.NET 中的 Json 使用体验

本文主要总结介绍 .NET 中的对 Json 数据使用在使用过程中的关于编码、循环引用、时间格式化的一些问题

背景

第一次接触 .Net 是2012年刚进入大学时，之后也一直作为桌面编程语言来使用。工作后，刚开始项目上更多的是使用 PHP 来快速开发，直到去年某次突然发现 .NET 竟不知道什么时候开始不仅跨平台还开源了。

看着微软的官方文档异常激动，按捺不住，拿一个项目上手试了一下，那个时候啥也不懂，嫌弃 JwtBearer 给我引了一大堆 dll，然后自己看文档用中间件造了轮子；而且那个时候我不知道有 EF core，也不懂什么 DBfirst，直接刀耕火种，手写 SQL，把自己累的够呛。当然在各种项目的使用中也或多或少出现了各种问题，现将使用 Json 格式相关的内容总结下来以供大家参考。

问题概览

中文 Unicode 和 字符转义 问题

中文 Unicode 这个问题在 ASP.NET Core 的返回中正常并不会出现，而是在控制台中使用 JsonSerializer.Serialize 将对象转为 json 时发生，解决方案也很简单，只需要通过 JsonSerializerOptions 设置要在转义字符串时使用的编码器即可。

var options = new JsonSerializerOptions { Encoder = JavaScriptEncoder.Create(UnicodeRanges.All) };
1

在不需要转移特殊符号的场景下，使用 JsonSerializer.Serialize 时，传入上方的 options 即可。

当你前往官网仔细研究这个 UnicodeRanges 的时候，你会发现 Unicode 块竟然还有 YijingHexagramSymbols 易经八卦符号 ䷀（乾）䷁（坤）等共六十四卦，说实话我还是第一次发现，遥想当年汉字输入都是问题。八卦是我们东方人得天独厚的文化，“易有太极，是生两仪，两仪生四象，四象生八卦。” 八卦亦可用二进制表示，然后通过 8x8 的矩阵就成了易经六十四卦。

字符转义问题在 ASP.NET Core 的返回中正常并不会出现，而是在控制台中使用时，这个和上一个问题类似。若要最大程度地减少转义（肯定是已含上面的了），可以使用 JavaScriptEncoder.UnsafeRelaxedJsonEscaping。

var options = new JsonSerializerOptions { Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping };
1

这里需要注意的是，使用该配置后，此时你需要额外注意 XSS 或信息泄露攻击的可能。

另外，在非业务场景下，只是为了展示测试时，我们可以设置 JsonSerializerOptions 的 WriteIndented 为 true，这样 JSON 的返回只是整理好格式的易读形式。

以上问题更详细的说明，可以查看微软官方的文档 如何使用 System.Text.Json 自定义字符编码。

时间问题

时间格式化的问题，主要是国情问题和能否直接显示给客户的问题。若是有国际化的问题，那就要额外再加一些其他逻辑处理了。其实我觉得这个丢给前端也挺好嘛，嘿嘿嘿。

现在我们在这样一个接口：

app.MapGet("/test", () =>
{
    return new
    {
        now = DateTime.Now,
        time = TimeOnly.FromDateTime(DateTime.Now),
        day = DateOnly.FromDateTime(DateTime.Now)
    };
});
1
2
3
4
5
6
7
8
9

需要注意的是，当前 .NET 6 是不支持 TimeOnly 和 DateTime 直接返回的，需要 .ToString()，直接返回是会报下面的错误的：

System.NotSupportedException: Serialization and deserialization of 'System.TimeOnly' instances are not supported. 
1

转为字符后输出结果如下：

{
  "now": "2022-10-30T14:43:02.0027311+08:00",
  "time": "14:43",
  "day": "2022/10/30"
}
1
2
3
4
5

在 .NET 7 的当前预览版中，已经支持了 TimeOnly 和 DateOnly 的直接序列化 https://github.com/dotnet/runtime/pull/69160。

更改为 .NET7 后，其输出结果如下：

{
  "now": "2022-10-30T14:53:22.095974+08:00",
  "time": "14:53:22.0959758",
  "day": "2022-10-30"
}
1
2
3
4
5

