REST API中PUT/PATCH请求应传全量数据还是仅变更字段

示例模型定义 #

public class Customer
{
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public Company Company { get; set; }
}

基础GET端点实现 #

[HttpGet, Route("{id}")]
public IActionResult GetById(int id)
{
    var entity = dataService.GetById(id);
    var model = Mapper.Map<Entity, Customer>(entity);
    return model;
}

GET端点返回的标准全量资源格式：

{
  "Id": 1,
  "FirstName": "John",
  "LastName": "Dow",
  "Company": { ... }
}

当用户仅修改FirstName字段时，符合全量更新要求的提交数据为：

{
  "Id": 1,
  "FirstName": "Mike",
  "LastName": "Dow",
  "Company": { ... }
}

经典.NET全量更新PUT端点 #

[HttpPut, Route("{id}")]
public IActionResult Update(int id, Customer model)
{
    // 设计预期：接收完整全量Customer对象，直接覆盖更新对应资源
}

实际联调常见问题 #

前端未按全量要求提交，仅传递变更字段，未修改字段被序列化为类型默认值（数值类型为0、引用类型为null），实际提交格式如下：

{
  "Id": 0,
  "FirstName": "Mike",
  "LastName": null,
  "Company": null
}

这种提交方式会迫使后端编写大量逐字段非空判断的冗余代码完成映射，示例逻辑：

if(model.FirstName != null)
    entity.FirstName = model.FirstName;

if(model.LastName != null)
    entity.LastName = model.LastName;

// 每新增一个字段就要重复编写一次判断逻辑

1. REST规范下PUT的语义边界 #

你的认知完全正确：

• 根据HTTP RFC标准定义，PUT方法的核心语义是使用请求中携带的资源表述，完整替换目标URI对应的存储资源。这就要求客户端必须提交资源的完整全量数据，服务端处理PUT请求时不需要做字段合并，直接用提交的数据覆盖原有资源即可。
• 仅提交变更字段、对原有资源做局部字段合并更新的场景，标准语义对应的HTTP动词是PATCH。如果用PUT端点接收部分字段做合并更新，属于违反HTTP语义约定的实现，会直接导致语义歧义：服务端无法区分「客户端主动要求把某个字段设置为null/0」和「客户端未传递该字段、要求保留原有值」的差异，也会让经过的代理、缓存组件的行为不符合通用预期。

2. 业界主流更新方案与选型建议 #

首先明确：给PUT端点传部分字段、后端手写逐字段判断合并的做法，从来不是.NET Core官方推荐的实现模式，本质是前端开发为了减少本地数据处理成本，把字段合并的逻辑转嫁到后端的非规范实践，并非官方推出的新标准。
目前业界主流的更新实现主要有三类，可根据团队场景选择：

• 严格遵循REST语义的标准实现：PUT端点强制要求提交全量资源，服务端收到请求后直接做全量覆盖更新；局部更新场景单独提供PATCH端点。这种方案语义最清晰，完全不需要冗余的字段判断逻辑，适合对接多端的公共API、对规范要求高的项目。前端侧实现成本很低，只需要在拿到GET返回的完整资源后，本地修改变更字段，再把整个对象提交回来即可。
• 标准化PATCH实现：采用官方定义的JSON Patch规范，请求使用application/json-patch+json格式，通过操作描述（replace/add/remove等）明确说明要修改的字段和值。.NET Core原生提供Microsoft.AspNetCore.JsonPatch库做自动解析、校验和映射，完全不需要手写逐字段判断，既符合PATCH的语义要求，又解决了局部更新的代码冗余问题，是目前局部更新场景的首选规范方案。
• 团队约定优先的灵活实现：如果团队内部约定不严格遵循REST语义，也不要在每个更新接口里手写逐字段判断，可以封装通用的模型合并公共组件，比如基于反射自动跳过未赋值的默认值字段、或者配置JSON序列化器识别字段是否被显式赋值，把合并逻辑抽成通用能力统一维护。但这种方案必须提前做好全局规则约定，明确区分「字段显式设为null/0」和「字段未传保留原值」的处理逻辑，避免出现数据误覆盖的问题。

非常不建议采纳「PUT接收部分字段+手写逐字段判断」的方案：既违反HTTP语义约定，又存在大量重复冗余代码，后续字段新增、调整时很容易漏写判断逻辑引发线上bug，长期维护成本极高。

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