.NET中JSON序列化方案对比与最佳实践

1. .NET对象转JSON的常见方式解析

在.NET开发中，对象与JSON之间的转换是日常开发中最常见的操作之一。无论是Web API的请求响应、配置文件读取还是数据持久化，都离不开JSON序列化。作为一名有多年.NET开发经验的工程师，我经常被问到："到底有几种方式可以实现对象到JSON的转换？"今天我就来系统梳理一下.NET生态中主流的JSON序列化方案。

1.1 为什么需要多种JSON序列化方式

在深入具体实现之前，我们需要理解为什么.NET生态中会存在多种JSON序列化方案。这主要源于以下几个因素：

1. 性能考量：不同序列化库在性能表现上差异显著，特别是在处理大数据量或高频调用场景时
2. 功能需求：有的场景需要丰富的自定义控制（如日期格式、循环引用处理），有的则追求简洁
3. 平台兼容性：不同.NET版本（.NET Framework/.NET Core/.NET 5+）对JSON支持程度不同
4. 历史演进：随着.NET生态发展，新的更优方案不断涌现，但旧方案仍需保持兼容

1.2 主流JSON序列化方案概览

目前.NET生态中主流的JSON序列化方案包括：

1. System.Text.Json：.NET Core 3.0+内置的JSON库，性能优异
2. Newtonsoft.Json：第三方库，功能丰富，长期作为事实标准
3. DataContractJsonSerializer：.NET Framework时代的官方方案
4. JavaScriptSerializer：ASP.NET时代的简易方案
5. 第三方高性能库：如Utf8Json、Jil等

接下来，我将重点分析前两种最常用的方案，并对比它们的适用场景。

2. System.Text.Json深度解析

System.Text.Json是微软在.NET Core 3.0中引入的高性能JSON库，现已成为.NET平台的首推JSON解决方案。

2.1 基本使用方法

csharp复制using System.Text.Json;

// 对象转JSON
var person = new Person { Name = "张三", Age = 30 };
string json = JsonSerializer.Serialize(person);

// JSON转对象
Person deserialized = JsonSerializer.Deserialize<Person>(json);

2.2 核心优势

1. 卓越的性能：比Newtonsoft.Json快2-3倍，内存分配更少
2. 低依赖：作为.NET运行时的一部分，无需额外NuGet包
3. UTF-8原生支持：直接处理UTF-8数据，避免不必要的编码转换
4. 强类型处理：对泛型和值类型有更好的支持

2.3 高级配置选项

csharp复制var options = new JsonSerializerOptions
{
    WriteIndented = true, // 美化输出
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase, // 属性名驼峰式
    Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping, // 宽松字符转义
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull // 忽略null值
};

string json = JsonSerializer.Serialize(person, options);

2.4 实际性能对比

通过BenchmarkDotNet测试10000次序列化操作：

注意：性能数据会随对象复杂度和运行环境变化，但System.Text.Json的优势是普遍存在的

3. Newtonsoft.Json全面指南

Newtonsoft.Json（又称Json.NET）是.NET生态中长期占据统治地位的JSON库，尽管现在被System.Text.Json部分取代，但在许多场景下仍是首选。

3.1 基本使用方法

csharp复制using Newtonsoft.Json;

// 对象转JSON
var person = new Person { Name = "李四", Age = 25 };
string json = JsonConvert.SerializeObject(person);

// JSON转对象
Person deserialized = JsonConvert.DeserializeObject<Person>(json);

3.2 不可替代的优势

1. 更丰富的自定义选项：

   • 复杂的日期格式处理
   • 循环引用处理
   • 多态类型序列化
   • 更灵活的忽略规则

2. 更成熟的生态系统：

   • 与大量第三方库深度集成
   • 更完善的文档和社区支持
   • 长期积累的bug修复和经验

3. 更宽松的兼容性：

   • 支持更旧的.NET版本
   • 对不规则JSON容错性更好

3.3 高级配置示例

