.NET中优雅使用Patch: JsonPatch

weimin

引言

在现代 Web API 开发中，我们经常需要对资源进行部分更新（Partial Update）。传统的 PUT 请求会要求发送整个对象，而 PATCH 请求可以仅发送需要更新的字段。ASP.NET Core 提供了 JsonPatchDocument<T> 来简化这一操作。
什么是 JsonPatch？

JsonPatch（基于 RFC 6902）是一种 JSON 格式的补丁文档，允许客户端声明式地修改 JSON 资源。JsonPatch 提供了以下操作：
add：添加一个新值
remove：删除一个字段
replace：替换一个字段的值
move：移动一个值
copy：复制一个值
test：测试一个值是否符合预期
在 ASP.NET Core Web API 中使用 JsonPatch

安装依赖

JsonPatch 已内置于 Microsoft.AspNetCore.Mvc.NewtonsoftJson，你需要确保你的项目引用了该包：
builder.Services.AddControllers().AddNewtonsoftJson();创建 API 控制器

假设我们有一个 Product 类：
public class Product{    public int Id { get; set; }    public string Name { get; set; }    public decimal Price { get; set; }}然后，创建 ProductsController 处理 PATCH 请求：
[ApiController][Route("api/[controller]")]public class ProductsController : ControllerBase{    private static List<Product> _products = new()    {        new Product { Id = 1, Name = "Laptop", Price = 1200 },        new Product { Id = 2, Name = "Mouse", Price = 25 }    };    [HttpPatch("{id}")]    public IActionResult Patch(int id, [FromBody] JsonPatchDocument<Product> patchDoc)    {        var product = _products.FirstOrDefault(p => p.Id == id);        if (product == null)        {            return NotFound();        }        patchDoc.ApplyTo(product, ModelState);        if (!ModelState.IsValid)        {            return BadRequest(ModelState);        }        return Ok(product);    }}发送 JsonPatch 请求

客户端可以发送如下 PATCH 请求：
[    { "op": "replace", "path": "/price", "value": 999.99 }]示例 cURL 请求：
curl -X PATCH "http://localhost:5000/api/products/1" \     -H "Content-Type: application/json" \     -d '[{"op": "replace", "path": "/price", "value": 999.99}]'处理 JsonPatch 可能遇到的问题

确保 JSON 格式正确

JsonPatch 语法容易出错，比如路径格式不正确或缺少 op。建议使用 Postman 或 cURL 进行调试。
处理 ModelState 错误

如果 patchDoc.ApplyTo(product, ModelState); 返回错误，应该返回 BadRequest(ModelState) 并提供详细的错误信息。
结论

JsonPatch 提供了一种优雅的方式来进行部分更新，避免了 PUT 需要传输整个对象的冗余。合理使用 JsonPatch，可以提高 API 的灵活性和效率。