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

时间:2023-02-03 21:35:13

原文: JSON Patch With ASP.NET Core
作者:.NET Core Tutorials
译文:如何在ASP.NET Core中使用JSON Patch
地址:https://www.cnblogs.com/lwqlun/p/10433615.html
译者:Lamond Lu

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

JSON Patch是一种使用API显式更新文档的方法。它本身是一种契约,用于描述如何修改文档(例如:将字段的值替换成另外一个值),而不必同时发送其他未更改的属性值。

一个JSON Patch请求是什么样的?

你可以在以下链接(http://jsonpatch.com/)中找到JSON Patch的官方文档,但是这里我们将进一步研究一下如何在ASP.NET Core中实现JSON Patch。

为了演示JSON Patch, 我创建了以下C#对象类, 后续我将使用JSON Patch请求来操作这个对象类的实例。

public class Person
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public List<string> Friends { get; set; }
}

所有的JSON Patch请求都是遵循一个相似的结构。它有一个固定的“操作”列表。每个操作本身拥有3个属性:

  • "op" - 定义了你要执行何种操作,例如add, replace, test等。
  • "path" - 定义了你要操作对象属性路径。用前面的Person类为例,如果你希望修改FirstName属性,那么你使用的操作路径应该是"/FirstName"。
  • "value" - 在大部分情况下,这个属性表示你希望在操作中使用的值。

现在让我们来看一下每一个的操作如何使用。

Add

Add操作通常意味着你要向对象中添加属性,或者向数组中添加项目。对于前者,在C#中是没有用的,因为C#是强类型语言,所以不能将属性添加到编译时尚未定义的对象上。

所以这里如果想往数组中添加项目,PATCH请求的内容应该如下所示。

{ "op": "add", "path": "/Friends/1", "value": "Mike" }

这将在Friends数组的索引1处插入一个"Mike"值。

或者你还可以使用"-"在数组尾部插入记录。

{ "op": "add", "path": "/Friends/-", "value": "Mike" }

Remove

与Add操作类似,删除操作意味着你希望删除对象中属性,或者从数据中删除某一项。但是因为在C#中你无法移除属性,实际操作时,它会将属性的值变更为default(T)。在某些情况下,如果属性是可空的,则会设置属性值为NULL。但是需要小心,因为当在值类型上使用时,例如int, 则该值实际上会重置为"0"。

如果要在对象上删除某一属性以达到重置的效果,你可以使用一下命令。

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

当然你也可以使用删除命令删除数组中的某一项。

{ "op": "remove", "path": "/Friends/1" }

这将删除数组索引为1的项目。但是有时候使用索引从数组中删除数据是非常危险的,因为这里没有一个"where"条件来控制删除, 有可能在删除的时候,数据库中对应数组已经发生变化了。实际上有一个JSON Patch操作可以帮助解决这个问题,后面我会描述它。

Replace

Replace操作和它的字面意思完全一样,可以使用它来替换已有值。针对简单属性,你可以使用如下的命令。

{ "op": "replace", "path": "/FirstName", "value": "Jim" }

你同样可以使用它来替换数组中的对象。

{ "op": "replace", "path": "/Friends/1", "value": "Bob" }

你甚至可以用它来替换整个数组。

{ "op": "replace", "path": "/Friends", "value": ["Bob", "Bill"] }

Copy

Copy操作可以将值从一个路径复制到另一个路径。这个值可以是属性,对象,或者数据。在下面的例子中,我们将FirstName属性的值复制到了LastName属性上。这个命令的使用场景不是很多。

{ "op": "copy", "from": "/FirstName", "path" : "/LastName" }

Move

Move操作非常类似于Copy操作,但是正如它的字面意思,"from"字段的值将被移除。如果你看一下ASP.NET Core的JSON Patch的底层代码,你会发现,它实际上它会在"from"路径上执行Remove操作,在"path"路径上执行Add操作。

{ "op": "move", "from": "/FirstName", "path" : "/LastName" }    

Test

在当前的ASP.NET Core公开发行版中没有Test操作,但是如果你在Github上查看源代码,你会发现微软已经处理了Test操作。Test操作是一种乐观锁定的方法,或者更简单的说,它会检测数据对象从服务器读取之后,是否发生了更改。

我们以如下操作为例。

[
    { "op": "test", "path": "/FirstName", "value": "Bob" }
    { "op": "replace", "path": "/FirstName", "value": "Jim" }
]

这个操作首先会检查"/FirstName"路径的值是否"Bob", 如果是,就将它改为"Jim"。 如果不是,则什么事情都不会发生。这里你需要注意,在一个Test操作的请求体内可以包含多个Test操作,但是如果其中任何一个Test操作验证失败,所以的变更操作都不会被执行。

为什么要使用JSON Patch?

