.NET中优雅使用Patch: JsonPatch

引言

在现代 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 的灵活性和效率。