哪种语言做网站好,自己建设一个网站,恩施网站定制,太原市网站建设文章目录写在前面问题描述核心结论与建议简要描述详细阐述1xx - 信息性响应 (Informational)2xx - 成功 (Successful)3xx - 重定向 (Redirection)4xx - 客户端错误 (Client Error)5xx - 服务器错误 (Server Error)HTTP 状态码速查表参考以及更多更详细的状态码查询写在前面
你…
文章目录写在前面问题描述核心结论与建议简要描述详细阐述1xx - 信息性响应 (Informational)2xx - 成功 (Successful)3xx - 重定向 (Redirection)4xx - 客户端错误 (Client Error)5xx - 服务器错误 (Server Error)HTTP 状态码速查表参考以及更多更详细的状态码查询写在前面
你是否见过这样的 API无论操作成功、参数错误还是找不到资源它都固执地返回 200 OK然后把真正的状态信息藏在响应体的某个角落比如 {“code”: 5001, “message”: “参数不能为空”} 这种设计看似“统一”实则严重违反了 RESTful 的核心原则极大地增加了客户端的对接成本和出错概率。HTTP 状态码并非摆设它们是服务器与客户端之间沟通的标准语言是 API 自我描述能力的重要组成部分。 本文旨在建立一套清晰、统一的 HTTP 状态码使用规范帮助你和你的团队构建出更健壮、更易于理解和使用的 API。
问题描述
在RESTful API设计中仅仅返回200成功或500服务器错误是远远不够的。不规范的状态码会严重影响API的可用性和开发者的对接效率。
本次调研旨在建立一套清晰、统一的HTTP状态码使用规范核心目标是当API调用出现各类情况如参数不合法、无权限、资源不存在等时能够返回最恰当的状态码和最清晰的错误信息提升API的健壮性和开发者体验。
核心结论与建议
参数不合法应该返回什么
首选答案400 Bad Request
这是最通用、最符合HTTP规范的选择。当服务器因客户端发送的请求本身有错误例如数据格式错误、缺少必需参数、参数值超出业务范围等而无法处理时应返回此状态码。
更精确的选择422 Unprocessable Entity
在特定场景下422 是比 400 更精确的补充。它们的区别在于
400 Bad Request: 请求语法有误。服务器无法理解请求如JSON格式损坏。422 Unprocessable Entity: 请求语义有误。服务器能理解请求但因业务规则限制无法处理如必填字段为空、年龄为负数。
对于绝大多数团队统一使用 400 Bad Request 来表示所有类型的参数验证失败是更简单且完全可接受的最佳实践。
简要描述
HTTP状态码是RESTful API设计中非常核心的一部分是三位整数代码它们是服务器与客户端之间沟通的“标准语言”。
HTTP 状态码是可扩展的。HTTP 客户端无需理解所有已注册状态码的含义尽管理解这些含义显然是更好的。但是客户端必须理解任何状态码的类别由第一位数字指示并将无法识别的状态码视为该类别的 x00 状态码例如如果客户端收到无法识别的状态码 471则客户端可以假定其请求存在问题并将该响应视为收到了 400错误请求状态码。响应消息通常包含一个解释状态的表示。
这些状态码被分为五大类由第一位数字标识第一位数字定义了响应的类别最后两位数字不具有任何分类作用
1xx (Informational): 信息性响应 - 表示请求已接收继续处理。2xx (Successful): 成功 - 表示请求已被成功接收、理解、并接受。3xx (Redirection): 重定向 - 表示需要客户端采取进一步的操作才能完成请求。4xx (Client Error): 客户端错误 - 表示请求包含语法错误或无法完成请求。5xx (Server Error): 服务器错误 - 表示服务器在处理一个看似有效的请求时发生错误。
详细阐述
1xx - 信息性响应 (Informational)
这类状态码在日常API开发中非常少见主要用于协议内部交互。
100 Continue (继续)客户端准备发送一个大的请求体如POST一个大文件时可以先发送一个只包含头信息的请求并携带Expect: 100-continue头。如果服务器愿意接收就返回100客户端再继续发送请求体。这可以避免因服务器拒绝而浪费带宽。
101 Switching Protocols (切换协议)客户端请求升级协议例如从HTTP/1.1升级到WebSocket服务器同意切换时返回此码。
102 Processing (处理中)(WebDAV扩展) 一个请求可能包含多个子操作需要较长时间完成。服务器返回102以防止客户端超时表示请求已收到且正在处理中。
2xx - 成功 (Successful)
这是API设计中最常用的一类表示操作成功。
200 OK (成功)最通用的成功状态码。表示请求已成功响应体中通常包含请求的资源。适用于GET获取数据、PUT更新整个资源、PATCH部分更新资源以及不创建新资源的POST操作的成功响应。
201 Created (已创建)专门用于创建新资源。当客户端通过POST请求成功创建了一个新资源时返回。最佳实践是在响应头的Location字段中包含新资源的URL。
202 Accepted (已接受): 用于异步任务。服务器已接收请求但尚未处理完成。这并不保证最终任务会成功。适用于需要长时间处理的操作如视频转码、生成报表等。客户端可以后续通过轮询或其他机制查询任务状态。
204 No Content (无内容): 服务器成功处理了请求但响应体中没有任何内容返回。常用于DELETE请求成功后或PUT更新操作成功但无需返回资源内容时。
206 Partial Content (部分内容)(不常用) 用于范围请求Range Requests表示服务器成功返回了资源的一部分例如视频流或大文件分块下载。
3xx - 重定向 (Redirection)
表示客户端需要执行后续操作才能完成请求。
301 Moved Permanently (永久移动): 请求的资源已被永久移动到新的URL。搜索引擎会更新其索引。API客户端应该将本地书签也更新到新的URL。
302 Found (找到)请求的资源临时位于不同的URL。客户端应该使用这个临时的URL来发送本次请求但下次还应该使用原始URL。常用于传统的Web页面重定向API中较少使用。
303 See Other (查看其他)(与302类似但更明确) 建议客户端使用GET方法去请求另一个URL来获取结果。主要用于POST请求后防止用户刷新页面导致重复提交。
304 Not Modified (未修改)用于缓存控制。当客户端发送一个带条件的GET请求如使用If-None-Match或If-Modified-Since头如果服务器发现资源自上次请求以来未发生变化则返回此码并且不包含响应体从而节省带宽。
307 Temporary Redirect (临时重定向)(与302类似但更严格) 要求客户端在重定向到新URL时保持原始请求方法不变。例如如果原始请求是POST那么对新URL的请求也必须是POST。
4xx - 客户端错误 (Client Error)
API设计中最需要关注和细化的一类表示错误源于客户端。
400 Bad Request (错误请求)通用的客户端错误。表示服务器因客户端发送的请求语法错误而无法解析。最常见的用途是参数验证失败如缺少必需字段、字段格式错误、数值超出范围等。
401 Unauthorized (未授权)用户未认证。客户端必须先进行身份验证例如提供有效的Token或API Key才能访问该资源。它表达的是“你是谁”的问题。
403 Forbidden (禁止访问)用户没权限。服务器已经知道客户端的身份但该身份没有权限访问此资源。它表达的是“我知道你是谁但你不能做这个操作”的问题。
404 Not Found (未找到)请求的资源不存在。例如GET /api/users/9999但ID为9999的用户不存在。
405 Method Not Allowed (方法不允许)客户端使用了当前资源不支持的HTTP方法。例如对一个只读资源使用POST。服务器应在Allow头中返回支持的方法列表。
406 Not Acceptable (不可接受)(不常用) 服务器无法根据客户端请求头中的Accept字段如Accept: application/xml生成任何可接受的表示形式。
409 Conflict (冲突)请求的操作与服务器资源的当前状态发生冲突。最常见的例子是尝试创建一个已经存在的唯一资源如注册一个已被占用的用户名或邮箱。
410 Gone (已移除)(比404更明确) 请求的资源曾经存在但现在已被永久删除并且不会再可用。
413 Payload Too Large (负载过大)客户端发送的请求体大小超过了服务器的限制。
415 Unsupported Media Type (不支持的媒体类型)客户端发送的请求体使用了服务器不支持的媒体类型由Content-Type头指定。例如API只接受application/json但客户端发送了application/xml。
422 Unprocessable Entity (无法处理的实体)(WebDAV扩展但被广泛用于API) 请求的语法正确但语义错误导致服务器无法处理。这是400的一个更具体的版本专门用于业务逻辑层面的验证失败。
429 Too Many Requests (请求过多)API限流。客户端在单位时间内发送的请求数量超过了服务器设定的速率限制。
5xx - 服务器错误 (Server Error)
表示错误源于服务器端客户端通常无法解决。
500 Internal Server Error (服务器内部错误)通用的服务器端错误。表示服务器遇到了一个未知的、无法处理的意外情况例如代码中出现未捕获的异常、数据库连接问题等。绝不能在响应中暴露敏感的错误细节。
501 Not Implemented (未实现)服务器不支持当前请求所需要的功能。例如客户端使用了服务器无法识别的请求方法。
502 Bad Gateway (错误网关)作为网关或代理的服务器从其上游服务器如应用服务器处收到了无效的响应。
503 Service Unavailable (服务不可用)服务器当前无法处理请求通常是临时性的。原因可能是服务器过载、正在进行维护或部署。服务器可以在Retry-After头中告知客户端何时可以重试。
504 Gateway Timeout (网关超时)作为网关或代理的服务器未能及时从其上游服务器获得响应。
HTTP 状态码速查表
类别状态码名称核心适用场景信息性响应1xx100 Continue继续交互是否继续发送101 Switching Protocols切换协议切换协议102 Processing处理中防止客户端超时。请求包含多个子操作需要较长时间成功 (2xx)200 OK成功通用成功。GET, PUT, PATCH, POST(不创建新资源), DELETE 成功201 Created已创建资源创建成功 (专用于POST)202 Accepted已接受异步任务请求已接收正在后台处理204 No Content无内容成功处理但无返回内容 (如DELETE成功)206 Partial Content部分内容服务器成功返回了资源的一部分例如视频流或大文件分块下载重定向 (3xx)301 Moved Permanently永久移动资源 URL 永久变更302 Found找到请求的资源临时位于不同的URL303 See Other查看其他建议客户端使用GET方法去请求另一个URL来获取结果304 Not Modified未修改缓存命中资源无变化307 Temporary Redirect临时重定向要求客户端在重定向到新URL时保持原始请求方法不变客户端错误 (4xx)400 Bad Request错误请求参数验证失败 (通用客户端错误)401 Unauthorized未授权需要认证 (未登录或Token无效)403 Forbidden禁止访问权限不足 (已登录但无权操作)404 Not Found未找到请求的资源不存在405 Method Not Allowed方法不允许HTTP 请求方法错误 (如对只读资源用POST)406 Not Acceptable不可接受服务器无法根据客户端请求头中的Accept字段生成任何可接受的表示形式409 Conflict冲突资源状态冲突 (如创建已存在的用户)410 Gone已移除请求的资源曾经存在但现在已被永久删除并且不会再可用413 Payload Too Large负载过大客户端发送的请求体大小超过了服务器的限制415 Unsupported Media Type不支持的媒体类型客户端发送的请求体使用了服务器不支持的媒体类型由Content-Type头指定422 Unprocessable Entity无法处理的实体请求的语法正确但业务语义错误 (400的更具体版本)专用于业务逻辑层面的验证失败429 Too Many Requests请求过多API 限流服务器错误 (5xx)500 Internal Server Error服务器内部错误通用服务器端代码/环境异常501 Not Implemented未实现服务器不支持当前请求所需要的功能502 Bad Gateway错误网关网关/代理从上游收到无效响应503 Service Unavailable服务不可用服务器临时过载、维护或部署504 Gateway Timeout网关超时网关/代理从上游请求超时
参考以及更多更详细的状态码查询 权威标准-IETF RFCs RFC 7231: Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content: 6. Response Status Codes
RFC 6585: Additional HTTP Status Codes
RFC 4918: HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV) 开发者圣经-MDN Web Docs HTTP 响应状态码 - HTTP | MDN 快速查询 HTTP Status Codes Glossary - WebFX 趣味记忆 HTTP Cats
