从 Newtonsoft.Json 迁移到 System.Text.Json

一.写在前面#

System.Text.Json 是 .NET Core 3 及以上版本内置的 Json 序列化组件，刚推出的时候经常看到踩各种坑的吐槽，现在经过几个版本的迭代优化，提升了易用性，修复了各种问题，是时候考虑使用 System.Text.Json 了。本文将从使用层面来进行对比。

System.Text.Json 在默认情况下十分严格，避免进行任何猜测或解释，强调确定性行为。比如：字符串默认转义，默认不允许尾随逗号，默认不允许带引号的数字等，不允许单引号或者不带引号的属性名称和字符串值。 该库是为了实现性能和安全性而特意这样设计的。Newtonsoft.Json 默认情况下十分灵活。

关于性能，参考 Incerry 的性能测试：.NET性能系列文章二：Newtonsoft.Json vs. System.Text.Json ，如果打算使用 .NET 7 不妨考虑一下 System.Text.Json。

Newtonsoft.Json 使用 13.0.2 版本，基于 .NET 7。

二.序列化#

1.序列化#

定义 Class

public class Cat
{
    public string? Name { get; set; }
    public int Age { get; set; }
}

序列化

var cat = new Cat() { Name = "xiaoshi", Age = 18 };

Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat));
// output: {"Name":"xiaoshi","Age":18}
Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat));
// output: {"Name":"xiaoshi","Age":18}

变化：JsonConvert.SerializeObject()->JsonSerializer.Serialize()

2.忽略属性#

2.1 通用#

[Newtonsoft.Json.JsonIgnore]
[System.Text.Json.Serialization.JsonIgnore]
public int Age { get; set; }

输出：

var cat = new Cat() { Name = "xiaoshi", Age = 18 };

Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat));
// output: {"Name":"xiaoshi"}
Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat));
// output: {"Name":"xiaoshi"}

变化：无

2.2 忽略所有只读属性#

代码：

public class Cat
{
    public string? Name { get; set; }
    
    public int Age { get;  }

    public Cat(int age)
    {
        Age = age;
    }
}

var cat = new Cat(18) { Name = "xiaoshi"};
var options = new System.Text.Json.JsonSerializerOptions
{
    IgnoreReadOnlyProperties = true,
};
Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat, options));
// output: {"Name":"xiaoshi"}

Newtonsoft.Json 需要自定义 ContractResolver 才能实现：https://stackoverflow.com/questions/45010583

2.3 忽略所有 null 属性#

代码：

var cat = new Cat() { Name = null,Age = 18};

var op = new Newtonsoft.Json.JsonSerializerSettings()
{
    NullValueHandling =NullValueHandling.Ignore
};

Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat,op));
// output: {"Name":"xiaoshi"}


var options = new System.Text.Json.JsonSerializerOptions
{
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
};
Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat, options));
// output: {"Name":"xiaoshi"}

默认情况下两者都是不忽略的，需要自行设置

2.4 忽略所有默认值属性#

代码：

var cat = new Cat() { Name = "xiaoshi",Age = };

var op = new Newtonsoft.Json.JsonSerializerSettings()
{
    DefaultValueHandling = DefaultValueHandling.Ignore
};

Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat,op));
// output: {"Name":"xiaoshi"}


var options = new System.Text.Json.JsonSerializerOptions
{
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingDefault
};
Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat, options));
// output: {"Name":"xiaoshi"}

不管是引用类型还是值类型都具有默认值，引用类型为 null，int 类型为 0。

两者都支持此功能。

3.大小写#

默认情况下两者序列化都是 Pascal 命名，及首字母大写，在 JavaScript 以及 Java 等语言中默认是使用驼峰命名，所以在实际业务中是离不开使用驼峰的。

代码：

var cat = new Cat() { Name = "xiaoshi",Age = };

var op = new Newtonsoft.Json.JsonSerializerSettings()
{
    ContractResolver = new CamelCasePropertyNamesContractResolver()
};

Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat,op));
// output: {"name":"xiaoshi","age":0}


var options = new System.Text.Json.JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
};
Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat, options));
// output: {"name":"xiaoshi","age":0}

