计算机网络 / 系统课时

使用成功状态码

使用成功状态码

接口已经成功处理请求时,并不意味着都应该返回 200 OK。200、201、202 和 204 分别表达“已完成并返回结果”“已创建资源”“已接收但尚未完成”和“已完成且没有正文”,正确选择可以让客户端知道下一步该读取数据、访问新资源还是继续查询任务状态。

学习目标

  • 能根据请求结果选择 200、201、202 或 204
  • 能正确处理 201 的资源位置和 202 的异步状态
  • 能避免给 204 返回正文等常见协议表达错误

200 用于已经完成并需要返回结果

200 OK 适合请求已经完成,并且响应正文对客户端有价值的场景。典型例子包括读取资源、执行查询,以及更新资源后返回更新结果。

例如读取用户 42 成功后,可以返回完整资源:

text
HTTP/1.1 200 OK
Content-Type: application/json

{"id":42,"name":"Ada"}

这里的预期结果是客户端收到 200 后直接解析 JSON,得到用户 ID 和名称。对于 GET /users/42 这类读取请求,这是比 201 或 204 更准确的表达。

如果一次更新需要把更新后的资源、版本号或计算结果返回给调用方,也可以使用 200。不要因为请求方法是 POST 或 PUT 就机械选择某个状态码,真正决定状态码的是本次处理结果。

201 用于已经创建出新资源

201 Created 表示服务器已经完成创建。常见做法是在响应的 Location 头中给出新资源的 URI,并在需要时把创建后的资源放进正文。

text
HTTP/1.1 201 Created
Location: /orders/8472
Content-Type: application/json

{"id":8472,"status":"created"}

预期结果是客户端可以确认订单已经存在,并可通过 /orders/8472 继续读取这个资源。这里不能使用 202 表示同一语义,因为 202 只保证请求已被接受,并不保证资源已经创建完成。

一个直接可用的判断方法是:响应发送时,如果新资源已经存在并拥有稳定标识符,优先考虑 201;如果创建工作仍在队列中等待执行,则考虑 202。

202 用于接受任务但尚未完成

202 Accepted 适合异步处理,例如生成大型报表、转码视频或批量导入数据。服务器已经接受请求,但在返回响应时任务可能仍处于 queued 或 running 状态,因此不能向客户端暗示最终操作已经成功完成。

text
HTTP/1.1 202 Accepted
Content-Type: application/json

{"jobId":"job-91","status":"queued","statusUrl":"/jobs/job-91"}

预期结果是客户端保存 jobId,随后访问 /jobs/job-91 查询任务状态。真实项目还可以在响应中提供状态查询地址,避免客户端不知道应该到哪里获取最终结果。

204 用于成功但没有响应正文

204 No Content 表示请求已经成功处理,而且服务器不返回消息正文。它常用于删除资源,或客户端已经拥有所需状态、不需要服务器再次传输资源的更新操作。

text
HTTP/1.1 204 No Content

预期结果是客户端确认操作成功,但不尝试解析 JSON 正文。若业务需要返回更新后的对象、删除记录数量或新的版本信息,应改用带正文的 200,而不是一边返回 204 一边附加 JSON。

例如 DELETE /sessions/abc 已成功注销会话且没有其他结果需要返回时,204 很合适;如果删除接口必须返回 {"deleted":true},则应使用允许正文的成功响应,例如 200。

用处理完成度选择状态码

四个状态码可以用两个问题快速区分:操作现在是否已经完成,以及客户端是否需要响应正文或新资源位置。

处理结果 推荐状态码 客户端下一步
已完成,需要读取返回数据 200 解析响应正文
已完成,并创建了新资源 201 读取正文或访问 Location
已接受,但后台仍在处理 202 查询任务状态
已完成,不需要返回正文 204 只确认成功

例如“创建导出任务”通常返回 202,因为文件还没生成;任务完成后读取导出记录可以返回 200;直接创建一条已经落库的订单记录可以返回 201;删除一个无需返回任何信息的临时令牌则可以返回 204。按处理结果选择状态码,比按照 GET、POST、PUT、DELETE 方法机械配对更可靠。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用成功状态码

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通