当前位置： 首页 > news >正文

Spring Boot HTTP状态码详解

news 2025/9/6 1:59:05

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) {// 自动验证，失败返回400userService.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 状态码选择指南

操作类型成功状态码失败状态码
查询(GET)200 OK404 Not Found
创建(POST)201 Created400 Bad Request
更新(PUT)200 OK404 Not Found
删除(DELETE)204 No Content404 Not Found
部分更新(PATCH)200 OK400 Bad Request

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枚举包含的所有状态码的完整参考表格：

状态码枚举常量状态系列含义描述使用场景
100CONTINUEINFORMATIONAL继续客户端应继续发送请求的剩余部分
101SWITCHING_PROTOCOLSINFORMATIONAL切换协议WebSocket连接升级、HTTP/2协议切换
102PROCESSINGINFORMATIONAL处理中长时间运行的操作，如大数据处理
103EARLY_HINTSINFORMATIONAL早期提示预加载资源，优化页面加载性能
103CHECKPOINTINFORMATIONAL检查点（已弃用）已弃用，使用EARLY_HINTS替代
200OKSUCCESSFUL成功GET请求成功返回数据
201CREATEDSUCCESSFUL已创建POST请求创建新资源
202ACCEPTEDSUCCESSFUL已接受异步操作，如批量处理
203NON_AUTHORITATIVE_INFORMATIONSUCCESSFUL非权威信息代理服务器修改了响应
204NO_CONTENTSUCCESSFUL无内容DELETE操作成功、UPDATE操作无需返回数据
205RESET_CONTENTSUCCESSFUL重置内容客户端需要重置文档视图
206PARTIAL_CONTENTSUCCESSFUL部分内容分片下载、断点续传
207MULTI_STATUSSUCCESSFUL多状态WebDAV扩展，多个操作状态
208ALREADY_REPORTEDSUCCESSFUL已报告WebDAV，成员已在之前报告中
226IM_USEDSUCCESSFULIM已使用服务器已对请求进行了实例操作
300MULTIPLE_CHOICESREDIRECTION多种选择请求的资源有多个表示形式
301MOVED_PERMANENTLYREDIRECTION永久移动资源已永久移动到新位置
302FOUNDREDIRECTION临时移动资源临时移动到其他位置
302MOVED_TEMPORARILYREDIRECTION临时移动（已弃用）已弃用，使用FOUND替代
303SEE_OTHERREDIRECTION查看其他POST成功后重定向到GET请求
304NOT_MODIFIEDREDIRECTION未修改资源未修改，可使用缓存版本
305USE_PROXYREDIRECTION使用代理（已弃用）已弃用
307TEMPORARY_REDIRECTREDIRECTION临时重定向请求应使用另一个URI重复
308PERMANENT_REDIRECTREDIRECTION永久重定向请求和所有未来请求应使用另一个URI
400BAD_REQUESTCLIENT_ERROR错误请求请求语法错误或参数无效
401UNAUTHORIZEDCLIENT_ERROR未授权需要身份验证
402PAYMENT_REQUIREDCLIENT_ERROR需要付款保留用于未来支付系统
403FORBIDDENCLIENT_ERROR禁止访问权限不足、IP限制
404NOT_FOUNDCLIENT_ERROR未找到请求的资源不存在
405METHOD_NOT_ALLOWEDCLIENT_ERROR方法不允许请求方法不被允许
406NOT_ACCEPTABLECLIENT_ERROR不可接受服务器无法生成客户端接受的内容
407PROXY_AUTHENTICATION_REQUIREDCLIENT_ERROR需要代理认证代理服务器需要认证
408REQUEST_TIMEOUTCLIENT_ERROR请求超时服务器等待请求超时
409CONFLICTCLIENT_ERROR冲突请求与当前资源状态冲突
410GONECLIENT_ERROR已删除资源已永久删除
411LENGTH_REQUIREDCLIENT_ERROR需要长度需要Content-Length头
412PRECONDITION_FAILEDCLIENT_ERROR前提条件失败请求头中前提条件失败
413PAYLOAD_TOO_LARGECLIENT_ERROR负载过大请求实体过大
413REQUEST_ENTITY_TOO_LARGECLIENT_ERROR请求实体过大（已弃用）已弃用，使用PAYLOAD_TOO_LARGE
414URI_TOO_LONGCLIENT_ERRORURI过长请求URI过长
414REQUEST_URI_TOO_LONGCLIENT_ERROR请求URI过长（已弃用）已弃用，使用URI_TOO_LONG
415UNSUPPORTED_MEDIA_TYPECLIENT_ERROR不支持的媒体类型不支持的媒体格式
416REQUESTED_RANGE_NOT_SATISFIABLECLIENT_ERROR请求范围不可满足无法满足请求的范围
417EXPECTATION_FAILEDCLIENT_ERROR期望失败无法满足Expect请求头
418I_AM_A_TEAPOTCLIENT_ERROR我是茶壶HTTP愚人节笑话，实际不使用
419INSUFFICIENT_SPACE_ON_RESOURCECLIENT_ERROR资源空间不足（已弃用）已弃用
420METHOD_FAILURECLIENT_ERROR方法失败（已弃用）已弃用
421DESTINATION_LOCKEDCLIENT_ERROR目标锁定（已弃用）已弃用
422UNPROCESSABLE_ENTITYCLIENT_ERROR不可处理的实体请求格式正确但语义错误
423LOCKEDCLIENT_ERROR已锁定资源被锁定
424FAILED_DEPENDENCYCLIENT_ERROR依赖失败WebDAV，依赖的操作失败
425TOO_EARLYCLIENT_ERROR太早服务器不愿意处理可能重放的请求
426UPGRADE_REQUIREDCLIENT_ERROR需要升级客户端应切换到不同的协议
428PRECONDITION_REQUIREDCLIENT_ERROR需要前提条件需要条件性请求
429TOO_MANY_REQUESTSCLIENT_ERROR请求过多API限流、防刷机制
431REQUEST_HEADER_FIELDS_TOO_LARGECLIENT_ERROR请求头字段过大请求头字段太大
451UNAVAILABLE_FOR_LEGAL_REASONSCLIENT_ERROR因法律原因不可用因法律要求无法提供
500INTERNAL_SERVER_ERRORSERVER_ERROR内部服务器错误服务器内部错误
501NOT_IMPLEMENTEDSERVER_ERROR未实现服务器不支持请求的功能
502BAD_GATEWAYSERVER_ERROR错误网关网关或代理服务器收到无效响应
503SERVICE_UNAVAILABLESERVER_ERROR服务不可用系统维护、过载保护
504GATEWAY_TIMEOUTSERVER_ERROR网关超时上游服务响应超时
505HTTP_VERSION_NOT_SUPPORTEDSERVER_ERRORHTTP版本不支持不支持的HTTP协议版本
506VARIANT_ALSO_NEGOTIATESSERVER_ERROR变体也可协商透明内容协商中的循环引用
507INSUFFICIENT_STORAGESERVER_ERROR存储空间不足WebDAV，存储空间不足
508LOOP_DETECTEDSERVER_ERROR检测到循环WebDAV，检测到无限循环
509BANDWIDTH_LIMIT_EXCEEDEDSERVER_ERROR带宽限制超出带宽使用超出限制
510NOT_EXTENDEDSERVER_ERROR未扩展需要进一步扩展才能完成请求
511NETWORK_AUTHENTICATION_REQUIREDSERVER_ERROR需要网络认证需要网络认证才能访问

表格说明：

  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状态码。如有疑问，欢迎留言讨论！


文章转载自：

http://BDLIqnng.tsgxz.cn
http://4IM0FVwn.tsgxz.cn
http://ADDFIJAv.tsgxz.cn
http://Fv8WFoOq.tsgxz.cn
http://2RH7ytfu.tsgxz.cn
http://cVlg54eW.tsgxz.cn
http://UrdBfnfV.tsgxz.cn
http://NvLmVrp7.tsgxz.cn
http://npMW6SXy.tsgxz.cn
http://u7WvLKwm.tsgxz.cn
http://9eAMeQ45.tsgxz.cn
http://R9q7hcic.tsgxz.cn
http://z4rKzRnd.tsgxz.cn
http://NRbgXcyg.tsgxz.cn
http://DBPgPIH9.tsgxz.cn
http://XPNwLxXW.tsgxz.cn
http://knvWbpzF.tsgxz.cn
http://cHgrPEiQ.tsgxz.cn
http://qSfc7tus.tsgxz.cn
http://tAy0MzUf.tsgxz.cn
http://ZieQN9Qt.tsgxz.cn
http://FDV3BLa0.tsgxz.cn
http://7SUDsgKt.tsgxz.cn
http://1QdKZRSO.tsgxz.cn
http://TlKKeksi.tsgxz.cn
http://6GjutTQp.tsgxz.cn
http://WUE6D2wR.tsgxz.cn
http://VhQfP7b9.tsgxz.cn
http://dNkX8VrE.tsgxz.cn
http://jytqpmpY.tsgxz.cn
http://www.dtcms.com/a/365944.html

相关文章：

  • 性能测试-jmeter8-脚本录制
  • 揭秘23种设计模式的艺术与技巧
  • ＜ 自用文 主机 USC 记录：＞ 发现正在被攻击 后的自救
  • Protocol Buffers：数据世界的秘语之书，手把手教学环境搭建
  • mysql高级进阶（存储过程）
  • 认识HTML
  • CDN的工作原理是什么？为什么要用高防 CDN？
  • 数据结构：双向链表
  • 分割回文串手绘图
  • 电脑城老板不会告诉你的装机秘籍：建造者模式让你的代码高配起飞！
  • @Autowired原理(三)
  • 【Qt中信号槽连接connect有接收者和无接收者的区别】
  • LeetCode 20.有效的符号算法解析及栈的相关知识
  • FTL文件格式的原理与应用（AI）
  • 【工具变量】上市公司绿色供应链管理示范企业DID数据（2010-2024年）
  • AUTOSAR进阶图解==＞AUTOSAR_TPS_ARXMLSerializationRules
  • Linux学习-硬件
  • 2025年IT行业入门级证书选择与分析
  • 从竞态到原子：pread/pwrite 如何重塑高效文件 I/O？
  • 深入浅出：YOLOv8性能评估指标与电科金仓2025AI新成果
  • SuperMap GIS基础产品FAQ集锦(20250819)
  • C++----模板特化以及模板声明与定义分离问题
  • 2025 大学生必考 IT 行业证书
  • BigemapPro中的坐标定位于与拾取
  • NuttX编译流程与config.h生成解析
  • STM32G4 电流环闭环
  • Springboot3+SpringSecurity6Oauth2+vue3前后端分离认证授权-授权服务
  • 后端框架（SpringBoot）：自动配置的底层执行流程
  • 2025年经管专业人士证书选择与分析
  • 深入理解Cloudflare错误1006、1007和1008：原因、解决方案和预防措施