csharp复制var settings = new JsonSerializerSettings
{
    Formatting = Formatting.Indented,
    ContractResolver = new CamelCasePropertyNamesContractResolver(),
    NullValueHandling = NullValueHandling.Ignore,
    DateFormatString = "yyyy-MM-dd HH:mm:ss",
    ReferenceLoopHandling = ReferenceLoopHandling.Ignore
};

string json = JsonConvert.SerializeObject(person, settings);

3.4 特殊场景处理

处理多态类型：

csharp复制[JsonConverter(typeof(StringEnumConverter))]
public enum UserType { Admin, Guest }

[KnownType(typeof(Admin))]
[KnownType(typeof(Guest))]
public abstract class User { /*...*/ }

public class Admin : User { /*...*/ }
public class Guest : User { /*...*/ }

处理动态对象：

csharp复制dynamic obj = new JObject();
obj.Name = "王五";
obj.Age = 28;
string json = obj.ToString();

4. 其他序列化方案简析

虽然System.Text.Json和Newtonsoft.Json覆盖了90%的使用场景，但了解其他方案也有其价值。

4.1 DataContractJsonSerializer

这是.NET Framework时代的官方方案，主要特点：

• 基于WCF的数据契约模型
• 需要显式标记[DataContract]和[DataMember]
• 性能一般，但兼容性极好

csharp复制using System.Runtime.Serialization.Json;

var serializer = new DataContractJsonSerializer(typeof(Person));
using var stream = new MemoryStream();
serializer.WriteObject(stream, person);
string json = Encoding.UTF8.GetString(stream.ToArray());

4.2 JavaScriptSerializer

ASP.NET时代的简易方案，现在基本不推荐使用：

• 位于System.Web.Extensions程序集
• 功能简单，性能较差
• 主要用于遗留系统维护

csharp复制using System.Web.Script.Serialization;

var serializer = new JavaScriptSerializer();
string json = serializer.Serialize(person);

4.3 第三方高性能库

Utf8Json：

• 直接处理UTF-8二进制数据
• 零内存分配的序列化
• 需要预编译代码生成

Jil：

• StackOverflow开发的超高性能库
• 有限的配置选项
• 适合固定模式的简单对象

5. 方案选型指南

面对多种选择，如何做出合理决策？以下是我的经验总结：

5.1 首选System.Text.Json的场景

1. 新项目开发，特别是基于.NET Core 3.0+的应用
2. 性能敏感型应用，如高频调用的微服务
3. 希望减少外部依赖的项目
4. 主要处理简单到中等复杂度的对象

5.2 坚持使用Newtonsoft.Json的场景

1. 需要处理复杂对象关系（循环引用、多态类型）
2. 需要高度自定义的序列化行为
3. 维护旧有项目，特别是.NET Framework应用
4. 依赖深度集成Newtonsoft.Json的第三方库

5.3 性能对比决策矩阵

5.4 实际项目经验分享

在我参与的一个高并发API网关项目中，我们从Newtonsoft.Json迁移到System.Text.Json后获得了显著提升：

• 吞吐量提高了约40%
• 内存分配减少了60%
• 99%延迟降低了35%

但迁移过程中也遇到了一些挑战：

1. 日期格式处理差异：Newtonsoft.Json默认使用本地时区，而System.Text.Json默认使用UTC
2. 属性命名策略：两者默认策略不同，需要显式配置保持一致
3. 忽略null值的行为：配置方式完全不同

6. 高级技巧与常见问题

6.1 性能优化实践

使用源生成器（.NET 6+）：

csharp复制[JsonSerializable(typeof(Person))]
public partial class PersonJsonContext : JsonSerializerContext {}

// 使用生成的序列化代码
string json = JsonSerializer.Serialize(person, PersonJsonContext.Default.Person);

池化JsonSerializerOptions：

csharp复制// 避免重复创建配置对象
private static readonly JsonSerializerOptions _options = new() { /*...*/ };

6.2 处理循环引用

Newtonsoft.Json方案：

