Spring Boot HTTP状态码详解

Spring Boot HTTP状态码完全指南：从入门到精通

前言

在RESTful API开发中，HTTP状态码是与客户端通信的重要桥梁。Spring Boot通过HttpStatus枚举提供了完整的HTTP状态码支持。本文将深入解析这些状态码的含义、使用场景以及在Spring Boot中的最佳实践。

1. 信息响应 (100-199) - 请求处理中

1.1 CONTINUE (100)

• 含义：客户端应继续发送请求的剩余部分
• 使用场景：当客户端发送Expect: 100-continue头时，服务器确认可以接收请求体
• Spring Boot示例：大文件上传时的预检确认

1.2 SWITCHING_PROTOCOLS (101)

• 含义：服务器同意客户端请求，切换协议
• 使用场景：WebSocket连接升级、HTTP/2协议切换

1.3 PROCESSING (102)

• 含义：服务器已收到请求，正在处理但尚未完成
• 使用场景：长时间运行的操作，如大数据处理

1.4 EARLY_HINTS (103)

• 含义：用于在最终响应之前发送一些HTTP头
• 使用场景：预加载资源，优化页面加载性能

2. 成功响应 (200-299) - 请求成功处理

2.1 OK (200) ✅

• 含义：请求成功
• 使用场景：GET请求成功返回数据
• Spring Boot示例：

@GetMapping("/users/{id}")
public ResponseEntity<User> getUser(@PathVariable Long id) {
    User user = userService.findById(id);
    return ResponseEntity.ok(user); // 返回200状态码
}

2.2 CREATED (201) 🆕

• 含义：资源创建成功
• 使用场景：POST请求创建新资源
• 最佳实践：应在响应头中包含新资源的Location

@PostMapping("/users")
public ResponseEntity<User> createUser(@RequestBody User user) {
    User savedUser = userService.save(user);
    return ResponseEntity
        .created(URI.create("/users/" + savedUser.getId()))
        .body(savedUser);
}

2.3 ACCEPTED (202) ⏳

• 含义：请求已接受，但处理尚未完成
• 使用场景：异步操作，如批量处理、邮件发送

2.4 NO_CONTENT (204) 🚫

• 含义：请求成功，但无内容返回
• 使用场景：DELETE操作成功、UPDATE操作无需返回数据

@DeleteMapping("/users/{id}")
public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
    userService.deleteById(id);
    return ResponseEntity.noContent().build(); // 返回204
}

2.5 PARTIAL_CONTENT (206) 📦

• 含义：部分内容请求成功
• 使用场景：分片下载、断点续传

3. 重定向响应 (300-399) - 需要进一步操作

3.1 MOVED_PERMANENTLY (301) 🔄

• 含义：资源已永久移动到新位置
• 使用场景：网站改版、API版本迁移

3.2 FOUND (302) 🔍

• 含义：资源临时移动到其他位置
• 使用场景：临时重定向，如登录后跳转

3.3 SEE_OTHER (303) 👀

• 含义：查看其他URI获取响应
• 使用场景：POST成功后重定向到GET请求

3.4 NOT_MODIFIED (304) 📄

• 含义：资源未修改，可使用缓存版本
• 使用场景：配合If-Modified-Since或ETag使用

4. 客户端错误 (400-499) - 客户端请求有问题

4.1 BAD_REQUEST (400) ❌

• 含义：请求语法错误或参数无效
• 使用场景：参数验证失败、JSON格式错误
• Spring Boot验证示例：

@PostMapping("/users")
public ResponseEntity<?> createUser(
    @Valid @RequestBody UserCreateRequest request) {
    // 自动验证，失败返回400
    userService.create(request);
    return ResponseEntity.ok().build();
}

4.2 UNAUTHORIZED (401) 🔐

• 含义：需要身份验证
• 使用场景：未提供认证信息或认证失败

4.3 FORBIDDEN (403) ⚠️

• 含义：服务器理解请求但拒绝执行
• 使用场景：权限不足、IP限制

4.4 NOT_FOUND (404) 🔍

• 含义：请求的资源不存在
• 使用场景：访问不存在的URL或资源ID

