ASP.NET WebAPI中PUT方法传递ID与含Id属性DTO的最佳实践

推荐做法 #

1. 校验ID一致性，优先使用路由ID #

如果不想修改现有DTO结构，最直接的方式是在方法内校验路由ID与DTO中ID的一致性，不一致则返回400错误。后续业务逻辑统一使用路由ID定位资源，用DTO的其他属性执行更新。

示例代码：

[Authorize(Policy = "WriteAccess")]
[HttpPut("{id}")]
[ProducesResponseType(StatusCodes.Status204NoContent)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
[ProducesResponseType(StatusCodes.Status409Conflict)]
public async Task<ActionResult> PutCategory(Guid id, CategoryDTO categoryDTO)
{
    // 校验ID一致性
    if (id != categoryDTO.Id)
    {
        return BadRequest("路由ID与请求体中的资源ID不匹配");
    }

    // 用路由ID查找待更新实体
    var category = await _context.Categories.FindAsync(id);
    if (category == null)
    {
        return NotFound();
    }

    // 用DTO属性更新实体
    category.Name = categoryDTO.Name;
    category.CategoryDescription = categoryDTO.CategoryDescription;

    await _context.SaveChangesAsync();
    return NoContent();
}

2. 为PUT请求单独创建无ID的DTO #

这是最符合RESTful规范的做法：PUT请求的目标资源已由路由ID明确指定，请求体只需传递需要更新的字段，无需重复携带ID。通过创建专用的更新DTO，能清晰区分不同操作的数据结构，避免歧义。

创建专用更新DTO：

public class UpdateCategoryDTO
{
    public string Name { get; set; }
    public string CategoryDescription { get; set; }
}

修改PUT方法参数：

[Authorize(Policy = "WriteAccess")]
[HttpPut("{id}")]
[ProducesResponseType(StatusCodes.Status204NoContent)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
[ProducesResponseType(StatusCodes.Status409Conflict)]
public async Task<ActionResult> PutCategory(Guid id, UpdateCategoryDTO updateCategoryDTO)
{
    var category = await _context.Categories.FindAsync(id);
    if (category == null)
    {
        return NotFound();
    }

    category.Name = updateCategoryDTO.Name;
    category.CategoryDescription = updateCategoryDTO.CategoryDescription;

    await _context.SaveChangesAsync();
    return NoContent();
}

3. 强制覆盖DTO中的ID（临时过渡方案） #

如果暂时无法创建新DTO，可以在代码中直接用路由ID覆盖DTO的ID字段，确保后续逻辑使用统一的ID。但需在接口文档中明确告知前端：请求体中的ID会被路由ID覆盖，避免误解。

示例代码：

public async Task<ActionResult> PutCategory(Guid id, CategoryDTO categoryDTO)
{
    // 强制用路由ID覆盖DTO中的ID
    categoryDTO.Id = id;

    // 后续用统一后的ID处理业务逻辑
    var category = await _context.Categories.FindAsync(categoryDTO.Id);
    // ... 更新逻辑
}

方案选择建议 #

• 若追求规范和长期可维护性，优先选择为PUT创建专用DTO的方案，职责清晰，避免冗余。
• 若需快速兼容现有前端实现，可选择校验ID一致性的方案，改动最小。
• 强制覆盖ID的方案仅适合临时过渡，不推荐长期使用。

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