REST API中的Patch请求大家都用错了，这才是正确姿势-51CTO.COM

环境：SpringBoot3.2.5

1. 简介

HTTP PATCH 方法它允许我们对 HTTP 资源进行部分更新。

在篇文章，将带你如何使用 HTTP PATCH 方法和 JSON Patch文档格式对 RESTful 资源进行部分更新。

HTTP PATCH 请求正文（Request Body）描述了如何修改目标资源以生成新版本。简而言之，JSON Patch 格式使用 "一系列操作 "来描述应如何修改目标资源。JSON Patch文档是一个 JSON 对象数组。数组中的每个对象正好代表一个 JSON Patch操作。Request Body请求格式如下：

[
  {
    "op": "replace|add|remove|move|copy|test",
    "path": "/xxx",
    ["value": "value"],
    ["from": "/yyy"]
  },
    ...
]

op：具体的操作
path：资源路径
value：变更值；根据操作op不同，决定是否有该属性
from：资源路径；根据操作op不同，决定是否有该属性

接下来，通过具体的示例来了解 JSON Patch操作。

2. JSON Patch操作

接下来的所有操作都基于下面的资源进行：

{ 
    "id": 1,
    "telephone": "001-555-1234",
    "favorites": ["Milk","Eggs"],
    "communicationPreferences": {"post":true, "email":true}
}

假设有上面的资源数据，下面将分别介绍基于该资源如何进行不同的操作。

2.1 add添加操作

添加操作为对象添加新值。此外，我们还可以用它来更新现有成员，并在指定索引处向数组中插入一个新值。

给favorities数据添加新值，并且插入到第一个位置。

请求Body

{
  "op": "add",
  "path": "/favorites/0",
  "value": "Bread"
}

结果

{
  "id": "1",
  "telephone": "001-555-1234",
  "favorites": ["Bread","Milk","Eggs"],
  "communicationPreferences": {"post":true, "email":true}
}

2.2 remove删除操作

不仅可以删除指定属性的值，如果是数组还可以删除指定索引位置的元素。

删除communicationPreferences属性值

请求Body

{
  "op": "remove",
  "path": "/communicationPreferences"
}

结果

{
  "id": "1",
  "telephone": "001-555-1234",
  "favorites": ["Bread","Milk","Eggs"],
  "communicationPreferences": null
}

2.3 replace替换操作

将目标属性值更新为一个新的值；

更新电话号码；

请求Body

{
  "op": "replace",
  "path": "/telephone",
  "value": "001-555-5678"
}

结果

{ 
  "id": "1", 
  "telephone": "001-555-5678", 
  "favorites": ["Bread","Milk","Eggs"], 
  "communicationPreferences": null
}

2.4 move移动操作

移动操作会移除指定位置的值，并将其添加到目标位置。

移动favorities属性第0号位置元素到最后一个位置。

请求Body

{
  "op": "move",
  "from": "/favorites/0",
  "path": "/favorites/-"
}

结果

{ 
  "id": "1", 
  "telephone": "001-555-5678", 
  "favorites": ["Milk","Eggs","Bread"], 
  "communicationPreferences": null
}

2.5 copy复制操作

复制操作将指定位置的值复制到目标位置。

将favorites属性中的Milk复制一份到该属性的最后位置。

请求Body

{
  "op": "copy",
  "from": "/favorites/0",
  "path": "/favorites/-"
}

结果

{ 
  "id": "1", 
  "telephone": "001-555-5678", 
  "favorites": ["Milk","Eggs","Bread","Milk"], 
  "communicationPreferences": null
}

2.6 test测试操作

测试操作测试 "路径 "上的值是否等于 "值"。

请求Body

{
  "op": "test", 
  "path": "/telephone",
  "value": "001-555-5678"
}

注意：JSON Patch请求的Content-Type类型为：application/json-patch+json

接下来将实战演示在Spring Boot中如何使用JSON Patch。

3. 实战案例

3.1 引入依赖

<dependency>
  <groupId>com.github.java-json-tools</groupId>
  <artifactId>json-patch</artifactId>
  <version>1.13</version>
</dependency>

该组件是RFC 6902（JSON Patch）和RFC 7386（JSON Merge Patch）的实现，其核心使用Jackson（2.2.x）。该组件的特性：

JSON Patch的序列化和JSON与Jackson Merge Patch实例
全面支持RFC 6902操作，包括测试
JSON“差异”(仅RFC 6902)与运算因子分解

接下来进入实践代码的编写

3.2 定义实体类

public class Customer {
  /**编号*/
  private Long id ;
  /**电话*/
  private String telephone ;
  /**收藏集*/
  private List<String> favorites ;
  /**通信首选项*/
  private Map<String, Boolean> communicationPreferences ;
  public Customer(Long id, String telephone, List<String> favorites,
      Map<String, Boolean> communicationPreferences) {
    this.id = id ;
    this.telephone = telephone ;
    this.favorites = favorites ;
    this.communicationPreferences = communicationPreferences ;
  }
  // getters, setters
}

定义异常类

public static class CustomerNotFoundException extends RuntimeException {
}

当没有资源时抛出该异常类

3.3 Service类

@Service
public static class CustomerService {
  // 模拟静态数据
  private static List<Customer> DATAS = List
    .of(new Customer(
          1L, "188", 
          List.of("Milk", "Eggs"), 
          Map.of("phone", true, "email", true)));
  // 根据ID查询操作
  public Optional<Customer> findCustomer(Long id) {
    return DATAS.stream().filter(customer -> customer.getId() == id).findFirst();
  }
}

接下来就是关键的Controller接口的编写了

3.4 Controller接口

@PatchMapping(path = "/{id}", consumes = "application/json-patch+json")
public ResponseEntity<Customer> updateCustomer(@PathVariable Long id, @RequestBody JsonPatch patch) {
  try {
    // 查询资源
    Customer customer = customerService.findCustomer(id).orElseThrow(CustomerNotFoundException::new);
    Customer customerPatched = applyPatchToCustomer(patch, customer);
    return ResponseEntity.ok(customerPatched);
  } catch (JsonPatchException | JsonProcessingException e) {
    return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
  } catch (CustomerNotFoundException e) {
    return ResponseEntity.status(HttpStatus.NOT_FOUND).build();
  }
}
// 将请求的操作转换成真实的资源变更
private Customer applyPatchToCustomer(JsonPatch patch, Customer targetCustomer)
    throws JsonPatchException, JsonProcessingException {
  ObjectMapper objectMapper = new ObjectMapper() ;
  JsonNode patched = patch.apply(objectMapper.convertValue(targetCustomer, JsonNode.class));
  return objectMapper.treeToValue(patched, Customer.class);
}

在该接口中注意以下两点：

consumes属性设置为application/json-patch+json，也就是请求的Content-Type必须是该值。
请求body通过JsonPatch对象接收。

接下来进行测试：

图片

请求Body中定义了2个操作，replace与add。最后返回的结果表明操作成功，数据得到了变更。