1. 忽略正确的 HTTP 状态码

许多开发者对每个响应都返回 200 OK，即使在错误情况下也是如此。这使得调试变得困难，并破坏了 RESTful 约定。

✅ 解决方案：
使用适当的状态码来传达正确的响应类型：

• 200 OK → 成功
• 201 Created → 资源已创建
• 400 Bad Request → 无效请求
• 401 Unauthorized → 认证失败
• 403 Forbidden → 权限不足
• 404 Not Found → 资源未找到
• 500 Internal Server Error → 服务器故障异常

@GetMapping("/users/{id}")
public ResponseEntity<User> getUser(@PathVariable Long id) {
    return userRepository.findById(id)
        .map(user -> ResponseEntity.ok(user)) // 200 OK
        .orElse(ResponseEntity.status(HttpStatus.NOT_FOUND).build()); // 404 Not Found
}

2. API 响应中暴露敏感数据

返回未过滤敏感字段的完整实体对象可能会暴露关键用户数据，如密码或令牌。

✅ 解决方案：使用 DTOs（数据传输对象）或 @JsonIgnore 注解来控制哪些数据被公开。

示例：

public class UserDTO {
    private String username;
    private String email;
}

代替暴露完整的 User 实体：

@GetMapping("/users/{id}")
public UserDTO getUser(@PathVariable Long id) {
    User user = userService.getUser(id);
    return new UserDTO(user.getUsername(), user.getEmail());
}

3. 正确处理异常

抛出通用异常会导致无结构的错误消息，这会混淆 API 用户。

✅ 解决方案：使用 @ControllerAdvice 来集中处理异常并返回一致的错误响应。

示例：

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<String> handleNotFound(ResourceNotFoundException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ex.getMessage());
    }
}

4. 设计不良的 API 端点

许多开发者设计的 REST API 不遵循适当规范，例如：

❌ 在 URL 中使用动词（ /getUser ， /updateUser ）
❌ 使用不一致的命名（ /user ， /users ）

✅ 解决方案：遵循 RESTful 最佳实践：

• • 使用名词表示资源（ /users 而不是 /getUser ）
• • 使用复数形式（ /users 而不是 /user ）
• • 使用子资源进行关系（ /users/{id}/orders ）

示例：

@GetMapping("/users/{id}") // ✅ Correct
public ResponseEntity<User> getUser(@PathVariable Long id) { ... }

5. 未实现分页和筛选

一次性获取所有记录可能会超载数据库并降低性能。

✅ 解决方案：使用 Spring Data Pageable 进行分页和过滤。

示例：

@GetMapping("/users")
public Page<User> getUsers(@RequestParam(defaultValue = "0") int page,
                           @RequestParam(defaultValue = "10") int size) {
    return userRepository.findAll(PageRequest.of(page, size));
}

6. 不使用缓存处理重复请求

APIs 频繁返回相同数据的可以受益于缓存，以减少响应时间和数据库负载。

✅ 解决方案：使用 Spring Cache 存储频繁访问的数据。

示例：

@Cacheable("users")
@GetMapping("/users/{id}")
public User getUser(@PathVariable Long id) {
    return userService.getUser(id);
}

7. 未正确保护 API

将您的 API 端点保持未受保护会使它们容易受到未经授权的访问。

✅ 解决方案：使用 Spring Security + JWT 进行身份验证和授权。

示例：

@EnableWebSecurity
public class SecurityConfig {
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http.csrf().disable()
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/admin/**").hasRole("ADMIN")
                .requestMatchers("/users/**").authenticated()
                .anyRequest().permitAll())
            .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS);
        return http.build();
    }
}

最后思考

避免这些常见错误将帮助您构建更安全、可维护和高效的 Spring Boot REST API。遵循最佳实践，例如使用适当的 HTTP 状态码、正确处理异常、实现缓存以及保护您的端点。

通过优化您的 API 设计，您将为开发人员和最终用户创造更好的体验。