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 引入依赖
com.github.java-json-tools
json-patch
1.13
该组件是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 favorites ;
private Map communicationPreferences ;
public Customer(Long id, String telephone, List favorites,
Map 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 DATAS = List
.of(new Customer(
1L, "188",
List.of("Milk", "Eggs"),
Map.of("phone", true, "email", true)));
// 根据ID查询操作
public Optional 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 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。最后返回的结果表明操作成功，数据得到了变更。
