ASP.NET Core Web API 中的 JSON 修补程序JsonPatch in ASP.NET Core web API

本文内容

作者：Tom Dykstra 和 Kirk Larkin

本文介绍如何处理 ASP.NET Core Web API 中的 JSON 修补程序请求。

包安装Package installation

使用 Microsoft.AspNetCore.Mvc.NewtonsoftJson 包实现了对 JsonPatch 的支持。要启用此功能，应用必须：

• 安装 Microsoft.AspNetCore.Mvc.NewtonsoftJson NuGet 包。

• 将项目的 Startup.ConfigureServices 方法更新为包含对 AddNewtonsoftJson 的调用：

services
    .AddControllersWithViews()
    .AddNewtonsoftJson();

AddNewtonsoftJson 与 MVC 服务注册方法兼容：

• AddRazorPages
• AddControllersWithViews
• AddControllers

JsonPatch、AddNewtonsoftJson 和 System.Text.JsonJsonPatch, AddNewtonsoftJson, and System.Text.Json

AddNewtonsoftJson 替换了基于 System.Text.Json 的输入和输出格式化程序，该格式化程序用于设置所有 JSON 内容的格式。要使用 JsonPatch 添加对 Newtonsoft.Json 的支持，同时使其他格式化程序保持不变，请按如下所示更新项目的 Startup.ConfigureServices：

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllersWithViews(options =>
    {
        options.InputFormatters.Insert(0, GetJsonPatchInputFormatter());
    });
}
private static NewtonsoftJsonPatchInputFormatter GetJsonPatchInputFormatter()
{
    var builder = new ServiceCollection()
        .AddLogging()
        .AddMvc()
        .AddNewtonsoftJson()
        .Services.BuildServiceProvider();
    return builder
        .GetRequiredService<IOptions<MvcOptions>>()
        .Value
        .InputFormatters
        .OfType<NewtonsoftJsonPatchInputFormatter>()
        .First();
}

上述代码需要对 Microsoft.AspNetCore.Mvc.NewtonsoftJson 的引用和以下 using 语句：

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Formatters;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Options;
using System.Linq;

PATCH HTTP 请求方法PATCH HTTP request method

PUT 和 PATCH 方法用于更新现有资源。它们之间的区别是，PUT 会替换整个资源，而PATCH 仅指定更改。

JSON 修补程序JSON Patch

JSON 修补程序是一种格式，用于指定要应用于资源的更新。JSON 修补程序文档有一个操作数组。每个操作标识特定类型的更改，例如添加数组元素或替换属性值。

例如，以下 JSON 文档表示资源、资源的 JSON 修补程序文档和应用修补程序操作的结果。

资源示例Resource example

{
  "customerName": "John",
  "orders": [
    {
      "orderName": "Order0",
      "orderType": null
    },
    {
      "orderName": "Order1",
      "orderType": null
    }
  ]
}

JSON 修补程序示例JSON patch example

[
  {
    "op": "add",
    "path": "/customerName",
    "value": "Barry"
  },
  {
    "op": "add",
    "path": "/orders/-",
    "value": {
      "orderName": "Order2",
      "orderType": null
    }
  }
]

在上述 JSON 中：

• op 属性指示操作的类型。
• path 属性指示要更新的元素。
• value 属性提供新值。

修补程序之后的资源Resource after patch

下面是应用上述 JSON 修补程序文档后的资源：

{
  "customerName": "Barry",
  "orders": [
    {
      "orderName": "Order0",
      "orderType": null
    },
    {
      "orderName": "Order1",
      "orderType": null
    },
    {
      "orderName": "Order2",
      "orderType": null
    }
  ]
}

通过将 JSON 修补程序文档应用于资源所做的更改是原子操作：如果列表中的任何操作失败，则不会应用列表中的任何操作。

路径语法Path syntax

操作对象的路径属性的级别之间有斜杠。例如，"/address/zipCode" 。