可以看到返回的差异还是挺大的，如果返回不合你的心意，怎么能让其统一呢？这里就需要用到注册的用户定义的转换器，下面提供三个时间处理的样例，大家可以按需求复制粘贴，其实代码都类似的。

处理日期时间的：

using System.Text.Json;
using System.Text.Json.Serialization;
internal class JsonDateTimeConverter : JsonConverter<DateTime>
{
    public string Format { get; set; } = "yyyy-MM-dd HH:mm:ss";
    public override DateTime Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) => DateTime.Parse(reader.GetString());
    public override void Write(Utf8JsonWriter writer, DateTime value, JsonSerializerOptions options) => writer.WriteStringValue(value.ToString(this.Format));
}
1
2
3
4
5
6
7
8

处理日期的：

using System.Text.Json;
using System.Text.Json.Serialization;
internal class JsonDateOnlyConverter : JsonConverter<DateOnly>
{
    public string Format { get; set; } = "yyyy-MM-dd";
    public override DateOnly Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) => DateOnly.Parse(reader.GetString());
    public override void Write(Utf8JsonWriter writer, DateOnly value, JsonSerializerOptions options) => writer.WriteStringValue(value.ToString(this.Format));
}
1
2
3
4
5
6
7
8

处理时间的：

using System.Text.Json;
using System.Text.Json.Serialization;
internal class JsonTimeOnlyConverter : JsonConverter<TimeOnly>
{
    public string Format { get; set; } = "HH:mm:ss";
    public override TimeOnly Read(ref Utf8JsonReader reader,Type typeToConvert, JsonSerializerOptions options) => TimeOnly.Parse(reader.GetString());
    public override void Write(Utf8JsonWriter writer, TimeOnly value,JsonSerializerOptions options) => writer.WriteStringValue(value.ToString(this.Format));
}
1
2
3
4
5
6
7
8

使用时可以直接引用，也可以设置格式方式。

builder.Services.Configure<JsonOptions>(options => {
    options.SerializerOptions.Converters.Add(new JsonDateTimeConverter() { Format = "yyyy年MM月dd日 HH:mm:ss" });
    options.SerializerOptions.Converters.Add(new JsonDateOnlyConverter());
    options.SerializerOptions.Converters.Add(new JsonTimeOnlyConverter());
});
1
2
3
4
5

输出结果：

{
  "now": "2022年10月30日 15:12:54",
  "time": "15:12:54",
  "day": "2022-10-30"
}
1
2
3
4
5

循环引用

循环引用，主要报错信息如下：

System.Text.Json.JsonException: A possible object cycle was detected. This can either be due to a cycle or if the object depth is larger than the maximum allowed depth of 64.
1

以下代码是为了复现而复现，当然实际情况我们遇到的话，往往是不经意间就出现了。

internal class  User{
    public string Name {get;set;}
    public Role Role {get;set;}
}

internal class  Role{
    public string RoleName {get;set;}
    public User[] Users {get;set;}
}

app.MapGet("/test", () =>
{
    var role = new Role(){RoleName = "小组长"};
    var user = new User(){Name = "王小明"};
    
    user.Role = role;
    role.Users = new User[]{user};
    
    return new {
        user = user
    };
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

方案一：

如果循环的只是为了编码查找方便，或者说此接口没必要输出的情况下，可以直接标记为忽略，不进行 json 输出。

internal class Role
{
    public string RoleName { get; set; }

    [JsonIgnore]
    public User[] Users { get; set; }
}
1
2
3
4
5
6
7

方案二：

ASP.NET 中，需要配置：

builder.Services.Configure<JsonOptions>(options => {
    options.SerializerOptions.ReferenceHandler = ReferenceHandler.IgnoreCycles;
});
1
2
3

控制台程序或命令行打印时：

var options = new JsonSerializerOptions { ReferenceHandler = ReferenceHandler.IgnoreCycles };
1

最后

在这里还是要再感谢一下杨老师，还好在大学的时候某次见面会加了微信，在他朋友圈看到在推录制的 .NET 6教程 。不然说不定目前我还是在刀耕火种阶段，哈哈哈……