4.字符串转义#

System.Text.Json 默认会对非 ASCII 字符进行转义，会将它们替换为 \uxxxx，其中 xxxx 为字符的 Unicode 代码。这是为了安全而考虑（XSS 攻击等），会执行严格的字符转义。而 Newtonsoft.Json 默认则不会转义。

默认：

var cat = new Cat() { Name = "小时",Age = };

var op = new Newtonsoft.Json.JsonSerializerSettings()
{
    ContractResolver = new CamelCasePropertyNamesContractResolver()
};

Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat,op));
// output: {"name":"小时","age":0}


var options = new System.Text.Json.JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
};
Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat, options));
// output: {"name":"\u5C0F\u65F6","age":0}

System.Text.Json 关闭转义：

var options = new System.Text.Json.JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping,
};
Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat, options));
// output: {"name":"小时","age":0}

Newtonsoft.Json 开启转义：

var op = new Newtonsoft.Json.JsonSerializerSettings()
{
    ContractResolver = new CamelCasePropertyNamesContractResolver(),
    StringEscapeHandling = StringEscapeHandling.EscapeNonAscii
};

Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat,op));
// output: {"name":"\u5c0f\u65f6","age":0}

详细说明：如何使用 System.Text.Json 自定义字符编码

5.自定义转换器#

自定义转换器 Converter，是我们比较常用的功能，以自定义 Converter 来输出特定的日期格式为例。

Newtonsoft.Json:

public class CustomDateTimeConverter : IsoDateTimeConverter
{
    public CustomDateTimeConverter()
    {
        DateTimeFormat = "yyyy-MM-dd";
    }

    public CustomDateTimeConverter(string format)
    {
        DateTimeFormat = format;
    }
}

// test
var op = new Newtonsoft.Json.JsonSerializerSettings()
{
    ContractResolver = new CamelCasePropertyNamesContractResolver(),
    Converters = new List<JsonConverter>() { new CustomDateTimeConverter() }
};

Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat,op));
// output: {"name":"xiaoshi","now":"2023-02-13","age":0}

System.Text.Json:

public class CustomDateTimeConverter : JsonConverter<DateTime>
{
    public override DateTime Read(
        ref Utf8JsonReader reader,
        Type typeToConvert,
        JsonSerializerOptions options) =>
        DateTime.ParseExact(reader.GetString()!,
            "yyyy-MM-dd", CultureInfo.InvariantCulture);

    public override void Write(
        Utf8JsonWriter writer,
        DateTime dateTimeValue,
        JsonSerializerOptions options) =>
        writer.WriteStringValue(dateTimeValue.ToString(
            "yyyy-MM-dd", CultureInfo.InvariantCulture));
}

// test
var options = new System.Text.Json.JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    Converters = { new CustomDateTimeConverter() }
};
Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat, options));
// output: {"name":"xiaoshi","age":0,"now":"2023-02-13"}

两者的使用方法都是差不多的，只是注册优先级有所不同。

Newtonsoft.Json：属性上的特性>类型上的特性>Converters 集合

System.Text.Json：属性上的特性>Converters 集合>类型上的特性

官方文档：如何编写用于 JSON 序列化的自定义转换器

6.循环引用#

有如下定义：

public class Cat
{

    public string? Name { get; set; }

    public int Age { get; set; }
    
    public Cat Child { get; set; }
    
    public Cat Parent { get; set; }
}

var cat1 = new Cat() { Name = "xiaoshi",Age = };
var cat2 = new Cat() { Name = "xiaomao",Age = };

cat1.Child = cat2;
cat2.Parent = cat1;

序列化 cat1 默认两者都会抛出异常，如何解决？

Newtonsoft.Json：

var op = new Newtonsoft.Json.JsonSerializerSettings()
{
    ContractResolver = new CamelCasePropertyNamesContractResolver(),
    ReferenceLoopHandling = ReferenceLoopHandling.Ignore,
};

Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat1,op));

设置 ReferenceLoopHandling.Ignore 即可。

System.Text.Json：

var options = new System.Text.Json.JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    ReferenceHandler = ReferenceHandler.IgnoreCycles
};
Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat1, options));

等效设置