.NET中優(yōu)雅使用Patch: JsonPatch

引言

在現(xiàn)代 Web API 開發(fā)中，我們經(jīng)常需要對資源進(jìn)行部分更新（Partial Update）。傳統(tǒng)的 PUT 請求會要求發(fā)送整個對象，而 PATCH 請求可以僅發(fā)送需要更新的字段。ASP.NET Core 提供了 JsonPatchDocument<T> 來簡化這一操作。

什么是 JsonPatch？

JsonPatch（基于 RFC 6902）是一種 JSON 格式的補丁文檔，允許客戶端聲明式地修改 JSON 資源。JsonPatch 提供了以下操作：

add：添加一個新值

remove：刪除一個字段

replace：替換一個字段的值

move：移動一個值

copy：復(fù)制一個值

test：測試一個值是否符合預(yù)期

在 ASP.NET Core Web API 中使用 JsonPatch

安裝依賴

JsonPatch 已內(nèi)置于 Microsoft.AspNetCore.Mvc.NewtonsoftJson，你需要確保你的項目引用了該包：

builder.Services.AddControllers().AddNewtonsoftJson();

創(chuàng)建 API 控制器

假設(shè)我們有一個 Product 類：

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
}

然后，創(chuàng)建 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);
    }
}

發(fā)送 JsonPatch 請求

客戶端可以發(fā)送如下 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 進(jìn)行調(diào)試。

處理 ModelState 錯誤

如果 patchDoc.ApplyTo(product, ModelState); 返回錯誤，應(yīng)該返回 BadRequest(ModelState) 并提供詳細(xì)的錯誤信息。

結(jié)論

JsonPatch 提供了一種優(yōu)雅的方式來進(jìn)行部分更新，避免了 PUT 需要傳輸整個對象的冗余。合理使用 JsonPatch，可以提高 API 的靈活性和效率。