HTTP 与 Web 标准 / 技术文章

POST 和 PUT 到底有什么区别

这篇文章解决开发中最常见的 HTTP 方法选择问题,适合正在设计或调用 REST API 的前后端开发者。读完后,你不再用“POST 是新增、PUT 是更新”死记,而能根据资源 URI、请求语义和幂等性判断该用哪一个。

先抓住本质:请求到底作用于哪个资源

POST 和 PUT 的差异,首先不在“增还是改”,而在请求的目标资源是谁,以及客户端是否已经知道最终资源 URI。

POST 通常把请求发给一个能够“处理这次提交”的资源。例如向 /users 提交用户资料,由服务器完成创建逻辑,并决定新用户最终是 /users/123 还是其他地址。

PUT 则直接作用于一个确定的目标 URI。例如请求 /users/123,表达的是:“我希望这个 URI 对应的资源变成请求体描述的状态。”如果该资源已经存在,通常是替换;如果不存在,服务器也可以按接口约定创建它。

因此,“POST=新增、PUT=更新”只能覆盖部分常见用法,不能当作定义。

POST:让目标资源处理一次提交

POST 的语义是把一份数据提交给目标资源处理。目标资源如何处理,由该接口自己定义,所以 POST 不只用于创建资源,也常用于提交表单、执行操作、触发任务或发起支付。

假设 /users 被定义为“用户集合”,客户端只负责提交用户资料,新资源 ID 由服务器生成。

下面是片段示例,依赖一个已实现 POST /users 的 HTTP 服务,并约定创建成功返回 201 Created 和新资源地址:

bash
curl -i -X POST "https://api.example.com/users"   -H "Content-Type: application/json"   -d '{"name":"Alice","email":"alice@example.com"}'

预期输出:

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

{"id":"<ID>","name":"Alice","email":"alice@example.com"}

其中 <ID> 由服务器生成,实际值每次可能不同。关键点不是 201 本身,而是客户端提交到 /users,最终资源 URI 由服务器决定。

POST 也可以用于非创建操作,例如 POST /orders/<ID>/cancel 表示提交一次“取消订单”的命令。这再次说明 POST 的本质不是“新增”,而是“让目标资源处理这次请求”。

PUT:把指定 URI 变成请求描述的状态

PUT 的语义更接近“在这个确定的 URI 上创建或替换资源状态”。客户端通常已经知道目标资源的 URI,因此请求直接发送到该地址。

下面是片段示例,依赖一个已实现 PUT /users/<ID> 的 HTTP 服务,并约定请求体表示用户的完整目标状态:

bash
curl -i -X PUT "https://api.example.com/users/<ID>"   -H "Content-Type: application/json"   -d '{"name":"Alice Chen","email":"alice.chen@example.com"}'

预期输出:

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

{"id":"<ID>","name":"Alice Chen","email":"alice.chen@example.com"}

这里的 <ID> 需要替换为真实资源 ID。这个请求表达的不是“请帮我修改 name 和 email 两个字段”,而是“请让 /users/<ID> 对应的用户呈现为这份表示描述的状态”。

这也是为什么 PUT 通常和“完整替换”联系在一起,而局部更新更常使用 PATCH。若某个接口把 PUT 设计成只修改请求中出现的字段,也不是客户端可以凭方法名猜出来的,必须以接口契约为准。

幂等性才是最关键的工程差异

HTTP 语义规定 PUT 是幂等的,而 POST 不保证幂等。

所谓幂等,不是“每次响应内容都完全一样”,而是:对服务器而言,执行一次和重复执行多次相同请求,最终预期状态相同。

例如连续发送三次相同的 PUT,请求都要求 /users/<ID> 最终变成同一份用户状态。第一次可能返回 200,后续也可能返回 200 或 204,但资源最终状态不会因为重复请求继续叠加变化。

POST 则没有这个保证。连续提交三次 POST /users,服务器完全可能创建三个用户资源。因此在支付、下单、发券这类不能重复执行的场景里,常会在 POST 之外增加幂等键、业务唯一号或服务端去重机制。

对比维度 POST PUT
目标 URI 通常是负责处理提交的资源 通常是最终资源自己的 URI
最终资源地址 常由服务器决定 通常由客户端已经确定
常见语义 创建、提交、执行动作 创建或替换指定资源
幂等性 HTTP 语义不保证 HTTP 语义要求幂等
局部更新 可以设计,但需明确约定 通常不建议表示局部修改

最容易踩坑的几个误区

误区一:POST 只能创建资源。
不是。POST 可以提交任何需要目标资源处理的数据,创建资源只是最常见的场景之一。

误区二:PUT 只能更新已有资源。
也不是。PUT 指向一个确定 URI,如果资源不存在,并且服务端允许创建,那么 PUT 同样可以创建该资源。

误区三:PUT 就等于修改几个字段。
更准确的理解是“让目标 URI 呈现为请求描述的状态”。如果只想修改一个字段,PATCH 往往更符合语义。

误区四:用了 POST 就一定会重复创建。
HTTP 本身不保证 POST 幂等,但业务层完全可以通过 Idempotency-Key、订单号或唯一约束让某个 POST 接口具备幂等效果。要区分“方法的标准语义”和“接口的业务实现”。

误区五:看状态码就能判断该用 POST 还是 PUT。
不能。POST 创建资源常返回 201 Created,PUT 在创建不存在的目标资源时同样可以返回 201。方法选择应该看资源语义,而不是反推状态码。

设计接口时怎么选

实际设计 API 时,可以按下面的顺序判断:

  1. 客户端是否已经知道并控制最终资源 URI?如果是,并且请求表达创建或替换这个资源,优先考虑 PUT。
  2. 客户端是否只是把数据提交给一个集合或处理器,由服务器决定如何处理、生成什么资源?优先考虑 POST。
  3. 是否只是修改资源的一部分字段?通常优先考虑 PATCH,而不是强行使用 PUT。
  4. 请求是否可能因为超时、重试机制而重复发送?如果使用 PUT,可以直接利用其幂等语义;如果必须使用 POST,应额外设计业务幂等机制。

可以把判断压缩成一句话:POST 更像“把这件事交给这个资源处理”,PUT 更像“让这个确定的 URI 变成我提交的状态”。

真正掌握这条区别后,再遇到创建、覆盖、重试、资源地址分配等场景,就不需要背“新增和更新”的口诀,而可以从 HTTP 资源语义直接得出答案。

目录与阅读设置

记录一个想法

POST 和 PUT 到底有什么区别

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

登录哪都通