使用从零开始的索引来指定数组元素。addresses 数组的第一个元素将位于 /addresses/0。若要将 add 置于数组末尾，请使用连字符 (-)，而不是索引号：/addresses/-。

操作Operations

下表显示了 JSON 修补程序规范中定义的支持操作：

ASP.NET Core 中的 JSON 修补程序JsonPatch in ASP.NET Core

Microsoft.AspNetCore.JsonPatch NuGet 包中提供了 JSON 修补程序的 ASP.NET Core 实现。

操作方法代码Action method code

在 API 控制器中，JSON 修补程序的操作方法：

• 使用 HttpPatch 属性进行批注。
• 接受 JsonPatchDocument<T>，通常带有 [FromBody]。
• 在修补程序文档上调用 ApplyTo 以应用更改。

下面是一个示例：

[HttpPatch]
public IActionResult JsonPatchWithModelState(
    [FromBody] JsonPatchDocument<Customer> patchDoc)
{
    if (patchDoc != null)
    {
        var customer = CreateCustomer();
        patchDoc.ApplyTo(customer, ModelState);
        if (!ModelState.IsValid)
        {
            return BadRequest(ModelState);
        }
        return new ObjectResult(customer);
    }
    else
    {
        return BadRequest(ModelState);
    }
}

示例应用中的此代码适用于以下 Customer 模型。

public class Customer
{
    public string CustomerName { get; set; }
    public List<Order> Orders { get; set; }
}

public class Order
{
    public string OrderName { get; set; }
    public string OrderType { get; set; }
}

示例操作方法：

• 构造一个 Customer。
• 应用修补程序。
• 在响应的正文中返回结果。

在实际应用中，该代码将从存储（如数据库）中检索数据并在应用修补程序后更新数据库。

模型状态Model state

上述操作方法示例调用将模型状态用作其参数之一的 ApplyTo 的重载。使用此选项，可以在响应中收到错误消息。以下示例显示了 test 操作的“400 错误请求”响应的正文：

{
    "Customer": [
        "The current value 'John' at path 'customerName' is not equal to the test value 'Nancy'."
    ]
}

动态对象Dynamic objects

以下操作方法示例演示如何将修补程序应用于动态对象。

[HttpPatch]
public IActionResult JsonPatchForDynamic([FromBody]JsonPatchDocument patch)
{
    dynamic obj = new ExpandoObject();
    patch.ApplyTo(obj);
    return Ok(obj);
}

添加操作The add operation

• 如果 path 指向数组元素：将新元素插入到 path 指定的元素之前。
• 如果 path 指向属性：设置属性值。
• 如果 path 指向不存在的位置：
  • 如果要修补的资源是一个动态对象：添加属性。
  • 如果要修补的资源是一个静态对象：请求失败。

以下示例修补程序文档设置 CustomerName 的值，并将 Order 对象添加到 Orders 数组末尾。

[
  {
    "op": "add",
    "path": "/customerName",
    "value": "Barry"
  },
  {
    "op": "add",
    "path": "/orders/-",
    "value": {
      "orderName": "Order2",
      "orderType": null
    }
  }
]

删除操作The remove operation

• 如果 path 指向数组元素：删除元素。
• 如果 path 指向属性：
  • 如果要修补的资源是一个动态对象：删除属性。
  • 如果要修补的资源是一个静态对象：
    • 如果属性可以为 Null：将其设置为 null。
    • 如果属性不可以为 Null，将其设置为 default<T>。

以下示例修补程序文档将 CustomerName 设置为 null 并删除 Orders[0]。

[
  {
    "op": "remove",
    "path": "/customerName"
  },
  {
    "op": "remove",
    "path": "/orders/0"
  }
]

替换操作The replace operation

此操作在功能上与后跟 remove 的 add 相同。

以下示例修补程序文档设置 CustomerName 的值，并将 Orders[0] 替换为新的 Order 对象。