@GetMapping("/users/{id}")
public ResponseEntity<User> getUser(@PathVariable Long id) {
    return userService.findById(id)
        .map(ResponseEntity::ok)
        .orElse(ResponseEntity.notFound().build()); // 返回404
}

4.5 METHOD_NOT_ALLOWED (405) 🚷

• 含义：请求方法不被允许
• 使用场景：对只读资源执行POST操作

4.6 UNPROCESSABLE_ENTITY (422) 📝

• 含义：请求格式正确但语义错误
• 使用场景：业务规则验证失败，如邮箱已注册

4.7 TOO_MANY_REQUESTS (429) 🚦

• 含义：请求频率过高
• 使用场景：API限流、防刷机制

5. 服务器错误 (500-599) - 服务器处理失败

5.1 INTERNAL_SERVER_ERROR (500) 💥

• 含义：服务器内部错误
• 使用场景：未捕获的异常、数据库连接失败
• Spring Boot异常处理：

@RestControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ApiResponse<?>> handleException(Exception e) {
        log.error("服务器异常", e);
        return ResponseEntity
            .status(HttpStatus.INTERNAL_SERVER_ERROR)
            .body(ApiResponse.error(500, "系统繁忙，请稍后重试"));
    }
}

5.2 NOT_IMPLEMENTED (501) 🔧

• 含义：服务器不支持请求的功能
• 使用场景：未实现的API端点

5.3 BAD_GATEWAY (502) 🌐

• 含义：网关或代理服务器从上游服务器收到无效响应
• 使用场景：微服务调用失败

5.4 SERVICE_UNAVAILABLE (503) ⚡

• 含义：服务暂时不可用
• 使用场景：系统维护、过载保护

5.5 GATEWAY_TIMEOUT (504) ⏰

• 含义：网关超时
• 使用场景：上游服务响应超时

6. Spring Boot中的最佳实践

6.1 使用ResponseEntity精确控制状态码

@GetMapping("/custom")
public ResponseEntity<String> customResponse() {
    if (someCondition) {
        return ResponseEntity.status(HttpStatus.CREATED).body("Created");
    } else {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body("Not Found");
    }
}

6.2 统一的错误响应格式

@Data
public class ErrorResponse {
    private int status;
    private String error;
    private String message;
    private String path;
    private LocalDateTime timestamp;
    
    public ErrorResponse(HttpStatus status, String message, String path) {
        this.status = status.value();
        this.error = status.getReasonPhrase();
        this.message = message;
        this.path = path;
        this.timestamp = LocalDateTime.now();
    }
}

6.3 状态码选择指南

7. 常见问题解答

Q: 什么时候使用200 vs 204？

A: 当需要返回数据时用200，不需要返回数据时用204。

Q: 401和403的区别？

A: 401表示未认证（需要登录），403表示已认证但权限不足。

Q: 400和422的区别？

A: 400表示请求语法错误，422表示语法正确但业务逻辑错误。

8. 总结

正确地使用HTTP状态码是构建高质量RESTful API的关键。Spring Boot的HttpStatus枚举为我们提供了完整的支持：

1. 信息类状态码用于通信协商
2. 成功类状态码表示操作成功
3. 重定向类状态码处理资源位置变更
4. 客户端错误类状态码帮助客户端纠正请求
5. 服务器错误类状态码表示服务端问题

通过合理选择状态码并提供清晰的错误信息，可以大大提升API的可用性和开发者体验。

9. 完整HTTP状态码参考表格

以下是Spring Boot中HttpStatus枚举包含的所有状态码的完整参考表格：

表格说明：

1. 状态码系列说明:

   • INFORMATIONAL (100-199): 信息响应，请求处理中
   • SUCCESSFUL (200-299): 成功响应，请求成功处理
   • REDIRECTION (300-399): 重定向响应，需要进一步操作
   • CLIENT_ERROR (400-499): 客户端错误，客户端请求有问题
   • SERVER_ERROR (500-599): 服务器错误，服务器处理失败

2. 已弃用状态码: 表格中标记为"已弃用"的状态码不建议在新项目中使用

3. 常用状态码: 在实际开发中，最常用的状态码包括：200, 201, 204, 400, 401, 403, 404, 500

希望本文能帮助您更好地理解和使用Spring Boot中的HTTP状态码。如有疑问，欢迎留言讨论！