计算机网络 / 系统课时
使用成功状态码
使用成功状态码
接口已经成功处理请求时,并不意味着都应该返回 200 OK。200、201、202 和 204 分别表达“已完成并返回结果”“已创建资源”“已接收但尚未完成”和“已完成且没有正文”,正确选择可以让客户端知道下一步该读取数据、访问新资源还是继续查询任务状态。
学习目标
- 能根据请求结果选择 200、201、202 或 204
- 能正确处理 201 的资源位置和 202 的异步状态
- 能避免给 204 返回正文等常见协议表达错误
200 用于已经完成并需要返回结果
200 OK 适合请求已经完成,并且响应正文对客户端有价值的场景。典型例子包括读取资源、执行查询,以及更新资源后返回更新结果。
例如读取用户 42 成功后,可以返回完整资源:
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,并在需要时把创建后的资源放进正文。
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 状态,因此不能向客户端暗示最终操作已经成功完成。
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 表示请求已经成功处理,而且服务器不返回消息正文。它常用于删除资源,或客户端已经拥有所需状态、不需要服务器再次传输资源的更新操作。
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 方法机械配对更可靠。