HTTP 与 Web 标准 / 技术文章

HTTP 200、201、204 应该怎么选

这篇文章解决一个常见的 API 设计问题:请求成功后到底该返回 200、201 还是 204。面向后端开发者、API 设计者和联调人员,读完后你可以直接根据“是否创建资源、是否返回响应体”做出一致选择。

先看结论

三个状态码都属于成功响应,但表达的结果不同。不要把它们理解成“成功程度不同”,而要看这次请求完成后,服务端准备向客户端表达什么。

状态码 核心语义 典型场景 响应体
200 OK 请求成功,并返回当前结果 查询、更新后返回资源、执行操作后返回结果 通常有
201 Created 请求成功,并创建了新资源 创建用户、订单、文章等资源 可以有
204 No Content 请求成功,但没有响应内容需要返回 删除成功、更新成功且无需返回资源 必须没有消息体

最实用的判断顺序是:先判断是否创建了新资源,再判断是否需要返回响应体。

200 OK:成功,而且有结果要返回

200 OK 是最通用的成功状态码,适合“请求已经成功处理,并且响应中还有客户端需要读取的表示或结果”。

最典型的是查询接口,例如 GET /users/<ID> 返回用户数据。更新接口也可以返回 200:如果 PUT 或 PATCH 完成后希望把更新后的资源、计算结果或业务状态一起返回,使用 200 很自然。

关键不是 HTTP 方法,而是响应语义。POST 并不天然等于 201,PUT 也不天然等于 204。只要这次请求成功且需要返回结果,200 就可能是正确答案。

201 Created:这次请求创建了一个新资源

201 Created 比 200 多表达了一层信息:服务器成功处理请求,并因此创建了一个此前不存在的新资源。

常见场景是 POST /users 创建用户、POST /orders 创建订单。此时服务端最好通过 Location 响应头告诉客户端新资源的位置,例如 Location: /users/<ID>。

响应体不是 201 的必要条件。你可以返回刚创建的资源,也可以只返回必要字段;但如果接口实际上没有创建新的可识别资源,仅仅执行了登录、发送验证码、触发任务等动作,就不应该为了“这是 POST”而机械返回 201。

204 No Content:成功,但没有内容要返回

204 No Content 表示请求已经成功处理,但服务器不返回消息体。它适合客户端只关心“操作是否成功”,不需要继续读取资源内容的场景。

例如删除接口 DELETE /users/<ID> 成功后,如果没有额外数据需要返回,可以直接使用 204。更新接口也一样:如果客户端已经知道提交的数据,而且服务端没有必要回传更新后的资源,可以使用 204。

204 最重要的约束就是不要再返回 JSON 响应体。如果你需要返回 { "success": true }、更新后的对象或其他结果,应改用 200 等带响应内容的成功状态。

用一个接口组理解差异

下面假设服务提供查询、创建和删除三个接口。将 <PORT>、<ID> 替换成实际值后即可执行,实际资源 ID、响应头和字段可能不同。

bash
curl -i "http://localhost:<PORT>/users/<ID>"
curl -i -X POST "http://localhost:<PORT>/users" -H "Content-Type: application/json" -d '{"name":"Ada"}'
curl -i -X DELETE "http://localhost:<PORT>/users/<ID>"

预期结果:

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

{"id":"<ID>","name":"Ada"}

HTTP/1.1 201 Created
Location: /users/<ID>
Content-Type: application/json

{"id":"<ID>","name":"Ada"}

HTTP/1.1 204 No Content

这三个响应都表示成功,但客户端得到的信息不同:200 告诉客户端“结果在响应体里”,201 进一步告诉客户端“创建了新资源”,204 则明确表示“操作成功,到这里结束,没有响应体”。

三个状态码怎么选

可以把选择压缩成两个问题:

  1. 这次请求是否创建了新的可识别资源? 如果是,优先使用 201 Created。
  2. 如果没有创建新资源,客户端是否需要读取响应体? 需要就用 200 OK,不需要就用 204 No Content。
请求结果 推荐状态码
查询成功并返回数据 200
更新成功并返回更新后的资源 200
创建成功并产生新资源 201
删除成功且无需返回内容 204
更新成功且无需返回内容 204
执行动作成功并返回执行结果 200

这个规则比“GET 用 200、POST 用 201、DELETE 用 204”更可靠,因为 HTTP 状态码描述的是响应结果的语义,不是请求方法的固定映射。

常见误用与落地建议

最常见的误用是所有成功请求都返回 200。这样通常能工作,但会丢掉“创建了新资源”或“没有响应内容”这些协议层信息,降低 API 的可读性。

另一种误用是为了统一响应格式,让所有接口都返回 200,再依靠 JSON 中的 code 判断成功失败。业务码可以保留,但不应该替代 HTTP 状态码本身;HTTP 层应该先正确表达请求是否成功以及结果类型。

实际设计时保持一条原则即可:状态码负责表达 HTTP 层结果,响应体负责承载需要返回的数据。 创建新资源用 201,成功且有结果用 200,成功且无需返回内容用 204。

目录与阅读设置

记录一个想法

HTTP 200、201、204 应该怎么选

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

登录哪都通