JsonSerializer 是 .NET 5+ 默认推荐的内置 JSON 序列化器，性能高且内存友好，但默认不缩进、不忽略 null/默认值、时间类型处理严格，需配置 JsonSerializerOptions 复用实例并合理设置 WriteIndented、IgnoreNullValues、DefaultIgnoreCondition 等选项。
JsonSerializer 是 .NET 5+ 默认推荐的 JSON 序列化器，不是第三方库，不用安装 NuGet 包。它快、安全、内存友好，但默认行为和 Newtonsoft.Json 差异明显——直接照搬旧习惯容易出错。
JsonSerializer.Serialize 输出是压缩格式，没换行也没缩进
默认输出像 {"Date":"2019-08-01T00:00:00-07:00","TemperatureCelsius":25,"Summary":"Hot"}，不适合调试或人工阅读。
- 加缩进需显式传入
JsonSerializerOptions，设WriteIndented = true - 别写
JsonSerializer.Serialize(obj, new JsonSerializerOptions { WriteIndented = true })每次都 new —— 复用实例更高效 - 如果只是临时调试，用
Debug.WriteLine(JsonSerializer.Serialize(obj, new JsonSerializerOptions { WriteIndented = true }))即可，别改生产逻辑
DateTimeOffset 和 DateTime 序列化格式不一致
DateTimeOffset 默认序列化为 ISO 8601 带时区偏移（如 "2019-08-01T00:00:00-07:00"），而 DateTime 默认只保留 Kind（Unspecified/Local/Utc），且不带时区信息，容易在跨系统传输时丢失上下文。
- 统一用
DateTimeOffset字段，避免歧义 - 若必须用
DateTime，通过JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter())不起作用——得注册DateTimeConverter类型转换器，例如options.Converters.Add(new JsonConverter(...)) - 更稳妥的做法：全局配置
options.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull+ 显式处理时间字段的序列化逻辑
Null 值和默认值默认都会被序列化出来
比如 string? Summary = null 或 int TemperatureCelsius = 0，默认全写进 JSON，前端可能误判为“有值”。
- 忽略 null：设
options.IgnoreNullValues = true - 忽略默认值（如 0、false、null）：设
options.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingDefault - 注意：这两个选项不互斥，可以同时开；但
WhenWritingDefault对自定义类不生效，除非该类标记了[JsonIgnore(Condition = ...)] - 字段级控制优先级高于全局选项，例如
[JsonPropertyName("summary")][JsonIgnore(Condition = JsonIgnoreCondition.Never)]能强制包含
异步序列化到文件必须用 Stream，不能用 string + File.WriteAllText
常见错误是先 Serialize 成字符串，再 File.WriteAllText——这会多一次内存拷贝，大对象时易触发 GC 或 OOM。
- 正确做法：用
JsonSerializer.SerializeAsync(stream, obj)，配合await using FileStream fs = File.Create(path) - 注意
FileStream必须以可写模式打开，且不能用File.OpenRead传给SerializeAsync - 如果目标是网络响应（如 ASP.NET Core 的
HttpResponse.Body），直接传 stream 即可，无需中间字符串 - 同步写小文件可用
File.WriteAllText(path, JsonSerializer.Serialize(obj, options))，但记得 options 复用
JsonSerializer 的坑不在语法难，而在默认契约太“严格”——它不自动处理循环引用、不默认忽略 null、不兼容 Newtonsoft 的命名策略。实际项目里，第一个 JsonSerializerOptions 实例最好封装成静态只读字段，所有序列化都复用它，并把 PropertyNamingPolicy、IgnoreNullValues 等关键项设清楚。否则后期排查字段莫名消失或时间格式错乱，会花比写代码多三倍的时间。