JSON Patch的一大优势在于它的请求操作体很小,只发送对象的更改内容。 但是在ASP.NET Core中使用JSON Patch还有另一个很大的好处,就是C#是一种强类型语言,无法区分是要将模型的值设置为NULL,还是忽略该属性, 而使用JSON Patch可以解决这个问题。

这里如果没有好的例子,很难解释。 所以想象一下我从API请求一个“Person”对象。 在C#中,模型可能如下所示:


public class Person
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
}

当从API返回Json对象时,它看起来可能像这样。

{
    "firstName" : "James", 
    "lastName" : "Smith"
}

现在在前端,如果不使用JSON Patch, 如果我只想更新FirstName, 我可能在请求中附带一下请求体。

{
    "firstName" : "Jim"
}

现在当我在C#中反序列化这个模型时,问题就出现了。不要看下面的代码,想一下此时我们的模型中的属性值是什么?

public class Person
{
    public string FirstName { get; set; } //Jim
    public string LastName { get; set; } //<Null>
}

因为我们发送LastName属性的值,所以它被反序列化为Null。 但这很简单,我们可以忽略NULL的值,只更新我们实际传递的字段。 但这不一定是正确的,如果该字段实际上可以为空呢? 如果我们发送了以下请求体怎么办?

{
    "firstName" : "Jim", 
    "lastName" : null
}

所以现在我们实际上已经指定我们想要取消该字段。但是因为C#是强类型的,所以我们无法在服务器端进行模型绑定的时候,我们无法确定它是否要将该字段的值设置为NULL。

这似乎是一个奇怪的场景,因为前端可以始终发送完整的数据模型,永远不会省略字段。并且在大多数情况下,前端Web库的模型将始终与API的模型匹配。但有一种情况并非如此,那就是移动应用程序。通常向苹果应用商店提交手机应用,可能需要数周时间才能获得批准。在这个时候,你可能还需要在Web或Android应用程序中使用新模型。在不同平台之间实现同步非常困难,而且通常是不可能。虽然API版本确实对解决这个问题有很长的路要走,但我仍然认为JSON Patch在解决这个问题方面具有很大的实用性。

最后,让我们使用JSON Patch!我们可以使用以下JSON Patch请求更新Person对象

[
    {
      "op": "replace",
      "path": "/FirstName",
      "value": "Jim"
    }
]

这明确表示我们想要更改名字而不是其他内容。 它准确的告诉我们到底将要发生什么。

在ASP.NET Core项目中启用JSON Patch

在Visual Studio中,我们可以在Package Manage Console中安装官方的Json Patch库(默认创建的ASP.NET Core项目中没有该库)。

Install-Package Microsoft.AspNetCore.JsonPatch

为了演示,我将添加如下的一个控制器类。这里需要注意我们使用的HTTP verb是HttpPatch, 请求参数的类型是JsonPatchDocument 。 为了更新对象,我们只需要简单调用ApplyTo方法,并传入了需要更新的对象。

[Route("api/[controller]")]
public class PersonController : Controller
{
    private readonly Person _defaultPerson = new Person
    {
        FirstName = "Jim",
        LastName = "Smith"
    };
 
    [HttpPatch("update")]
    public Person Patch([FromBody]JsonPatchDocument<Person> personPatch)
    {
        personPatch.ApplyTo(_defaultPerson);
        return _defaultPerson;
    }
}
 
public class Person
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
}

在以上示例中,我们只是使用了存放在控制器中的简单对象并对其进行了更新,但是在正式的API中,我们需要从数据库中拉取数据对象,更新对象,并重新保存到数据库。

当我们使用如下请求体发送JSON Patch请求时:

[
    {"op" : "replace", "path" : "/FirstName", "value" : "Bob"}
]

我们可以得到如下响应内容:

{
    "firstName": "Bob",
    "lastName": "Smith"
}

真棒! 我们的名字改为Bob! 使用JSON Patch启动和运行真的很简单。

使用Automapper处理JSON Patch请求

针对JSON Patch的使用,最大的问题是,你经常需要从API返回View Model或者DTO, 并生成PATCH请求。但是如果将这些修改请求应用于数据库对象上?大部分情况下,开发人员都挣扎在与此。这里我们可以使用Automapper来帮助完成这个转换的工作。

例如如下代码:


[HttpPatch("update/{id}")]
public Person Patch(int id, [FromBody]JsonPatchDocument<PersonDTO> personPatch)
{
    //获取原始Person对象实例
    PersonDatabase personDatabase = _personRepository.GetById(id); 
    
    //将Person对象实例转换为PersonDTO对象实例
    PersonDTO personDTO = _mapper.Map<PersonDTO>(personDatabase); 
    
    //应用Patch修改
    personPatch.ApplyTo(personDTO);  
    
    //将更新后的PersonDTO对象,重新映射到Person对象实例中
    _mapper.Map(personDTO, personDatabase); 
    
    //将更新后的Person对象实例保存到数据库
    _personRepository.Update(personDatabase); 
 
    return personDTO;
}