csharp复制settings.ReferenceLoopHandling = ReferenceLoopHandling.Serialize;
settings.PreserveReferencesHandling = PreserveReferencesHandling.Objects;

System.Text.Json方案：

csharp复制options.ReferenceHandler = ReferenceHandler.Preserve;

6.3 日期时间处理差异

Newtonsoft.Json默认行为：

• DateTimeZoneHandling.Local（本地时区）
• DateFormatHandling.IsoDateFormat（ISO8601）

System.Text.Json默认行为：

• 严格遵循ISO8601-1:2019规范
• 默认使用UTC时区
• 更严格的日期验证

6.4 常见错误与解决方案

System.Text.Json的"对象循环"错误：

plaintext复制System.Text.Json.JsonException: A possible object cycle was detected.

解决方案：

1. 配置ReferenceHandler.Preserve
2. 使用[JsonIgnore]忽略导航属性
3. 考虑DTO模式避免直接序列化实体

Newtonsoft.Json的类型名称处理：

csharp复制// 需要明确指定类型名称处理
settings.TypeNameHandling = TypeNameHandling.Auto;

安全警告：TypeNameHandling.Auto可能导致反序列化安全问题，需谨慎使用

7. 实战案例：电商订单序列化

让我们通过一个电商订单的实际案例，比较不同方案的实现差异。

7.1 领域模型定义

csharp复制public class Order
{
    public int Id { get; set; }
    public DateTime OrderDate { get; set; }
    public Customer Customer { get; set; }
    public List<OrderItem> Items { get; set; }
    public decimal TotalAmount => Items?.Sum(i => i.Subtotal) ?? 0;
}

public class OrderItem
{
    public int ProductId { get; set; }
    public string ProductName { get; set; }
    public decimal Price { get; set; }
    public int Quantity { get; set; }
    public decimal Subtotal => Price * Quantity;
}

public class Customer
{
    public int Id { get; set; }
    public string Name { get; set; }
    public List<Order> Orders { get; set; } // 循环引用
}

7.2 System.Text.Json实现

csharp复制var options = new JsonSerializerOptions
{
    WriteIndented = true,
    ReferenceHandler = ReferenceHandler.Preserve,
    Converters = { new JsonStringEnumConverter() },
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
};

string json = JsonSerializer.Serialize(order, options);

7.3 Newtonsoft.Json实现

csharp复制var settings = new JsonSerializerSettings
{
    Formatting = Formatting.Indented,
    ReferenceLoopHandling = ReferenceLoopHandling.Serialize,
    PreserveReferencesHandling = PreserveReferencesHandling.Objects,
    NullValueHandling = NullValueHandling.Ignore,
    DateFormatString = "yyyy-MM-ddTHH:mm:ssZ"
};

string json = JsonConvert.SerializeObject(order, settings);

7.4 输出结果对比

System.Text.Json输出：

json复制{
  "$id": "1",
  "Id": 1001,
  "OrderDate": "2023-05-15T14:30:00Z",
  "Customer": {
    "$id": "2",
    "Id": 501,
    "Name": "张三",
    "Orders": [
      {
        "$ref": "1"
      }
    ]
  },
  "Items": [
    {
      "ProductId": 2001,
      "ProductName": "智能手机",
      "Price": 5999.00,
      "Quantity": 1,
      "Subtotal": 5999.00
    }
  ],
  "TotalAmount": 5999.00
}

Newtonsoft.Json输出：

json复制{
  "$id": "1",
  "Id": 1001,
  "OrderDate": "2023-05-15T22:30:00+08:00",
  "Customer": {
    "$id": "2",
    "Id": 501,
    "Name": "张三",
    "Orders": [
      {
        "$ref": "1"
      }
    ]
  },
  "Items": [
    {
      "ProductId": 2001,
      "ProductName": "智能手机",
      "Price": 5999.00,
      "Quantity": 1,
      "Subtotal": 5999.00
    }
  ],
  "TotalAmount": 5999.00
}

关键差异点：

1. 日期时间表示（UTC vs 本地时区）
2. 引用标识格式略有不同
3. 默认缩进空格数不同

