ASP.NET Core – Web API JSON Patch

前言

依据 Restful 的方式, 修改 resource 要用 PUT, 然后把完整的 resource 发出去, resource 的所有信息都将被更新.

但很多时候我们希望只做局部更新, 而且希望只提供局部的 resource info.

比如有个 person resource

class Person {
    name: string;
    age: number;
}

如果只想修改 age 的话, 那 body 就是 { age : 11 }, 够了.

JSON Path & JSON Merge Path

这种情况下, Restful 对应的方式就是使用 JSON Patch 和 JSON Merge Path

JSON Patch 的 method 是 PATCH, content-type 是 application/json-patch+json

JSON Merge Path 的 method 是 PATCH, content-type 是 application/merge-patch+json

它们比较大的区别在 body

JSON Merge Path 和我们上面期望的比较类似, 就只发想要修改的内容, 其余的就省略掉.

但有一点要留意的是 { age: null }, 这个表达的意思是, delete 掉 age 这个 property, 而不是把 age set value to null.

要把 age set to null, 就一定要用 PUT 或者 JSON Patch

JSON Patch 的 body 是一堆修改的表达格式.

大概长这样:

[
    {
        "op" : "replace" ,
        "path" : "/users/0/email" ,
        "value" : "alice@wonderland.org"
    },
    {
        "op" : "add" ,
        "path" : "/users/-" ,
        "value" : {
            "name" : "Christine",
            "email" : "christine@example.org"
        }
    }
]

op 是 operation, 有 add, remove, replace, move, copy

path 就是定位那个 property 要修改

value 就 new value 咯.

所以 JSON Patch 能做的比 JSON Merge Patch 多, 但是也相对复杂一些.

主要参考:

JSON Patch and JSON Merge Patch

如何在ASP.NET Core中使用JSON Patch

JsonPatch in ASP.NET Core web API

JSON Patch With ASP.NET Core

JSON Merge Patch in .NET Core

JSON Merge Patch in ASP.NET Core

Should I use it?

JSON Patch 其实对前端来说是比较麻烦的, JSON Merge Patch 的 null 概念也容易被坑.

所以我个人觉得 Restful 的东西, 大多时候听听就好, 不要死死跟它.

也可以看看 WEB开发中，使用JSON-RPC好，还是RESTful API好？大宽宽的回答

JSON Patch in ASP.NET Core

首先 ASP.NET Core 没有 build-in JSON Merge Patch.

它目前只有 build-in JSON Patch 但还需要配合 NewtonsoftJson. Issue: JsonPatchDocument should use System.Text.Json in ASP.NET vNext

step by step 看这篇就可以了: JsonPatch in ASP.NET Core web API

前端就是传 operation

后端就是接收, 然后 apply to resource

具体 resource 是一个 DTO, 还是一个 entity, 自由发挥, 后续的 validation 什么的也自由发挥, 它就只是封装了把 operation apply to resource, 让 resource 变化而已.

所以有些人的做法是,

从数据库拿资料放入 DTO

在把 JSON Patch apply to DTO (覆盖原本的值)

这样 DTO 就完整了, 然后可以拿去做验证什么的

再然后把 DTO to Entity 更新数据.

到底这个做法对不对，好不好, 完全是看你要怎么管理.

抽象来看, JSON Patch 的主要职责就是表达如何修改资源, 它就是一个表达而已, 理解的人要做什么那个是理解的人要去实现的部分. 不要被套死死.

另外, 表达只是一种手法, 我们完全可以用其它的表达方式, 也不一定非要用 JSON Patch. 用它只是因为它有个规范, 有搭配一些便利的工具 (比如上面这个 apply to 的功能)

如果我们的场景比较特殊, 我们完全可以自己搞一套自己的规则 (要知道所有规则都是一点点 build 起来的, 法律也有 cover 不到的场景, 每年也都要修订, 没有绝对的)