开发者在Spring Boot中编写REST API时常犯的10个错误

开发者在Spring Boot中编写REST API时常犯的10个错误

1. HTTP状态码
   • 错误：对每个响应都始终返回200 OK，即使是发生错误时也是如此。
   • 例如，在响应体中返回带有错误消息的200响应，而不是使用400 Bad Request（请求错误）或404 Not Found（未找到）。
   • 修复方法：使用合适的HTTP状态码，例如：
     • 201 - 创建成功时使用，用于成功创建资源。
     • 400 - 验证错误时使用，用于请求数据验证失败。
     • 404 - 资源缺失时使用，用于未找到请求的资源。
     • 500 - 内部服务器错误时使用，用于处理意外问题。
2. 未进行正确的请求验证
   • 错误：在未验证传入数据的情况下就直接信任它。
   • 示例：未经检查就接受无效数据，从而导致后续流程出现错误。
   • 修复方法：在数据传输对象（DTO）上使用@Valid和@Validated注解，并结合Spring的BindingResult进行详细的错误处理。
     
3. 忽视API版本控制
   • 错误：开发API时不进行版本控制，这会使向后兼容性难以管理。
   • 修复方法：通过以下方式实现API版本控制：
     • URI版本控制（例如，/v1/users）。
     • 头部版本控制（例如，Accept: application/vnd.company.app - v1 + json）。
       
4. 硬编码端点和URL
   • 错误：在代码中直接编写URL、路径或服务地址。
   • 修复方法：使用属性文件（application.yml）来外部化配置，并通过@Value或Environment读取配置。
     
5. 异常处理不当
   • 错误：让异常直接传播到客户端，而没有提供结构化的响应。
   • 修复方法：使用@ControllerAdvice和@ExceptionHandler来标准化错误处理。
     
6. 数据传输对象（DTO）与实体映射过于复杂
   • 错误：在API响应中直接暴露数据库实体。
   • 修复方法：使用数据传输对象（DTO）来解耦API层与数据库模式。可以使用像MapStruct或ModelMapper这样的库来进行映射。

@Mapper(componentModel = "spring")
public interface EmployeeMapper{
    @Mapping(source = "name", target = "fullName")
    EmployeeDTO toDto(Employee employee);
    @Mapping(source = "fullName", target = "name")
    EmployeeDTO toEntity(Employee employee);
}

7. 忽视分页和过滤
   • 错误：在单个响应中返回所有记录，这会导致性能问题。
   • 修复方法：使用Spring Data的Pageable和查询参数实现分页和过滤。

@GetMapping("/employees")
public Page<Employee> getEmployees(Pageable pageable){
    return repository.findAll(pageable);
}

8. 忽视安全最佳实践
   • 错误：暴露API却不进行安全防护，导致未经授权的访问。
   • 修复方法：
     • 使用Spring Security来保护端点。
     • 实现OAuth2或JWT进行身份验证和授权。
     • 避免在响应中暴露敏感信息（例如，密码、内部ID）。
9. 忽略API文档
   • 错误：不编写API文档，这会给其他开发者带来困惑。
   • 修复方法：
     • 使用Swagger/OpenAPI等工具自动生成文档。
     • 添加Swagger依赖并进行配置。
10. 忘记使用HATEOAS
    • 错误：返回的纯JSON数据中没有导航链接。
    • 修复方法：使用Spring HATEOAS在返回数据中包含资源操作链接（例如，自链接、相关资源链接）。

{
    "id": 1,
    "name": "John Doe",
    "role": "Developer",
    "_links": {
        "self": { "href": "http://localhost:8080/employees/1" },
        "all-employees": { "href": "http://localhost:8080/employees" }
    }
}