8. 迁移指南：从Newtonsoft.Json到System.Text.Json

对于现有项目迁移，建议采用渐进式策略：

8.1 兼容性配置

csharp复制services.AddControllers()
    .AddJsonOptions(options =>
    {
        // 尽量接近Newtonsoft.Json的行为
        options.JsonSerializerOptions.PropertyNamingPolicy = null;
        options.JsonSerializerOptions.DictionaryKeyPolicy = null;
        options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter());
        options.JsonSerializerOptions.ReferenceHandler = ReferenceHandler.Preserve;
    });

8.2 常见行为差异处理

大小写策略：

• Newtonsoft.Json默认保留原始大小写
• System.Text.Json默认驼峰式

解决方案：设置PropertyNamingPolicy = null

枚举处理：

• Newtonsoft.Json默认使用数值
• System.Text.Json默认使用字符串名称

解决方案：添加JsonStringEnumConverter

构造函数处理：

• Newtonsoft.Json优先使用无参构造函数
• System.Text.Json要求精确匹配构造函数参数

解决方案：使用[JsonConstructor]属性标记

8.3 渐进式迁移策略

1. 并行运行阶段：

   • 在项目中同时引用两个库
   • 新代码使用System.Text.Json
   • 旧代码逐步迁移

2. 差异封装层：

   csharp复制public static class JsonHelper
   {
       private static readonly JsonSerializerOptions _options = new() { /*...*/ };
       
       public static string Serialize<T>(T obj)
       {
           try {
               return JsonSerializer.Serialize(obj, _options);
           }
           catch (Exception) {
               // 回退到Newtonsoft.Json
               return JsonConvert.SerializeObject(obj);
           }
       }
   }
   

3. 全面迁移阶段：

   • 使用分析器识别不兼容代码
   • 逐步替换所有Newtonsoft.Json调用
   • 最终移除Newtonsoft.Json依赖

9. 特殊场景处理技巧

9.1 处理大型JSON文档

对于超过内存限制的大型JSON文档：

System.Text.Json流式API：

csharp复制await using var stream = new MemoryStream(Encoding.UTF8.GetBytes(json));
var data = await JsonSerializer.DeserializeAsync<LargeData>(stream);

Newtonsoft.Json流式处理：

csharp复制using var textReader = new StringReader(json);
using var jsonReader = new JsonTextReader(textReader);
var serializer = new JsonSerializer();
var data = serializer.Deserialize<LargeData>(jsonReader);

9.2 动态JSON处理

System.Text.Json的JsonNode：

csharp复制JsonNode node = JsonNode.Parse(json);
string name = node["customer"]?["name"]?.GetValue<string>();

Newtonsoft.Json的JObject：

csharp复制JObject obj = JObject.Parse(json);
string name = (string)obj["customer"]?["name"];

9.3 自定义转换器实现

System.Text.Json自定义转换器：

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

    public override void Write(Utf8JsonWriter writer, DateTime value, JsonSerializerOptions options)
    {
        writer.WriteStringValue(value.ToString("yyyy-MM-dd"));
    }
}

Newtonsoft.Json自定义转换器：

csharp复制public class CustomDateTimeConverter : JsonConverter
{
    public override void WriteJson(JsonWriter writer, object value, JsonSerializer serializer)
    {
        writer.WriteValue(((DateTime)value).ToString("yyyy-MM-dd"));
    }

    public override object ReadJson(JsonReader reader, Type objectType, object existingValue, JsonSerializer serializer)
    {
        return DateTime.ParseExact((string)reader.Value, "yyyy-MM-dd", CultureInfo.InvariantCulture);
    }

    public override bool CanConvert(Type objectType) => objectType == typeof(DateTime);
}

10. 性能优化深度实践

10.1 基准测试对比

使用BenchmarkDotNet测试不同场景下的性能表现：

