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) {// 自动验证,失败返回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://www.pswp.cn/news/921377.shtml
繁体地址,请注明出处:http://hk.pswp.cn/news/921377.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

怎样让外网计算机访问局域网计算机?通过公网地址访问不同内网服务的设置方法

局域网服务器提供公网访问&#xff0c;或指定某些端口应用资源给外地访问&#xff0c;都是常见跨网通信需求。在一些场景下&#xff0c;内部网络中的服务器需要通过公网地址进行访问&#xff0c;尤其是在没有固定公网IP或需要在外部访问时。为了解决这一问题&#xff0c;可以使…

Spring Boot启动失败从循环依赖到懒加载配置的深度排查指南

&#x1f49d;&#x1f49d;&#x1f49d;欢迎莅临我的博客&#xff0c;很高兴能够在这里和您见面&#xff01;希望您在这里可以感受到一份轻松愉快的氛围&#xff0c;不仅可以获得有趣的内容和知识&#xff0c;也可以畅所欲言、分享您的想法和见解。 持续学习&#xff0c;不断…

从零开始学大模型之大语言模型

大语言模型 4.1 什么是 LLM 在前三章&#xff0c;我们从 NLP 的定义与主要任务出发&#xff0c;介绍了引发 NLP 领域重大变革的核心思想——注意力机制与 Transformer 架构。随着 Transformer 架构的横空出世&#xff0c;NLP 领域逐步进入预训练-微调范式&#xff0c;以 Tran…

如何将视频从 iPhone 转移到 Mac

将视频从 iPhone 转移到 Mac 是许多用户常见的需求。无论你是想备份重要的视频&#xff0c;还是希望在更大的屏幕上观看&#xff0c;以下方法都能帮助你轻松完成。方法一&#xff1a;使用 iReaShare iPhone ManageriReaShare iPhone Manager 是一款功能强大的工具&#xff0c;可…

五、Docker 核心技术:容器数据持久化之数据卷

Docker 容器本身是无状态且生命周期短暂的。当一个容器被删除时&#xff0c;它在可写层产生的所有数据都会随之消失。这对于需要持久化存储数据的应用 (如数据库、日志系统、用户上传内容) 来说是不可接受的。为了解决这个问题&#xff0c;Docker 提供了多种数据持久化方案&…

前端视觉交互设计全解析:从悬停高亮到多维交互体系(含代码 + 图表)

在前端用户体验领域&#xff0c;视觉交互是连接用户与产品的 “隐形桥梁”—— 它通过可视化信号传递操作意图、反馈系统状态&#xff0c;直接决定用户对产品的感知。很多开发者对视觉交互的认知停留在 “鼠标悬停高亮”&#xff0c;但实际上&#xff0c;视觉交互是一个覆盖 “…

从零打造商业级LLMOps平台:开源项目LMForge详解,助力多模型AI Agent开发!

最近&#xff0c;我发现了一个超级实用的开源项目——LMForge-End-to-End-LLMOps-Platform-for-Multi-Model-Agents&#xff08;以下简称LMForge&#xff09;。这个项目是一个端到端的LLMOps&#xff08;Large Language Model Operations&#xff09;平台&#xff0c;专为多模型…

【C++练习】06.输出100以内的所有素数

目录输出100以内的所有素数方法1&#xff1a;基础判断法方法2&#xff1a;埃拉托斯特尼筛法&#xff08;效率更高&#xff09;方法3&#xff1a;优化版筛法&#xff08;只考虑奇数&#xff09;方法4&#xff1a;使用STL算法方法5&#xff1a;递归实现总结&#xff1a; 输出100以…

在开发中使用git rebase的场景

rebase介绍 一、背景 远程仓库有oh4w-dev和oh4k-dev两个分支&#xff0c;oh4k-dev是基于oh4w-dev开发到80%的代码新拉的分支&#xff1b;此后两条分支同步开发&#xff0c;当oh4k-dev开发完成&#xff0c;oh4w-dev还在开发阶段&#xff0c;oh4k-dev需要拉取到oh4w-dev自分出o…

TDengine 时序函数 NOW() 用户手册

TDengine NOW() 函数用户使用手册 目录 功能概述函数语法返回值说明技术特性使用场景及示例时间运算操作注意事项常见问题 功能概述 NOW() 函数是 TDengine 中的时间函数&#xff0c;用于获取客户端当前系统时间。该函数在时序数据库中特别有用&#xff0c;可以用于数据插入…

JavaWeb ——事务管理

文章目录事务管理事务回顾Spring事务管理事务进阶事务属性 - 回滚 rollbackFor事务属性 - 传播行为 propagationSpring框架第一大核心: IOC控制反转&#xff0c; 其第二大核心就是 AOP 面向切面编程 事务管理 事务回顾 Spring事务管理 # spring 事务管理日志 logging:level:org…

【跨国数仓迁移最佳实践8】MaxCompute Streaming Insert: 大数据数据流写业务迁移的实践与突破

本系列文章将围绕东南亚头部科技集团的真实迁移历程展开&#xff0c;逐步拆解 BigQuery 迁移至 MaxCompute 过程中的关键挑战与技术创新。本篇为第八篇&#xff0c;MaxCompute Streaming Insert&#xff1a; 大数据数据流写业务迁移的实践与突破。注&#xff1a;客户背景为东南…

2025-09-05 CSS4——浮动与定位

文章目录1 显示&#xff08;Display&#xff09;1.1 visibility:hidden1.2 display:none2 块和内联元素2.1 块元素2.2 内联元素2.3 改变元素的显示方式3 浮动&#xff08;Float&#xff09;3.1 float 属性3.2 clear 属性4 定位&#xff08;Position&#xff09;4.1 五种定位模式…

43这周打卡——生成手势图像 (可控制生成)

目录 前言 1.导入数据及数据可视化 2.构建模型 3.训练模型 4.模型分析并生成指定图像 总结 前言 &#x1f368; 本文为&#x1f517;365天深度学习训练营中的学习记录博客&#x1f356; 原作者&#xff1a;K同学啊 1.导入数据及数据可视化 from torchvision import data…

TDengine 时间函数 TIMEDIFF() 用户手册

TDengine TIMEDIFF() 函数详细使用手册 目录 功能概述函数语法参数说明返回值说明版本变更说明技术特性使用场景及示例时间单位处理数据类型兼容性注意事项常见问题最佳实践 功能概述 TIMEDIFF() 函数用于计算两个时间戳的差值&#xff0c;返回 expr1 - expr2 的结果。结果…

【2025ICCV-持续学习方向】一种用于提示持续学习(Prompt-based Continual Learning, PCL)的新方法

1. 背景与问题 (Background & Problem):​​ ​持续学习 (CL):​​ 目标是在不遗忘旧任务知识的情况下,让模型持续学习一系列新任务。主要挑战是灾难性遗忘。 ​基于提示的持续学习 (PCL):​​ 利用预训练视觉Transformer (ViT),冻结其权重,通过微调称为“提示”(prompt…

2025 年 08 月 GitHub 十大热门项目排行榜

欢迎来到 2025 年 8 月 GitHub 热门开源项目排行榜&#xff01;本月榜单集中展示了来自智能体平台、AI 编程助手、多模态角色系统、本地化部署工具到可视化白板与企业协同平台的多元创新。从构建 AI 助手中枢的 Archon&#xff0c;到终端 AI 编码拍档 Crush&#xff0c;再到虚拟…

LeetCode每日一题,2025-9-4

多数元素 投票法 让你找到序列中出现超过二分之一的元素&#xff0c;一定要记住这个规则。 记录两个值val和cnt&#xff0c;刚开始val为任意数&#xff0c;cnt0。 如果cnt是0&#xff0c;就把当前val num。接下来判断&#xff0c;ifnum val&#xff0c;则cnt &#xff0c;e…

第7章 安全配置

7.1 安全概述 Jenkins安全威胁 常见安全风险&#xff1a; 访问控制风险&#xff1a; - 未授权访问Jenkins实例 - 权限提升攻击 - 横向移动攻击 - 敏感信息泄露代码执行风险&#xff1a; - 恶意脚本注入 - 构建脚本篡改 - 插件漏洞利用 - 远程代码执行数据安全风险&#xff1a; …

腾讯混元世界模型Voyager开源:单图生成3D世界的“核弹级”突破,游戏、VR、自动驾驶迎来新变量

当AI绘画、视频生成技术逐渐从“新鲜感”走向“实用化”&#xff0c;3D内容生成却始终卡在“效率低、成本高、门槛高”的瓶颈里。传统3D建模需要专业软件、大量人工调整&#xff0c;甚至依赖昂贵的硬件设备&#xff0c;让中小团队和个人创作者望而却步。 但腾讯AI实验室最近开…