文章目录HTTP请求方法与状态码 全体系知识总结一、核心基础定义与设计原则1.1 协议定位1.2 核心设计原则二、HTTP请求方法2.1 核心属性对照表2.2 标准请求方法RFC 9110 定义2.2.1 核心常用方法高频开发/接口设计场景2.2.2 专用标准方法2.3 扩展请求方法2.4 易混淆方法对比与误区澄清三、HTTP状态码 1xx-5xx3.1 核心规则3.2 1xx 信息性状态码临时响应3.3 2xx 成功状态码3.4 3xx 重定向状态码3.4.1 核心码与场景3.4.2 易混淆码对比3.5 4xx 客户端错误状态码3.5.1 核心码与场景按场景分类3.5.2 易混淆码对比3.6 5xx 服务端错误状态码3.7 状态码使用最佳实践与误区澄清四、全体系工程化最佳实践RESTful API 落地规范4.1 请求方法语义化规范4.2 状态码语义化规范4.3 协同设计规范HTTP请求方法与状态码 全体系知识总结本文基于RFC 9110HTTP/1.1语义最新标准替代废弃的RFC 2616构建全方位结构化拆解HTTP请求方法、状态码的核心语义、分类规则、高频场景与工程化规范形成完整的知识体系。一、核心基础定义与设计原则1.1 协议定位HTTP是应用层的请求-响应式协议是Web通信的核心基石请求方法定义客户端对服务端资源的操作语义明确“要做什么”状态码定义服务端对请求的处理结果语义明确“做得怎么样”1.2 核心设计原则原则定义核心价值语义化方法/状态码必须严格遵循标准语义禁止自定义篡改保证客户端、服务端、网关、CDN、监控系统的全链路兼容性安全性方法不会修改服务端资源状态仅执行只读操作客户端无需承担副作用责任区分只读/写操作避免误触发资源变更幂等性同一请求执行1次和N次服务端资源状态完全一致客户端可安全重试解决网络超时、重复提交等场景的一致性问题二、HTTP请求方法2.1 核心属性对照表所有标准方法的安全/幂等属性严格遵循RFC规范是方法选型的核心依据方法安全方法幂等方法核心操作类型GET是是只读查询HEAD是是只读查询仅返回响应头OPTIONS是是能力查询/跨域预检TRACE是是链路诊断/环回测试PUT否是全量更新/创建资源DELETE否是删除资源POST否否提交实体/创建资源/通用处理PATCH否不强制保证增量更新资源CONNECT否否建立隧道代理2.2 标准请求方法RFC 9110 定义2.2.1 核心常用方法高频开发/接口设计场景GET核心语义从服务端获取指定资源仅执行只读操作核心场景接口数据查询、页面资源加载、搜索引擎抓取规范要求禁止用于修改资源的操作可带查询参数不建议带请求体多数客户端/服务端不兼容POST核心语义向服务端提交实体数据由服务端处理语义上不保证幂等核心场景新增资源、表单提交、文件上传、复杂查询带大体积请求体、非幂等的业务操作规范要求创建资源成功时优先返回201 Created而非200 OKPUT核心语义用请求体的完整实体全量覆盖服务端指定资源不存在则创建语义上强制幂等核心场景已知资源URI的全量更新、确定性的资源创建关键区别与POST的核心差异是幂等性资源URI由客户端指定与PATCH的差异是全量覆盖vs增量修改PATCH核心语义对服务端资源执行增量更新仅修改请求体指定的字段语义上不强制保证幂等核心场景大资源的局部修改、字段级别的更新如修改用户昵称、订单状态规范要求需带Content-Type指定补丁格式如application/merge-patchjsonDELETE核心语义删除服务端指定资源语义上强制幂等核心场景资源删除、数据注销规范要求删除成功优先返回204 No Content无需返回响应体HEAD核心语义与GET完全一致但服务端仅返回响应头不返回响应体核心场景检查资源是否存在、校验资源大小、测试接口连通性、预校验缓存有效性OPTIONS核心语义查询服务端对指定资源支持的请求方法、跨域权限等能力核心场景CORS跨域预检请求、服务端接口能力探测规范要求响应头必须带Allow字段明确支持的请求方法2.2.2 专用标准方法CONNECT核心语义与目标服务器建立TCP隧道通常用于HTTPS代理核心场景正向代理、HTTPS穿透、VPN隧道搭建TRACE核心语义服务端将收到的请求原封不动返回给客户端用于链路诊断核心场景排查代理/网关篡改请求的问题、定位请求链路故障安全提示生产环境通常禁用避免XST跨站追踪攻击2.3 扩展请求方法非HTTP核心标准定义由扩展协议补充仅用于特定场景WebDAV扩展COPY、MOVE、LOCK、UNLOCK、PROPFIND等用于文件管理系统CalDAV/CardDAV扩展用于日历、联系人同步协议自定义扩展需遵循HTTP语义禁止与标准方法冲突兼容性有限2.4 易混淆方法对比与误区澄清对比项核心差异选型建议POST vs PUTPOST非幂等资源URI由服务端生成PUT幂等资源URI由客户端指定新增资源用POST全量更新已知资源用PUTPUT vs PATCHPUT全量覆盖必须传完整资源实体强制幂等PATCH增量修改仅传变更字段不强制幂等全量更新用PUT局部字段修改用PATCHGET vs POSTGET安全幂等参数在URL有长度限制POST非安全非幂等参数在请求体无硬长度限制只读查询用GET提交/修改数据用POST常见误区澄清误区GET不能带请求体 → 规范未禁止但多数客户端/网关/服务器不支持生产环境严禁使用误区POST一定不幂等 → 语义上不保证幂等业务层可通过唯一请求ID实现幂等但不改变方法的标准语义误区PATCH一定是幂等的 → 仅当补丁内容是确定性覆盖时才幂等若为增量运算如count count 1则非幂等三、HTTP状态码 1xx-5xx3.1 核心规则HTTP状态码为3位数字第一位定义分类共5大类覆盖请求全生命周期的所有结果1xx信息性/临时响应请求已接收正在处理2xx成功请求已完整接收、理解并处理3xx重定向客户端需进一步操作完成请求4xx客户端错误请求存在语法/语义问题客户端需修正后重试5xx服务端错误服务端处理合法请求时发生故障责任在服务端3.2 1xx 信息性状态码临时响应核心语义服务端已接收请求正在处理仅为中间状态不代表最终结果HTTP/1.1强制要求客户端支持状态码标准名称核心场景规范要求100Continue大文件/大请求体上传客户端带Expect: 100-continue先发请求头服务端校验通过后返回100客户端再发送请求体避免带宽浪费仅当客户端带Expect头时可返回101Switching Protocols协议升级客户端带Upgrade头请求切换协议如HTTP→WebSocket、HTTP/1.1→HTTP/2服务端同意后返回必须带Upgrade和Connection响应头103Early Hints性能优化服务端处理HTML时提前返回响应头带Link头让浏览器预加载CSS/JS等静态资源提升首屏加载速度RFC 8297定义仅用于GET/HEAD请求3.3 2xx 成功状态码核心语义服务端已完整处理并完成客户端请求的动作是唯一代表请求成功的分类状态码标准名称核心场景规范要求200OK最通用成功码GET查询返回资源、POST提交成功返回结果、通用业务处理成功响应体携带对应资源/结果数据201Created资源创建成功POST/PUT新增用户、上传文件、创建订单等场景响应头必须带Location指向新资源的URI响应体可带资源信息202Accepted异步任务提交成功服务端已接收请求但未处理完成如批量任务、报表生成、消息推送、AI推理任务响应体需带任务进度查询地址禁止返回最终处理结果204No Content请求成功但无响应体PUT全量更新、DELETE删除成功、配置修改成功等无需返回内容的场景绝对不能带响应体仅返回响应头206Partial Content分片传输断点续传、视频分片加载、大文件分段下载客户端带Range头请求部分资源必须带Content-Range响应头明确返回的字节范围3.4 3xx 重定向状态码核心语义资源位置发生变更客户端需重新发起请求完成操作核心分为永久重定向、临时重定向、缓存重定向三大类核心差异是缓存行为和是否保留原请求方法3.4.1 核心码与场景状态码标准名称重定向类型核心场景关键特性301Moved Permanently永久重定向域名更换、页面路径永久变更、SEO权重转移浏览器会永久缓存重定向结果多数浏览器会将POST请求改为GET重定向308Permanent Redirect永久重定向POST资源的永久迁移、表单提交地址永久变更301的严格版永久保留原请求方法和请求体禁止修改POST为GET302Found临时重定向登录态失效跳登录页、活动临时跳转、临时维护跳转浏览器不缓存重定向结果多数浏览器会将POST请求改为GET重定向307Temporary Redirect临时重定向POST表单临时跳转、支付回调临时转发302的严格版临时保留原请求方法和请求体禁止修改POST为GET303See Other特殊重定向POST表单提交后跳结果页避免刷新重复提交PRG模式、下单成功跳订单详情强制客户端用GET方法请求新URI无论原请求方法是什么304Not Modified缓存重定向协商缓存客户端带If-Modified-Since/If-None-Match头资源未变更时返回无响应体客户端直接使用本地缓存仅返回缓存相关响应头3.4.2 易混淆码对比对比场景选型建议永久跳转普通页面跳转用301POST提交地址永久变更用308临时跳转普通页面跳转用302POST表单临时跳转用307表单提交后跳转必须用303避免用户刷新页面重复提交表单3.5 4xx 客户端错误状态码核心语义请求存在问题服务端无法/不会处理责任在客户端除HEAD请求外响应体必须携带明确的错误原因与修正方案3.5.1 核心码与场景按场景分类通用请求错误状态码标准名称核心场景400Bad Request通用客户端错误请求语法错误、JSON格式非法、参数缺失/类型不匹配、请求体无法解析405Method Not Allowed请求方法不被支持接口仅支持GET客户端使用POST/PUT等方法406Not Acceptable资源无法满足客户端的Accept头要求客户端要求返回XML服务端仅支持JSON408Request Timeout请求超时客户端请求发送过慢服务端等待超时关闭连接411Length Required缺少Content-Length头POST提交请求体未声明内容长度服务端无法处理413Payload Too Large请求体过大上传文件/提交数据超过服务端大小限制414URI Too Long请求URI过长GET请求参数超长超过服务端限制415Unsupported Media Type不支持的媒体类型客户端提交的Content-Type与接口要求不符416Range Not Satisfiable请求范围无效断点续传时请求的字节范围超过资源总长度431Request Header Fields Too Large请求头过大Cookie超长、自定义请求头超过服务端限制认证与授权错误状态码标准名称核心场景关键区别401Unauthorized未认证用户未登录、Token缺失/过期/无效服务端无法确认客户端身份语义是「未认证」不是「未授权」必须带WWW-Authenticate响应头声明认证方式403Forbidden无权限访问用户已认证但无操作权限、IP被封禁、资源禁止访问服务端已识别客户端身份但明确拒绝执行请求重试无效资源与业务错误状态码标准名称核心场景404Not Found资源不存在URL错误、资源已删除、接口路径写错、服务端无对应路由409Conflict资源冲突注册用户名已存在、乐观锁版本冲突、唯一约束违反、并发修改冲突410Gone资源永久删除资源曾经存在现已永久删除且不会恢复SEO场景专用412Precondition Failed前提条件失败乐观锁更新时If-Match头的ETag不匹配服务端拒绝并发修改422Unprocessable Entity语义错误请求格式正确但业务逻辑无法处理如手机号格式非法、密码长度不足、参数值不符合业务规则限流与访问控制错误状态码标准名称核心场景429Too Many Requests请求频率超限接口限流、防刷、爬虫拦截客户端请求次数超过服务端阈值3.5.2 易混淆码对比对比项核心差异选型建议400 vs 422400请求语法/格式错误服务端无法解析422请求格式正确服务端可解析但业务语义非法格式错误用400业务参数校验失败用422401 vs 403401未登录/身份无效「你是谁我不认识」403已登录但无权限「我认识你但你不能这么做」登录态问题用401权限问题用403404 vs 410404资源不存在原因未知410资源永久删除明确不会恢复临时/未知原因用404永久删除用4103.6 5xx 服务端错误状态码核心语义服务端处理合法请求时发生不可预期的错误无法完成请求责任在服务端客户端可重试请求状态码标准名称核心场景关键区别500Internal Server Error通用服务端错误代码未捕获异常、数据库报错、空指针、业务逻辑崩溃、依赖服务故障最常见的服务端错误生产环境禁止返回详细异常栈避免信息泄露501Not Implemented服务端未实现该请求方法客户端使用了服务端未支持的扩展方法与405的区别405是方法已知但不允许使用501是方法完全未实现502Bad Gateway网关错误反向代理Nginx/网关收到了上游服务的无效响应如上游服务宕机、连接被重置、进程崩溃上游服务已响应但响应内容非法503Service Unavailable服务不可用服务停机维护、流量过载熔断、数据库宕机、资源耗尽服务端明确告知暂时不可用响应头可带Retry-After声明恢复时间是临时故障504Gateway Timeout网关超时反向代理/网关等待上游服务响应超时如接口执行时间过长、慢查询、死锁上游服务未在超时时间内返回任何响应与502的核心差异是「超时vs无效响应」505HTTP Version Not Supported服务端不支持客户端使用的HTTP版本如客户端用HTTP/3服务端仅支持HTTP/1.13.7 状态码使用最佳实践与误区澄清核心规范严格遵循语义禁止所有请求都返回200再通过响应体自定义code会破坏HTTP语义导致CDN、缓存、监控、网关全链路异常优先使用标准状态码禁止自定义非标准状态码如460、555等标准码已覆盖99%的业务场景错误响应必须携带明确的错误信息4xx告知客户端修正方案5xx禁止泄露服务端敏感信息常见误区澄清误区401翻译为「未授权」→ 正确语义是「未认证」403才是「未授权/禁止访问」误区500就是代码bug → 500是通用服务端错误也可能是依赖服务故障、资源耗尽等问题误区304是客户端缓存触发的和服务端无关 → 304是服务端返回的状态码由服务端校验缓存有效性后决定是否返回四、全体系工程化最佳实践RESTful API 落地规范4.1 请求方法语义化规范CRUD操作严格对应标准方法GET查、POST增、PUT全量改、PATCH增量改、DELETE删只读操作必须使用安全方法GET/HEAD禁止用POST实现查询接口可重试的操作必须使用幂等方法PUT/DELETE/GET避免网络波动导致数据不一致跨域场景下非简单请求必须支持OPTIONS预检请求4.2 状态码语义化规范成功场景查询成功返回200创建成功返回201异步任务提交返回202删除/更新成功无返回内容用204重定向场景SEO永久跳转用301表单提交后跳转用303协商缓存用304客户端错误参数格式错误用400未登录用401无权限用403资源不存在用404业务参数校验失败用422限流用429服务端错误通用异常用500网关转发失败用502服务不可用用503上游超时用5044.3 协同设计规范幂等性设计POST创建接口必须通过唯一请求ID实现幂等PUT/DELETE接口严格保证幂等缓存设计静态资源用301Cache-Control强缓存动态接口用304协商缓存4xx/5xx错误禁止缓存可观测性监控系统按状态码分类统计重点监控4xx异常率、5xx错误率、3xx重定向率快速定位故障安全防护生产环境禁用TRACE方法401/403接口做访问控制429限流防止CC攻击5xx错误隐藏服务端细节
【HTTP】HTTP请求方法与状态码（全体系知识总结+附表格）
文章目录HTTP请求方法与状态码 全体系知识总结一、核心基础定义与设计原则1.1 协议定位1.2 核心设计原则二、HTTP请求方法2.1 核心属性对照表2.2 标准请求方法RFC 9110 定义2.2.1 核心常用方法高频开发/接口设计场景2.2.2 专用标准方法2.3 扩展请求方法2.4 易混淆方法对比与误区澄清三、HTTP状态码 1xx-5xx3.1 核心规则3.2 1xx 信息性状态码临时响应3.3 2xx 成功状态码3.4 3xx 重定向状态码3.4.1 核心码与场景3.4.2 易混淆码对比3.5 4xx 客户端错误状态码3.5.1 核心码与场景按场景分类3.5.2 易混淆码对比3.6 5xx 服务端错误状态码3.7 状态码使用最佳实践与误区澄清四、全体系工程化最佳实践RESTful API 落地规范4.1 请求方法语义化规范4.2 状态码语义化规范4.3 协同设计规范HTTP请求方法与状态码 全体系知识总结本文基于RFC 9110HTTP/1.1语义最新标准替代废弃的RFC 2616构建全方位结构化拆解HTTP请求方法、状态码的核心语义、分类规则、高频场景与工程化规范形成完整的知识体系。一、核心基础定义与设计原则1.1 协议定位HTTP是应用层的请求-响应式协议是Web通信的核心基石请求方法定义客户端对服务端资源的操作语义明确“要做什么”状态码定义服务端对请求的处理结果语义明确“做得怎么样”1.2 核心设计原则原则定义核心价值语义化方法/状态码必须严格遵循标准语义禁止自定义篡改保证客户端、服务端、网关、CDN、监控系统的全链路兼容性安全性方法不会修改服务端资源状态仅执行只读操作客户端无需承担副作用责任区分只读/写操作避免误触发资源变更幂等性同一请求执行1次和N次服务端资源状态完全一致客户端可安全重试解决网络超时、重复提交等场景的一致性问题二、HTTP请求方法2.1 核心属性对照表所有标准方法的安全/幂等属性严格遵循RFC规范是方法选型的核心依据方法安全方法幂等方法核心操作类型GET是是只读查询HEAD是是只读查询仅返回响应头OPTIONS是是能力查询/跨域预检TRACE是是链路诊断/环回测试PUT否是全量更新/创建资源DELETE否是删除资源POST否否提交实体/创建资源/通用处理PATCH否不强制保证增量更新资源CONNECT否否建立隧道代理2.2 标准请求方法RFC 9110 定义2.2.1 核心常用方法高频开发/接口设计场景GET核心语义从服务端获取指定资源仅执行只读操作核心场景接口数据查询、页面资源加载、搜索引擎抓取规范要求禁止用于修改资源的操作可带查询参数不建议带请求体多数客户端/服务端不兼容POST核心语义向服务端提交实体数据由服务端处理语义上不保证幂等核心场景新增资源、表单提交、文件上传、复杂查询带大体积请求体、非幂等的业务操作规范要求创建资源成功时优先返回201 Created而非200 OKPUT核心语义用请求体的完整实体全量覆盖服务端指定资源不存在则创建语义上强制幂等核心场景已知资源URI的全量更新、确定性的资源创建关键区别与POST的核心差异是幂等性资源URI由客户端指定与PATCH的差异是全量覆盖vs增量修改PATCH核心语义对服务端资源执行增量更新仅修改请求体指定的字段语义上不强制保证幂等核心场景大资源的局部修改、字段级别的更新如修改用户昵称、订单状态规范要求需带Content-Type指定补丁格式如application/merge-patchjsonDELETE核心语义删除服务端指定资源语义上强制幂等核心场景资源删除、数据注销规范要求删除成功优先返回204 No Content无需返回响应体HEAD核心语义与GET完全一致但服务端仅返回响应头不返回响应体核心场景检查资源是否存在、校验资源大小、测试接口连通性、预校验缓存有效性OPTIONS核心语义查询服务端对指定资源支持的请求方法、跨域权限等能力核心场景CORS跨域预检请求、服务端接口能力探测规范要求响应头必须带Allow字段明确支持的请求方法2.2.2 专用标准方法CONNECT核心语义与目标服务器建立TCP隧道通常用于HTTPS代理核心场景正向代理、HTTPS穿透、VPN隧道搭建TRACE核心语义服务端将收到的请求原封不动返回给客户端用于链路诊断核心场景排查代理/网关篡改请求的问题、定位请求链路故障安全提示生产环境通常禁用避免XST跨站追踪攻击2.3 扩展请求方法非HTTP核心标准定义由扩展协议补充仅用于特定场景WebDAV扩展COPY、MOVE、LOCK、UNLOCK、PROPFIND等用于文件管理系统CalDAV/CardDAV扩展用于日历、联系人同步协议自定义扩展需遵循HTTP语义禁止与标准方法冲突兼容性有限2.4 易混淆方法对比与误区澄清对比项核心差异选型建议POST vs PUTPOST非幂等资源URI由服务端生成PUT幂等资源URI由客户端指定新增资源用POST全量更新已知资源用PUTPUT vs PATCHPUT全量覆盖必须传完整资源实体强制幂等PATCH增量修改仅传变更字段不强制幂等全量更新用PUT局部字段修改用PATCHGET vs POSTGET安全幂等参数在URL有长度限制POST非安全非幂等参数在请求体无硬长度限制只读查询用GET提交/修改数据用POST常见误区澄清误区GET不能带请求体 → 规范未禁止但多数客户端/网关/服务器不支持生产环境严禁使用误区POST一定不幂等 → 语义上不保证幂等业务层可通过唯一请求ID实现幂等但不改变方法的标准语义误区PATCH一定是幂等的 → 仅当补丁内容是确定性覆盖时才幂等若为增量运算如count count 1则非幂等三、HTTP状态码 1xx-5xx3.1 核心规则HTTP状态码为3位数字第一位定义分类共5大类覆盖请求全生命周期的所有结果1xx信息性/临时响应请求已接收正在处理2xx成功请求已完整接收、理解并处理3xx重定向客户端需进一步操作完成请求4xx客户端错误请求存在语法/语义问题客户端需修正后重试5xx服务端错误服务端处理合法请求时发生故障责任在服务端3.2 1xx 信息性状态码临时响应核心语义服务端已接收请求正在处理仅为中间状态不代表最终结果HTTP/1.1强制要求客户端支持状态码标准名称核心场景规范要求100Continue大文件/大请求体上传客户端带Expect: 100-continue先发请求头服务端校验通过后返回100客户端再发送请求体避免带宽浪费仅当客户端带Expect头时可返回101Switching Protocols协议升级客户端带Upgrade头请求切换协议如HTTP→WebSocket、HTTP/1.1→HTTP/2服务端同意后返回必须带Upgrade和Connection响应头103Early Hints性能优化服务端处理HTML时提前返回响应头带Link头让浏览器预加载CSS/JS等静态资源提升首屏加载速度RFC 8297定义仅用于GET/HEAD请求3.3 2xx 成功状态码核心语义服务端已完整处理并完成客户端请求的动作是唯一代表请求成功的分类状态码标准名称核心场景规范要求200OK最通用成功码GET查询返回资源、POST提交成功返回结果、通用业务处理成功响应体携带对应资源/结果数据201Created资源创建成功POST/PUT新增用户、上传文件、创建订单等场景响应头必须带Location指向新资源的URI响应体可带资源信息202Accepted异步任务提交成功服务端已接收请求但未处理完成如批量任务、报表生成、消息推送、AI推理任务响应体需带任务进度查询地址禁止返回最终处理结果204No Content请求成功但无响应体PUT全量更新、DELETE删除成功、配置修改成功等无需返回内容的场景绝对不能带响应体仅返回响应头206Partial Content分片传输断点续传、视频分片加载、大文件分段下载客户端带Range头请求部分资源必须带Content-Range响应头明确返回的字节范围3.4 3xx 重定向状态码核心语义资源位置发生变更客户端需重新发起请求完成操作核心分为永久重定向、临时重定向、缓存重定向三大类核心差异是缓存行为和是否保留原请求方法3.4.1 核心码与场景状态码标准名称重定向类型核心场景关键特性301Moved Permanently永久重定向域名更换、页面路径永久变更、SEO权重转移浏览器会永久缓存重定向结果多数浏览器会将POST请求改为GET重定向308Permanent Redirect永久重定向POST资源的永久迁移、表单提交地址永久变更301的严格版永久保留原请求方法和请求体禁止修改POST为GET302Found临时重定向登录态失效跳登录页、活动临时跳转、临时维护跳转浏览器不缓存重定向结果多数浏览器会将POST请求改为GET重定向307Temporary Redirect临时重定向POST表单临时跳转、支付回调临时转发302的严格版临时保留原请求方法和请求体禁止修改POST为GET303See Other特殊重定向POST表单提交后跳结果页避免刷新重复提交PRG模式、下单成功跳订单详情强制客户端用GET方法请求新URI无论原请求方法是什么304Not Modified缓存重定向协商缓存客户端带If-Modified-Since/If-None-Match头资源未变更时返回无响应体客户端直接使用本地缓存仅返回缓存相关响应头3.4.2 易混淆码对比对比场景选型建议永久跳转普通页面跳转用301POST提交地址永久变更用308临时跳转普通页面跳转用302POST表单临时跳转用307表单提交后跳转必须用303避免用户刷新页面重复提交表单3.5 4xx 客户端错误状态码核心语义请求存在问题服务端无法/不会处理责任在客户端除HEAD请求外响应体必须携带明确的错误原因与修正方案3.5.1 核心码与场景按场景分类通用请求错误状态码标准名称核心场景400Bad Request通用客户端错误请求语法错误、JSON格式非法、参数缺失/类型不匹配、请求体无法解析405Method Not Allowed请求方法不被支持接口仅支持GET客户端使用POST/PUT等方法406Not Acceptable资源无法满足客户端的Accept头要求客户端要求返回XML服务端仅支持JSON408Request Timeout请求超时客户端请求发送过慢服务端等待超时关闭连接411Length Required缺少Content-Length头POST提交请求体未声明内容长度服务端无法处理413Payload Too Large请求体过大上传文件/提交数据超过服务端大小限制414URI Too Long请求URI过长GET请求参数超长超过服务端限制415Unsupported Media Type不支持的媒体类型客户端提交的Content-Type与接口要求不符416Range Not Satisfiable请求范围无效断点续传时请求的字节范围超过资源总长度431Request Header Fields Too Large请求头过大Cookie超长、自定义请求头超过服务端限制认证与授权错误状态码标准名称核心场景关键区别401Unauthorized未认证用户未登录、Token缺失/过期/无效服务端无法确认客户端身份语义是「未认证」不是「未授权」必须带WWW-Authenticate响应头声明认证方式403Forbidden无权限访问用户已认证但无操作权限、IP被封禁、资源禁止访问服务端已识别客户端身份但明确拒绝执行请求重试无效资源与业务错误状态码标准名称核心场景404Not Found资源不存在URL错误、资源已删除、接口路径写错、服务端无对应路由409Conflict资源冲突注册用户名已存在、乐观锁版本冲突、唯一约束违反、并发修改冲突410Gone资源永久删除资源曾经存在现已永久删除且不会恢复SEO场景专用412Precondition Failed前提条件失败乐观锁更新时If-Match头的ETag不匹配服务端拒绝并发修改422Unprocessable Entity语义错误请求格式正确但业务逻辑无法处理如手机号格式非法、密码长度不足、参数值不符合业务规则限流与访问控制错误状态码标准名称核心场景429Too Many Requests请求频率超限接口限流、防刷、爬虫拦截客户端请求次数超过服务端阈值3.5.2 易混淆码对比对比项核心差异选型建议400 vs 422400请求语法/格式错误服务端无法解析422请求格式正确服务端可解析但业务语义非法格式错误用400业务参数校验失败用422401 vs 403401未登录/身份无效「你是谁我不认识」403已登录但无权限「我认识你但你不能这么做」登录态问题用401权限问题用403404 vs 410404资源不存在原因未知410资源永久删除明确不会恢复临时/未知原因用404永久删除用4103.6 5xx 服务端错误状态码核心语义服务端处理合法请求时发生不可预期的错误无法完成请求责任在服务端客户端可重试请求状态码标准名称核心场景关键区别500Internal Server Error通用服务端错误代码未捕获异常、数据库报错、空指针、业务逻辑崩溃、依赖服务故障最常见的服务端错误生产环境禁止返回详细异常栈避免信息泄露501Not Implemented服务端未实现该请求方法客户端使用了服务端未支持的扩展方法与405的区别405是方法已知但不允许使用501是方法完全未实现502Bad Gateway网关错误反向代理Nginx/网关收到了上游服务的无效响应如上游服务宕机、连接被重置、进程崩溃上游服务已响应但响应内容非法503Service Unavailable服务不可用服务停机维护、流量过载熔断、数据库宕机、资源耗尽服务端明确告知暂时不可用响应头可带Retry-After声明恢复时间是临时故障504Gateway Timeout网关超时反向代理/网关等待上游服务响应超时如接口执行时间过长、慢查询、死锁上游服务未在超时时间内返回任何响应与502的核心差异是「超时vs无效响应」505HTTP Version Not Supported服务端不支持客户端使用的HTTP版本如客户端用HTTP/3服务端仅支持HTTP/1.13.7 状态码使用最佳实践与误区澄清核心规范严格遵循语义禁止所有请求都返回200再通过响应体自定义code会破坏HTTP语义导致CDN、缓存、监控、网关全链路异常优先使用标准状态码禁止自定义非标准状态码如460、555等标准码已覆盖99%的业务场景错误响应必须携带明确的错误信息4xx告知客户端修正方案5xx禁止泄露服务端敏感信息常见误区澄清误区401翻译为「未授权」→ 正确语义是「未认证」403才是「未授权/禁止访问」误区500就是代码bug → 500是通用服务端错误也可能是依赖服务故障、资源耗尽等问题误区304是客户端缓存触发的和服务端无关 → 304是服务端返回的状态码由服务端校验缓存有效性后决定是否返回四、全体系工程化最佳实践RESTful API 落地规范4.1 请求方法语义化规范CRUD操作严格对应标准方法GET查、POST增、PUT全量改、PATCH增量改、DELETE删只读操作必须使用安全方法GET/HEAD禁止用POST实现查询接口可重试的操作必须使用幂等方法PUT/DELETE/GET避免网络波动导致数据不一致跨域场景下非简单请求必须支持OPTIONS预检请求4.2 状态码语义化规范成功场景查询成功返回200创建成功返回201异步任务提交返回202删除/更新成功无返回内容用204重定向场景SEO永久跳转用301表单提交后跳转用303协商缓存用304客户端错误参数格式错误用400未登录用401无权限用403资源不存在用404业务参数校验失败用422限流用429服务端错误通用异常用500网关转发失败用502服务不可用用503上游超时用5044.3 协同设计规范幂等性设计POST创建接口必须通过唯一请求ID实现幂等PUT/DELETE接口严格保证幂等缓存设计静态资源用301Cache-Control强缓存动态接口用304协商缓存4xx/5xx错误禁止缓存可观测性监控系统按状态码分类统计重点监控4xx异常率、5xx错误率、3xx重定向率快速定位故障安全防护生产环境禁用TRACE方法401/403接口做访问控制429限流防止CC攻击5xx错误隐藏服务端细节