csharp复制[MemoryDiagnoser]
public class JsonBenchmarks
{
    private readonly Order _order = SampleData.CreateLargeOrder();
    private readonly JsonSerializerOptions _stjOptions = new() { /*...*/ };
    private readonly JsonSerializerSettings _nsjSettings = new() { /*...*/ };

    [Benchmark]
    public string SystemTextJson_Serialize() => JsonSerializer.Serialize(_order, _stjOptions);

    [Benchmark]
    public string NewtonsoftJson_Serialize() => JsonConvert.SerializeObject(_order, _nsjSettings);

    [Benchmark]
    public Order SystemTextJson_Deserialize() => JsonSerializer.Deserialize<Order>(_systemTextJson, _stjOptions);

    [Benchmark]
    public Order NewtonsoftJson_Deserialize() => JsonConvert.DeserializeObject<Order>(_newtonsoftJson, _nsjSettings);
}

典型测试结果（复杂对象，1000次操作）：

10.2 内存优化技巧

1. 重用JsonSerializerOptions：

   • 避免每次序列化都创建新配置
   • 配置对象是线程安全的

2. 使用ArrayPool减少分配：

   csharp复制var bufferWriter = new ArrayBufferWriter<byte>();
   using var writer = new Utf8JsonWriter(bufferWriter);
   JsonSerializer.Serialize(writer, data);
   

3. 流式处理大文件：

   • 避免一次性加载整个JSON到内存
   • 使用PipeReader/PipeWriter进行流式处理

10.3 多线程优化

System.Text.Json的JsonSerializerOptions在设计时就考虑了线程安全：

csharp复制// 全局共享的线程安全配置
private static readonly JsonSerializerOptions _options = new() { /*...*/ };

// 多线程安全使用
Parallel.For(0, 100, i => 
{
    string json = JsonSerializer.Serialize(data, _options);
});

而Newtonsoft.Json的JsonSerializerSettings也是线程安全的，可以类似地共享使用。

11. 安全最佳实践

11.1 反序列化安全

System.Text.Json安全特性：

• 默认不允许注释
• 严格的最大深度限制（默认64）
• 不允许尾随逗号
• 强类型绑定减少攻击面

Newtonsoft.Json安全配置：

csharp复制var settings = new JsonSerializerSettings
{
    MaxDepth = 64,
    CheckAdditionalContent = true,
    DateParseHandling = DateParseHandling.DateTimeOffset,
    MetadataPropertyHandling = MetadataPropertyHandling.Default
};

11.2 类型安全处理

避免使用object或dynamic作为反序列化目标类型：

csharp复制// 不安全
var obj = JsonSerializer.Deserialize<object>(json);

// 更安全
var obj = JsonSerializer.Deserialize<SpecificType>(json);

11.3 JSON注入防护

对用户提供的JSON数据进行严格验证：

csharp复制try
{
    var options = new JsonDocumentOptions
    {
        AllowTrailingCommas = false,
        CommentHandling = JsonCommentHandling.Skip,
        MaxDepth = 32
    };
    
    using JsonDocument doc = JsonDocument.Parse(json, options);
    // 处理验证后的数据
}
catch (JsonException ex)
{
    // 处理无效JSON
}

12. 未来发展趋势

12.1 System.Text.Json的演进

1. .NET 8的改进：

   • 更丰富的自定义转换器支持
   • 改进的源生成器
   • 更好的多态序列化支持

2. 性能持续优化：

   • 减少反射使用
   • 更高效的UTF-8处理
   • 更小的内存占用

12.2 行业趋势观察

1. 二进制JSON格式：

   • 如MessagePack、BSON的兴起
   • 在网络传输中逐渐替代文本JSON

2. 模式验证：

   • JSON Schema验证集成
   • 编译时JSON结构检查

3. 跨语言统一：

   • 不同语言JSON库行为趋同
   • 减少跨平台开发的差异

在实际项目中，我建议持续关注System.Text.Json的更新，因为它代表了.NET平台JSON处理的未来方向。对于新项目，除非有特殊需求，否则应优先考虑System.Text.Json。而对于现有项目，可以根据实际情况制定合理的迁移计划。