[
  {
    "op": "replace",
    "path": "/customerName",
    "value": "Barry"
  },
  {
    "op": "replace",
    "path": "/orders/0",
    "value": {
      "orderName": "Order2",
      "orderType": null
    }
  }
]

移动操作The move operation

• 如果 path 指向数组元素：将 from 元素复制到 path 元素的位置，然后对 remove 元素运行 from 操作。
• 如果 path 指向属性：将 from 属性的值复制到 path 属性，然后对 remove 属性运行 from 操作。
• 如果 path 指向不存在的属性：
  • 如果要修补的资源是一个静态对象：请求失败。
  • 如果要修补的资源是一个动态对象：将 from 属性复制到 path 指示的位置，然后对 remove 属性运行 from 操作。

以下示例修补程序文档：

• 将 Orders[0].OrderName 的值复制到 CustomerName。
• 将 Orders[0].OrderName 设置为 null。
• 将 Orders[1] 移动到 Orders[0] 之前。

[
  {
    "op": "move",
    "from": "/orders/0/orderName",
    "path": "/customerName"
  },
  {
    "op": "move",
    "from": "/orders/1",
    "path": "/orders/0"
  }
]

复制操作The copy operation

此操作在功能上与不包含最后 move 步骤的 remove 操作相同。

以下示例修补程序文档：

• 将 Orders[0].OrderName 的值复制到 CustomerName。
• 将 Orders[1] 的副本插入到 Orders[0] 之前。

[
  {
    "op": "copy",
    "from": "/orders/0/orderName",
    "path": "/customerName"
  },
  {
    "op": "copy",
    "from": "/orders/1",
    "path": "/orders/0"
  }
]

测试操作The test operation

如果 path 指示的位置处的值与 value 中提供的值不同，则请求会失败。在这种情况下，整个 PATCH 请求会失败，即使修补程序文档中的所有其他操作均成功也是如此。

test 操作通常用于在发生并发冲突时阻止更新。

如果 CustomerName 的初始值是“John”，则以下示例修补程序文档不起任何作用，因为测试失败：

[
  {
    "op": "test",
    "path": "/customerName",
    "value": "Nancy"
  },
  {
    "op": "add",
    "path": "/customerName",
    "value": "Barry"
  }
]

获取代码Get the code

查看或下载示例代码。（下载方法）。

若要测试此示例，请使用以下设置运行应用并发送 HTTP 请求：

• URL：http://localhost:{port}/jsonpatch/jsonpatchwithmodelstate
• HTTP 方法：PATCH
• 标头：Content-Type: application/json-patch+json
• Body：从json项目文件夹复制并粘贴一个 json 修补文档示例。

其他资源Additional resources

• IETF RFC 5789 PATCH 方法规范
• IETF RFC 6902 JSON 修补程序规范
• IETF RFC 6901 JSON 修补程序路径格式规范
• JSON 路径文档。包括指向用于创建 JSON 修补程序文档的资源的链接。
• ASP.NET Core JSON 修补程序源代码

本文介绍如何处理 ASP.NET Core Web API 中的 JSON 修补程序请求。

PATCH HTTP 请求方法PATCH HTTP request method

PUT 和 PATCH 方法用于更新现有资源。它们之间的区别是，PUT 会替换整个资源，而PATCH 仅指定更改。

JSON 修补程序JSON Patch

JSON 修补程序是一种格式，用于指定要应用于资源的更新。JSON 修补程序文档有一个操作数组。每个操作标识特定类型的更改，例如添加数组元素或替换属性值。

例如，以下 JSON 文档表示资源、资源的 JSON 修补程序文档和应用修补程序操作的结果。

资源示例Resource example

{
  "customerName": "John",
  "orders": [
    {
      "orderName": "Order0",
      "orderType": null
    },
    {
      "orderName": "Order1",
      "orderType": null
    }
  ]
}

JSON 修补程序示例JSON patch example

