开发.NET Core todo API时PUT接口是否需要创建DTO移除对象ID？

针对Todo类API的PUT接口参数歧义问题，结合.NET Core框架的默认行为和REST规范，不同实现方案的长期维护成本差异很大，存在明确的优先级排序，并不是随便选一个能跑就行：

方案优先级说明 #

• 第一推荐：使用不含Id的TodoUpdateDTO作为PUT接口的请求体
  这也是.NET官方项目模板里对PUT接口的默认设计思路，核心原因有三个：
  • 从接口语义上明确边界：{id}参数是URI中对资源的唯一寻址标识，不属于客户端可提交的更新字段。DTO从结构上就去掉Id字段，能完全避免调用方对"哪个Id生效"的歧义，不需要靠文档反复解释规则。
  • 规避.NET Core默认模型绑定的隐式冲突：默认模型绑定不是只读请求体的，它会同时从路由值、查询字符串、表单格式提供者里匹配同名属性，如果直接把带Id的Todo实体作为请求体，框架会自动把路由里的id值填充到todo对象的Id属性上，你根本没法校验两个来源的Id是否真的一致，很容易出现非预期的资源更新行为。
  • 从源头防止越权篡改：后续Todo模型新增CreatedAt、CreateUserId这类不允许客户端修改的字段时，用实体当请求体很容易被恶意请求直接修改字段值，DTO可以精准控制哪些字段是允许客户端提交的。
• 次选兼容方案：如果为了快速开发不想新增DTO，必须显式校验路由Id和请求体携带Id的一致性，不一致直接返回400错误
  这种方案的核心是不能对两个来源的Id视而不见：
  校验逻辑非常简单，只要判断id != todo.Id就返回BadRequest("路径中的资源ID与请求体携带的ID不匹配")即可。完全不校验的话，会埋下长期的排查坑——比如调用方PUT /api/todos/1时在请求体里传了{"Id":2,"Title":"测试"}，你最后更新了Id=1的资源，调用方会默认自己改的是Id=2的todo，出问题时定位成本极高。
• 绝对不推荐的反模式：直接忽略请求体中的Id，只用路由传入的id做资源操作
  这种做法看起来代码最少，实际上把歧义留给了所有调用方和后续维护的开发，和显式校验的方案比没有任何收益，反而会增加不必要的沟通成本。

落地的配套细节 #

.NET Core里写PUT接口时，除了选对请求体结构，还要注意两个容易踩的坑：

• 用DTO的场景下，显式标注[FromBody]的数据源，避免框架把路由值绑定到DTO的同名字段上。参考写法：

  public class TodoUpdateDto
  {
      public string Title { get; set; }
      public bool Completed { get; set; }
  }
  
  [HttpPut("{id}")]
  public IActionResult Put(int id, [FromBody] TodoUpdateDto todoDto)
  {
      var existTodo = _dbContext.Todos.Find(id);
      if (existTodo == null) return NotFound();
  
      existTodo.Title = todoDto.Title;
      existTodo.Completed = todoDto.Completed;
      _dbContext.SaveChanges();
      return NoContent();
  }
  

• 如果暂时用Todo实体当请求体，记得显式排除Id字段的模型绑定，避免同名字段的绑定冲突。可以用[Bind]特性指定允许绑定的字段：

  [HttpPut("{id}")]
  public IActionResult Put(int id, [Bind(nameof(Todo.Title), nameof(Todo.Completed))] Todo todo)
  {
      // 此处todo的Id不会被任何来源自动绑定，不存在和路由id的冲突
      var existTodo = _dbContext.Todos.Find(id);
      if (existTodo == null) return NotFound();
  
      existTodo.Title = todo.Title;
      existTodo.Completed = todo.Completed;
      _dbContext.SaveChanges();
      return NoContent();
  }
  

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