@PostMapping与@PutMapping注解的核心区别是什么？

首先你提到的两个认知都是准确的：

• 两个注解在Spring框架层面都完全支持绑定请求体，不管是用@RequestBody接收JSON/XML格式参数，还是解析表单提交的参数，底层处理逻辑没有任何区别。二者本质都是@RequestMapping的派生注解，唯一的内置差异就是默认匹配的HTTP方法不同：@PostMapping 匹配HTTP POST请求，@PutMapping匹配HTTP PUT请求，不存在其他功能层面的硬限制。
• “Post用来提交新增数据、Put用来更新数据”是行业非常普遍的实践，但这不是Spring框架做的强制约束，也不只是为了提升代码可读性，这个约定的根源是HTTP协议本身对两个方法的语义定义，是会实际影响接口运行行为的。

核心差异是HTTP语义层面的幂等性约定 #

两个方法的本质语义区别和对应的行为要求是：

• POST 属于非幂等操作：语义是「向目标路径提交处理请求，由服务端决定如何处理这批数据」。重复发送多次相同的POST请求，服务端可能产生多个不同的结果——比如你提交新建用户的POST请求到/users路径，重复发3次可能会生成3个不同ID的新用户，这是完全符合POST语义的。
• PUT 属于幂等操作：语义是「用请求携带的完整资源，完全替换目标路径上的现有资源」。重复发送多次相同的PUT请求，服务端的最终状态和发送一次完全一致——比如你发PUT请求到/users/101，把ID为101的用户昵称改成“张三”，哪怕因为网络卡顿重复提交了5次，最终这个用户的昵称还是“张三”，不会生成新用户，也不会产生其他额外副作用。

大家约定俗成用POST做新增、PUT做更新，本质是刚好匹配了两类操作的特性：新增操作通常客户端不知道新资源的最终访问路径（资源ID由服务端生成），重复提交会产生多份数据，符合POST的非幂等特性；更新操作通常客户端明确知道要修改的资源全路径（比如明确要修改ID为101的用户），重复提交结果一致，符合PUT的幂等特性。

为什么说这不只是代码可读性问题 #

这个语义约定是整个HTTP生态都认可的通用规则，不是Java/Spring生态自定的代码风格规范，会直接影响请求链路上所有组件的行为：

• 绝大多数HTTP客户端、API网关、反向代理在遇到网络超时、连接失败的场景时，会默认自动重试幂等方法的请求，PUT、GET都属于默认重试列表，POST默认不会被自动重试。如果你把非幂等的新增接口写成PUT，很可能因为中间件自动重试产生大量重复数据；反过来把幂等的更新接口写成POST，遇到网络波动时不会自动重试，用户端明明点了提交却没生效，这些都是实际生产环境会出现的真实bug。
• 接口文档工具、接口测试工具、前后端联调的通用认知都会基于这个语义做判断，用错注解会直接误导接口调用方，增加不必要的沟通成本。

最后补充一个常见误区：不是说PUT绝对不能做新增、POST绝对不能做更新。如果客户端在发起请求时就已经能确定新资源的唯一访问路径（比如用户注册时用用户名作为唯一标识，直接发PUT到/users/zhangsan创建账号），这个操作本身是幂等的（重复发多少次都只会有一个叫zhangsan的账号），用PUT完全符合HTTP规范，不属于错用。

内容的提问来源于stack exchange，提问作者flobbe9