[
  {
    "op": "add",
    "path": "/customerName",
    "value": "Barry"
  },
  {
    "op": "add",
    "path": "/orders/-",
    "value": {
      "orderName": "Order2",
      "orderType": null
    }
  }
]

在上述 JSON 中：

• op 属性指示操作的类型。
• path 属性指示要更新的元素。
• value 属性提供新值。

修补程序之后的资源Resource after patch

下面是应用上述 JSON 修补程序文档后的资源：

{
  "customerName": "Barry",
  "orders": [
    {
      "orderName": "Order0",
      "orderType": null
    },
    {
      "orderName": "Order1",
      "orderType": null
    },
    {
      "orderName": "Order2",
      "orderType": null
    }
  ]
}

通过将 JSON 修补程序文档应用于资源所做的更改是原子操作：如果列表中的任何操作失败，则不会应用列表中的任何操作。

路径语法Path syntax

操作对象的路径属性的级别之间有斜杠。例如，"/address/zipCode" 。

使用从零开始的索引来指定数组元素。addresses 数组的第一个元素将位于 /addresses/0。若要将 add 置于数组末尾，请使用连字符 (-)，而不是索引号：/addresses/-。

操作Operations

下表显示了 JSON 修补程序规范中定义的支持操作：

ASP.NET Core 中的 JSON 修补程序JsonPatch in ASP.NET Core

Microsoft.AspNetCore.JsonPatch NuGet 包中提供了 JSON 修补程序的 ASP.NET Core 实现。该包包含在 Microsoft.AspnetCore.App 元包中。

操作方法代码Action method code

在 API 控制器中，JSON 修补程序的操作方法：

• 使用 HttpPatch 属性进行批注。
• 接受 JsonPatchDocument<T>，通常带有 [FromBody]。
• 在修补程序文档上调用 ApplyTo 以应用更改。

下面是一个示例：

[HttpPatch]
public IActionResult JsonPatchWithModelState(
    [FromBody] JsonPatchDocument<Customer> patchDoc)
{
    if (patchDoc != null)
    {
        var customer = CreateCustomer();
        patchDoc.ApplyTo(customer, ModelState);
        if (!ModelState.IsValid)
        {
            return BadRequest(ModelState);
        }
        return new ObjectResult(customer);
    }
    else
    {
        return BadRequest(ModelState);
    }
}

示例应用中的此代码适用于以下 Customer 模型。

public class Customer
{
    public string CustomerName { get; set; }
    public List<Order> Orders { get; set; }
}

public class Order
{
    public string OrderName { get; set; }
    public string OrderType { get; set; }
}

示例操作方法：

• 构造一个 Customer。
• 应用修补程序。
• 在响应的正文中返回结果。

在实际应用中，该代码将从存储（如数据库）中检索数据并在应用修补程序后更新数据库。

模型状态Model state

上述操作方法示例调用将模型状态用作其参数之一的 ApplyTo 的重载。使用此选项，可以在响应中收到错误消息。以下示例显示了 test 操作的“400 错误请求”响应的正文：

{
    "Customer": [
        "The current value 'John' at path 'customerName' is not equal to the test value 'Nancy'."
    ]
}

动态对象Dynamic objects

以下操作方法示例演示如何将修补程序应用于动态对象。

[HttpPatch]
public IActionResult JsonPatchForDynamic([FromBody]JsonPatchDocument patch)
{
    dynamic obj = new ExpandoObject();
    patch.ApplyTo(obj);
    return Ok(obj);
}

添加操作The add operation

• 如果 path 指向数组元素：将新元素插入到 path 指定的元素之前。
• 如果 path 指向属性：设置属性值。
• 如果 path 指向不存在的位置：
  • 如果要修补的资源是一个动态对象：添加属性。
  • 如果要修补的资源是一个静态对象：请求失败。

以下示例修补程序文档设置 CustomerName 的值，并将 Order 对象添加到 Orders 数组末尾。

