RESTful API最佳实践：字段更新选全局端点还是专用端点？

针对你给出的用户年龄更新场景，优先级从高到低的选择是：PATCH /api/users/:id/ 仅传age字段 > PUT /api/users/:id/ 传全量User字段 > 单独给age建端点发POST请求。 #

各方案的优劣分析 #

1. PATCH 部分更新（首推） #

PATCH 天生的语义就是资源的部分更新，完全匹配你只修改年龄的需求：

• 请求体只需要携带 {"age": 新值} 即可，不需要冗余传其他字段，降低请求体积的同时，也完全不会出现漏传字段导致其他属性被意外覆盖的问题
• 完全符合REST规范的语义约定，对接的开发者不需要额外查文档就能理解接口用途

2. PUT 全量替换（次选，仅适合全量更新场景） #

PUT 的语义是用传入的完整资源替换目标位置的现有资源，所以你如果要用PUT更新年龄，必须传全量的firstName、lastName、age三个字段，不能只传age：

• 如果服务端严格遵守PUT语义，你漏传的字段会被直接置空或者覆盖为默认值，很容易引发数据异常
• 这种方案只适合你确实要修改整个User资源的场景，单字段更新用PUT的话冗余度太高

3. 单独属性端点发POST（不推荐） #

这种方案完全不符合REST的设计理念，问题非常多：

• age是User资源的属性，不是独立资源，没有必要单独分配端点。如果每个属性都这么设计，一个带20个属性的模型就要多维护20个接口，后期API会越来越臃肿，维护成本陡增
• POST的语义是创建子资源，用它来做属性更新属于语义滥用，会给对接方造成不必要的理解成本

实际开发补充建议 #

如果你的业务场景存在网关、旧客户端不支持PATCH请求的限制，可以退而求其次用全量PUT方案，但必须在接口文档里明确要求调用方必须传全量必填字段，同时服务端可以做参数校验，缺少必填字段直接返回错误，避免数据被异常覆盖。不要为了省事给PUT接口加部分更新的逻辑，语义混淆之后后续排查问题的成本会非常高。

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