ASP.NET Core Web API 中的 JSON Patch 技术详解

什么是 JSON Patch？

JSON Patch 是一种用于描述对 JSON 文档修改操作的标准格式，定义在 RFC 6902 中。它允许客户端通过发送一组操作指令（而非整个资源）来对服务器端资源进行部分更新，这在 RESTful API 设计中特别有用。

JSON Patch 的核心操作

JSON Patch 定义了六种基本操作类型：

1. add - 添加新属性或数组元素
2. remove - 删除属性或数组元素
3. replace - 替换现有属性值
4. move - 移动属性或数组元素
5. copy - 复制属性或数组元素
6. test - 测试属性值是否符合预期

ASP.NET Core 中的 JSON Patch 实现

在 ASP.NET Core 10 及更高版本中，JSON Patch 支持基于 System.Text.Json 序列化库实现，相比之前的 Newtonsoft.Json 实现具有更好的性能和更低的内存占用。

安装必要包

要使用 JSON Patch 功能，首先需要安装专用 NuGet 包：

dotnet add package Microsoft.AspNetCore.JsonPatch.SystemTextJson

实现 JSON Patch 控制器

下面是一个完整的 JSON Patch 控制器实现示例：

[ApiController]
[Route("api/[controller]")]
public class CustomerController : ControllerBase
{
    private readonly AppDbContext _db;

    public CustomerController(AppDbContext db)
    {
        _db = db;
    }

    [HttpPatch("{id}")]
    public IActionResult Patch(int id, 
        [FromBody] JsonPatchDocument<Customer> patchDoc)
    {
        var customer = _db.Customers.Find(id);
        if (customer == null)
        {
            return NotFound();
        }

        patchDoc.ApplyTo(customer, ModelState);

        if (!ModelState.IsValid)
        {
            return BadRequest(ModelState);
        }

        _db.SaveChanges();
        return Ok(customer);
    }
}

代码解析

1. 路由定义：使用 [HttpPatch] 特性标记处理 PATCH 请求的方法
2. 参数绑定：JsonPatchDocument<Customer> 会自动绑定请求体中的 JSON Patch 文档
3. 应用变更：ApplyTo 方法将补丁操作应用到目标对象
4. 验证处理：检查 ModelState 确保所有操作都成功应用
5. 保存变更：将修改后的对象持久化到数据库

JSON Patch 操作示例

基础操作示例

[
    { "op": "replace", "path": "/firstName", "value": "张" },
    { "op": "remove", "path": "/email" },
    { "op": "add", "path": "/address/postCode", "value": "100000" }
]

数组操作示例

[
    { "op": "add", "path": "/phoneNumbers/-", "value": { "number": "13800138000", "type": "Mobile" } },
    { "op": "remove", "path": "/phoneNumbers/0" }
]

安全注意事项

使用 JSON Patch 时需要特别注意以下安全风险：

1. 拒绝服务攻击：恶意客户端可能发送导致内存大量消耗的操作

   • 限制单个请求中的操作数量
   • 对复杂操作进行特殊处理

2. 业务逻辑绕过：补丁可能修改不应被直接修改的字段

   • 使用 DTO 对象而非直接暴露领域模型
   • 补丁应用后进行业务规则验证

3. 未授权访问：确保端点有适当的身份验证和授权

最佳实践

1. 使用专用媒体类型：请求头应设置为 Content-Type: application/json-patch+json

2. 错误处理：提供有意义的错误响应，帮助客户端调试问题

3. 文档化API：清晰说明支持的补丁操作和路径格式

4. 性能考虑：对于大型对象，考虑实现乐观并发控制

实际应用场景

JSON Patch 特别适用于以下场景：

1. 移动应用同步：仅同步变更部分而非整个资源
2. 协作编辑：多人同时编辑文档的不同部分
3. 配置管理：精细修改复杂配置对象

总结

ASP.NET Core 提供的 JSON Patch 支持使开发者能够轻松实现高效的资源部分更新功能。通过遵循本文介绍的最佳实践和安全建议，您可以构建出既灵活又安全的 API 端点。

对于需要与旧系统集成的场景，ASP.NET Core 也提供了基于 Newtonsoft.Json 的实现，但新项目建议使用基于 System.Text.Json 的新实现以获得最佳性能。