[
  {
    "op": "add",
    "path": "/customerName",
    "value": "Barry"
  },
  {
    "op": "add",
    "path": "/orders/-",
    "value": {
      "orderName": "Order2",
      "orderType": null
    }
  }
]

删除操作The remove operation

• 如果 path 指向数组元素：删除元素。
• 如果 path 指向属性：
  • 如果要修补的资源是一个动态对象：删除属性。
  • 如果要修补的资源是一个静态对象：
    • 如果属性可以为 Null：将其设置为 null。
    • 如果属性不可以为 Null，将其设置为 default<T>。

以下示例修补程序文档将 CustomerName 设置为 null 并删除 Orders[0]。

[
  {
    "op": "remove",
    "path": "/customerName"
  },
  {
    "op": "remove",
    "path": "/orders/0"
  }
]

替换操作The replace operation

此操作在功能上与后跟 remove 的 add 相同。

以下示例修补程序文档设置 CustomerName 的值，并将 Orders[0] 替换为新的 Order 对象。

[
  {
    "op": "replace",
    "path": "/customerName",
    "value": "Barry"
  },
  {
    "op": "replace",
    "path": "/orders/0",
    "value": {
      "orderName": "Order2",
      "orderType": null
    }
  }
]

移动操作The move operation

• 如果 path 指向数组元素：将 from 元素复制到 path 元素的位置，然后对 remove 元素运行 from 操作。
• 如果 path 指向属性：将 from 属性的值复制到 path 属性，然后对 remove 属性运行 from 操作。
• 如果 path 指向不存在的属性：
  • 如果要修补的资源是一个静态对象：请求失败。
  • 如果要修补的资源是一个动态对象：将 from 属性复制到 path 指示的位置，然后对 remove 属性运行 from 操作。

以下示例修补程序文档：

• 将 Orders[0].OrderName 的值复制到 CustomerName。
• 将 Orders[0].OrderName 设置为 null。
• 将 Orders[1] 移动到 Orders[0] 之前。

[
  {
    "op": "move",
    "from": "/orders/0/orderName",
    "path": "/customerName"
  },
  {
    "op": "move",
    "from": "/orders/1",
    "path": "/orders/0"
  }
]

复制操作The copy operation

此操作在功能上与不包含最后 move 步骤的 remove 操作相同。

以下示例修补程序文档：

• 将 Orders[0].OrderName 的值复制到 CustomerName。
• 将 Orders[1] 的副本插入到 Orders[0] 之前。

[
  {
    "op": "copy",
    "from": "/orders/0/orderName",
    "path": "/customerName"
  },
  {
    "op": "copy",
    "from": "/orders/1",
    "path": "/orders/0"
  }
]

测试操作The test operation

如果 path 指示的位置处的值与 value 中提供的值不同，则请求会失败。在这种情况下，整个 PATCH 请求会失败，即使修补程序文档中的所有其他操作均成功也是如此。

test 操作通常用于在发生并发冲突时阻止更新。

如果 CustomerName 的初始值是“John”，则以下示例修补程序文档不起任何作用，因为测试失败：

[
  {
    "op": "test",
    "path": "/customerName",
    "value": "Nancy"
  },
  {
    "op": "add",
    "path": "/customerName",
    "value": "Barry"
  }
]

获取代码Get the code

查看或下载示例代码。（下载方法）。

若要测试此示例，请使用以下设置运行应用并发送 HTTP 请求：

• URL：http://localhost:{port}/jsonpatch/jsonpatchwithmodelstate
• HTTP 方法：PATCH
• 标头：Content-Type: application/json-patch+json
• Body：从json项目文件夹复制并粘贴一个 json 修补文档示例。

其他资源Additional resources

• IETF RFC 5789 PATCH 方法规范
• IETF RFC 6902 JSON 修补程序规范
• IETF RFC 6901 JSON 修补程序路径格式规范
• JSON 路径文档。包括指向用于创建 JSON 修补程序文档的资源的链接。
• ASP.NET Core JSON 修补程序源代码