1. 项目概述：为什么C#开发者绕不开Newtonsoft.Json

在C#的日常开发里，处理JSON数据就像吃饭喝水一样平常。无论是调用Web API、读写配置文件，还是做数据持久化，JSON都是那个绕不开的“中间人”。而提到C#里的JSON处理，Newtonsoft.Json（也叫Json.NET）几乎是一个图腾般的存在。尽管.NET Core/5+之后官方推出了System.Text.Json，但Json.NET凭借其极致的灵活性、强大的功能和广泛的生态，至今仍在无数项目（尤其是遗留系统和复杂业务场景）中扮演着核心角色。

我自己在十多年的C#开发生涯中，从WebForm时代到现在的.NET 8，Json.NET始终是工具箱里的“瑞士军刀”。它解决的远不止是简单的序列化和反序列化。当你需要处理不规则的JSON结构、自定义日期格式、处理循环引用、或者进行高性能的流式读写时，Json.NET提供的丰富API和配置选项总能给你恰到好处的支持。很多新手觉得用JsonConvert.SerializeObject和DeserializeObject就足够了，但这只是揭开了它能力的冰山一角。深入理解它的高级特性，比如契约解析器（ContractResolver）、JSON路径查询（JToken、SelectToken）、以及序列化设置（JsonSerializerSettings），才能真正让你在复杂的数据处理场景下游刃有余。

这篇文章，我就结合自己踩过的无数坑和积累的经验，带你从“会用”到“精通”Json.NET。我们会涵盖从基础操作到高级定制，从性能优化到异常处理的全链路实践。无论你是正在维护一个使用了Json.NET的老项目，还是在新项目中评估JSON方案，这些内容都能给你提供直接的参考。

2. 核心设计思路：理解Json.NET的灵活性与控制力

Json.NET的设计哲学核心是“灵活与控制”。与后来者System.Text.Json强调性能和简易性不同，Json.NET选择为开发者暴露尽可能多的控制点。这种设计使得它能够处理各种“非标准”但现实中又极其常见的JSON场景。

2.1 基于契约（Contract）的序列化模型

这是Json.NET灵活性的基石。序列化或反序列化一个对象时，Json.NET并非直接操作对象的属性，而是通过一个“契约”（Contract）抽象层。这个契约描述了如何将对象的成员（属性、字段）映射到JSON的属性和值。JsonSerializerSettings里的ContractResolver属性就是用来定制这个映射规则的入口。

为什么需要这个？举个例子，你有一个第三方API返回的JSON，其属性名是蛇形命名法（如user_name），但你的C#模型属性是帕斯卡命名法（UserName）。又或者，你希望序列化时忽略所有值为null的属性，或者只序列化带有特定标记的属性。这些需求，都可以通过自定义IContractResolver来实现。DefaultContractResolver类提供了丰富的可重写方法（如CreateProperty），让你能精细控制每个属性是否被序列化、它的JSON属性名是什么、用什么转换器（JsonConverter）等。

注意：自定义ContractResolver虽然强大，但创建和缓存策略不当会影响性能。通常建议将其实例缓存起来，在整个应用程序生命周期内复用。

2.2 动态与静态类型处理的统一

Json.NET优雅地统一了对静态类型（你的强类型C#类）和动态类型（运行时才知结构的JSON）的处理。对于强类型，你使用泛型方法DeserializeObject<T>。对于完全未知或结构多变的JSON，你可以使用JToken体系（JObject,JArray,JValue）来以动态方式解析和操作。

JToken及其派生类构成了一个LINQ to JSON的查询体系。你可以像使用XDocument处理XML一样，使用JObject.Parse将JSON字符串加载为一个可遍历、可查询的对象树，然后通过索引器或SelectToken方法（支持JSON Path表达式）来访问深层嵌套的数据。这在处理配置文件、解析不完全符合你模型的API响应时极其有用。

// 示例：动态解析复杂JSON片段 string json = @"{ 'order': { 'id': 123, 'items': [ {'name': 'Widget', 'price': 9.99}, {'name': 'Gadget', 'price': 19.99} ] } }"; JObject orderObj = JObject.Parse(json); int orderId = (int)orderObj["order"]["id"]; // 通过索引器访问 decimal totalPrice = orderObj.SelectToken("order.items[*].price").Sum(); // 使用JSON Path和LINQ

这种动静结合的能力，让Json.NET能够适应从严格领域模型到灵活脚本处理的广泛场景。

2.3 可扩展的转换器（JsonConverter）体系

JsonConverter是Json.NET处理特殊序列化需求的终极武器。当内置的序列化规则无法满足需求时，你可以编写自定义的JsonConverter。

你需要自定义转换器的典型场景包括：

1. 处理特殊的日期/时间格式：API返回的可能是Unix时间戳或某种自定义字符串格式。
2. 序列化枚举为字符串而非数字：提高JSON的可读性。
3. 处理多态类型：JSON中的一个字段，根据其值可能对应多个不同的子类。
4. 自定义集合或字典的序列化方式。
5. 处理循环引用：虽然可以通过ReferenceLoopHandling设置，但有时需要更精细的控制。

编写一个自定义JsonConverter需要实现三个主要方法：CanConvert（判断该转换器是否能处理指定类型）、WriteJson（将C#对象写入JSON）、ReadJson（从JSON读取并构造C#对象）。通过转换器，你可以完全掌控序列化和反序列化的过程。

3. 基础到进阶：核心API详解与实战

让我们从最常用的API开始，逐步深入到高级配置和定制化操作。

3.1 序列化与反序列化：不止是简单的调用

JsonConvert.SerializeObject和DeserializeObject<T>是入口点，但它们的威力来自于可传入的JsonSerializerSettings参数。

基础但关键的设置：

• Formatting.Indented：生成格式化的、带缩进的JSON字符串，便于调试和阅读。生产环境通常使用Formatting.None以节省空间。
• NullValueHandling：控制如何处理null值。NullValueHandling.Ignore会在序列化时跳过值为null的属性，让生成的JSON更简洁。
• DefaultValueHandling：控制如何处理默认值（如int的0，bool的false）。同样可以设置为忽略。
• ReferenceLoopHandling：处理对象循环引用。ReferenceLoopHandling.Ignore会忽略导致循环的引用，ReferenceLoopHandling.Serialize则使用$ref和$id标识符来保持引用关系（但并非所有JSON解析器都支持此规范）。
• DateFormatString：自定义日期序列化的格式。例如"yyyy-MM-ddTHH:mm:ssZ"。

public class Product { public string Name { get; set; } public decimal? Price { get; set; } // 可空类型 public DateTime CreatedAt { get; set; } } var product = new Product { Name = "Laptop", Price = null, CreatedAt = DateTime.UtcNow }; var settings = new JsonSerializerSettings { Formatting = Formatting.Indented, NullValueHandling = NullValueHandling.Ignore, DateFormatString = "yyyy-MM-dd" }; string json = JsonConvert.SerializeObject(product, settings); // 输出：{"Name":"Laptop","CreatedAt":"2023-10-27"}

反序列化时的类型匹配与容错：

反序列化时，JSON中的属性如果不存在于目标类型中，默认会被忽略（MissingMemberHandling默认为Ignore）。你可以通过设置MissingMemberHandling.Error来让它在遇到未知属性时抛出异常，这在严格校验API响应时很有用。

对于JSON中的null值反序列化到不可空的值类型（如int）时，会引发错误。你需要确保模型属性使用可空类型（int?），或者使用DefaultValueHandling.Populate配合属性的[DefaultValue]特性。

3.2 使用JToken进行动态JSON操作

当JSON结构不稳定或你只想提取其中一部分数据时，JToken家族是你的最佳选择。

1. 解析与导航：使用JObject.Parse、JArray.Parse或通用的JToken.Parse来加载JSON字符串。之后可以通过多种方式访问数据：

• 索引器：jObject["propertyName"]或jArray[0]。返回的是JToken，需要类型转换。
• Value 方法：安全地获取值，如jToken.Value<string>("name")。
• SelectToken方法：使用JSON Path表达式进行查询，功能强大。

string complexJson = @"{ 'store': { 'book': [ { 'title': 'Clean Code', 'author': 'Robert C. Martin', 'price': 42.0 }, { 'title': 'The Pragmatic Programmer', 'author': 'Andrew Hunt', 'price': 38.5 } ], 'bicycle': { 'color': 'red', 'price': 199.95 } } }"; JToken root = JToken.Parse(complexJson); // 获取所有书名 var titles = root.SelectTokens("$.store.book[*].title").Select(t => t.Value<string>()).ToList(); // 结果: ["Clean Code", "The Pragmatic Programmer"] // 修改自行车价格 root.SelectToken("$.store.bicycle.price").Replace(179.95); // 添加一个新属性 (root.SelectToken("$.store.bicycle") as JObject).Add("gears", 21);

2. 创建与修改JSON：你也可以从头开始构建JSON对象。

JObject newObj = new JObject( new JProperty("id", 1), new JProperty("name", "Test"), new JProperty("tags", new JArray("csharp", "json")) ); string outputJson = newObj.ToString(Formatting.Indented);

3. LINQ to JSON：JToken实现了IEnumerable<JToken>，因此可以无缝使用LINQ进行查询和转换，与查询内存中的集合一样直观。

3.3 高级定制：自定义转换器（JsonConverter）实战

假设我们有一个API，返回的日期是Unix时间戳（毫秒），但我们的C#模型使用DateTime。我们可以编写一个转换器。

public class UnixTimestampMillisecondsConverter : JsonConverter<DateTime> { private static readonly DateTime _epoch = new DateTime(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc); public override void WriteJson(JsonWriter writer, DateTime value, JsonSerializer serializer) { // 将DateTime转换为Unix时间戳（毫秒） long unixTime = (long)(value.ToUniversalTime() - _epoch).TotalMilliseconds; writer.WriteValue(unixTime); } public override DateTime ReadJson(JsonReader reader, Type objectType, DateTime existingValue, bool hasExistingValue, JsonSerializer serializer) { // 从JSON读取的可能是long（时间戳）或string（可能是其他格式），这里处理long if (reader.TokenType == JsonToken.Integer) { long milliseconds = (long)reader.Value; return _epoch.AddMilliseconds(milliseconds); } // 如果不是数字，可以尝试用默认的日期解析，或者抛出异常 throw new JsonSerializationException($"Expected integer (Unix timestamp) for date, got {reader.TokenType}."); } // CanConvert 方法在泛型 JsonConverter<T> 中已实现，通常不需要重写 // 但如果转换器要处理非泛型情况，可能需要。 }

使用这个转换器有两种方式：

1. 在属性上标记：[JsonConverter(typeof(UnixTimestampMillisecondsConverter))]
2. 添加到全局设置：settings.Converters.Add(new UnixTimestampMillisecondsConverter());

实操心得：编写自定义转换器时，务必考虑ReadJson中reader.TokenType的多样性。API可能因为版本迭代，有时返回数字，有时返回字符串。一个健壮的转换器应该能处理多种输入格式，或者至少给出清晰的错误信息。

4. 性能优化与最佳实践

在大量或高频的JSON序列化场景下，性能至关重要。以下是一些经过验证的优化技巧。

4.1 重用JsonSerializerSettings和JsonSerializer

创建JsonSerializerSettings和JsonSerializer实例是有开销的。最佳实践是创建静态的、只读的配置实例，在整个应用程序中复用。

public static class JsonSettings { public static readonly JsonSerializerSettings Default = new JsonSerializerSettings { Formatting = Formatting.None, NullValueHandling = NullValueHandling.Ignore, // ... 其他配置 // 注意：如果配置中包含自定义的ContractResolver或Converters，确保它们是线程安全的。 }; } // 使用时 string json = JsonConvert.SerializeObject(obj, JsonSettings.Default);

对于JsonSerializer，如果你使用JsonSerializer.Create(settings)创建了一个实例，并且用于多次序列化（例如在循环中），性能会比每次都使用JsonConvert更好。

4.2 使用流式API处理大JSON

对于非常大的JSON文件或网络流，一次性将整个文档加载到内存（JToken.Parse或DeserializeObject）可能导致内存压力。Json.NET提供了基于JsonTextReader和JsonTextWriter的流式API。

// 流式读取大型JSON数组 using (var streamReader = new StreamReader("large-file.json")) using (var jsonReader = new JsonTextReader(streamReader)) { var serializer = new JsonSerializer(); // 假设JSON是一个对象数组 jsonReader.Read(); // 读取开始数组令牌 '[' while (jsonReader.Read() && jsonReader.TokenType != JsonToken.EndArray) { if (jsonReader.TokenType == JsonToken.StartObject) { // 反序列化当前对象 var item = serializer.Deserialize<MyItem>(jsonReader); ProcessItem(item); // 处理单个对象，然后它可以被GC回收 } } }

流式写入同理，使用JsonTextWriter逐个写入对象，而不是在内存中构建完整的JSON字符串。

4.3 选择合适的契约解析器（ContractResolver）

DefaultContractResolver在首次为某个类型创建契约时会进行反射，这个过程相对较慢。Json.NET提供了CamelCasePropertyNamesContractResolver（自动将属性名转为小驼峰命名）等内置解析器。

一个重要的优化是使用CachedContractResolver模式，或者直接使用静态实例。确保你的自定义IContractResolver是线程安全的，并且其ResolveContract方法的结果被有效缓存。

// 创建一个全局的、缓存的契约解析器实例 private static readonly IContractResolver _myContractResolver = new MyCustomContractResolver(); public class MyCustomContractResolver : DefaultContractResolver { // 重写方法以实现自定义逻辑... // DefaultContractResolver内部有缓存机制，所以通常不需要自己再实现缓存。 }

4.4 模型设计的优化

• 使用属性（Property）而非字段（Field）：Json.NET默认序列化公共属性。字段需要额外配置（IncludeFields设置或[JsonProperty]特性）。
• 为常用模型添加[JsonObject]和[JsonProperty]特性：虽然特性不是必须的，但显式声明可以减少运行时反射的决策，对性能有轻微正面影响，更重要的是提高了代码的清晰度和可控性。你可以用[JsonProperty(PropertyName = "jsonName")]来指定序列化后的名称。
• 避免过度嵌套和复杂对象图：非常深或关系复杂的对象图在序列化时会消耗更多CPU和内存，也更容易遇到循环引用问题。考虑使用DTO（数据传输对象）来扁平化数据结构。

5. 常见问题排查与调试技巧

即使对Json.NET很熟悉，也难免会遇到一些棘手的问题。下面是一些常见坑点及其解决方法。

5.1 日期时间格式问题

这是最常见的问题之一。JSON标准中没有明确的日期格式，因此不同系统可能使用不同的格式。

• 问题：反序列化时抛出JsonSerializationException: Could not convert string to DateTime.
• 排查：
  1. 首先检查原始的JSON字符串，确认日期字段的格式。是ISO 8601（如"2023-10-27T12:00:00Z"）？还是Unix时间戳？或者是"MM/dd/yyyy"？
  2. 查看你的JsonSerializerSettings中的DateFormatString设置，或者模型属性上是否有[JsonConverter]或[JsonProperty]特性指定了格式。
• 解决：
  • 如果格式是ISO 8601，Json.NET默认可以处理。确保你的DateTime属性类型正确（使用DateTime或DateTimeOffset）。
  • 如果是自定义字符串格式，在JsonSerializerSettings中设置正确的DateFormatString。
  • 如果是数字时间戳，使用自定义的JsonConverter（如前文示例）。
  • 设置DateTimeZoneHandling来处理时区。DateTimeZoneHandling.Utc是个安全的选择，可以避免本地时区带来的混乱。

5.2 循环引用与堆栈溢出

• 问题：序列化包含循环引用的对象时，可能进入无限循环导致JsonSerializationException（提示循环引用）或直接堆栈溢出。
• 解决：
  1. 设置ReferenceLoopHandling：ReferenceLoopHandling.Ignore会忽略导致循环的属性，简单有效，但会丢失部分数据。ReferenceLoopHandling.Serialize会使用$ref，但需确认数据消费者是否支持。
  2. 重新设计模型：这是最根本的方法。考虑使用视图模型（ViewModel）或DTO，在序列化前将对象图扁平化，切断不必要的循环引用。
  3. 使用[JsonIgnore]特性：在导致循环的导航属性上标记此特性，使其不被序列化。

5.3 反序列化到抽象类或接口（多态类型）

• 问题：JSON中包含一个type字段来决定具体类型，但反序列化目标是一个接口或抽象类。
• 解决：使用TypeNameHandling设置或自定义JsonConverter。
  • TypeNameHandling.Auto或TypeNameHandling.All：Json.NET会在JSON中嵌入.NET类型信息（如"$type": "MyNamespace.MyClass, MyAssembly"）。注意：这是一个安全风险，如果JSON来自不可信源，反序列化时可能会加载并实例化任意类型。仅在完全可信的环境中使用。
  • 推荐使用自定义JsonConverter：在转换器的ReadJson方法中，根据JSON中的某个判别字段（如"discriminator": "typeA"），手动创建具体的子类实例，然后让序列器填充其余属性。

5.4 性能瓶颈诊断

如果发现JSON处理变慢，可以：

1. 使用性能分析工具：如Visual Studio的性能探查器或JetBrains dotTrace，找到热点是在序列化还是反序列化，以及具体的类型。
2. 检查是否在频繁创建JsonSerializerSettings：改为复用全局实例。
3. 检查是否使用了慢速的自定义ContractResolver或JsonConverter：优化其逻辑，确保没有不必要的反射或复杂计算。
4. 考虑大JSON是否适合内存处理：切换到流式API。

5.5 调试小技巧：序列化跟踪

有时你需要知道为什么一个属性没有被序列化，或者值为什么被转换成了某种形式。你可以创建一个简单的跟踪器：

public class TraceWriter : ITraceWriter { public TraceLevel LevelFilter => TraceLevel.Verbose; // 捕获所有级别 public void Trace(TraceLevel level, string message, Exception ex) { // 将message输出到调试窗口、日志文件等 Debug.WriteLine($"[Json.NET {level}]: {message}"); } } // 在设置中启用 var settings = new JsonSerializerSettings { TraceWriter = new TraceWriter(), // ... 其他设置 };

启用跟踪后，Json.NET会在序列化/反序列化过程中输出详细的日志，帮助你理解其内部决策过程，对于排查复杂问题非常有用。

6. 与System.Text.Json的对比与迁移考量

随着.NET的演进，微软官方的System.Text.Json在性能和内存分配上通常优于Json.NET，并且从.NET Core 3.1开始就内置了。是否要从Json.NET迁移，需要权衡。

Json.NET的优势：

• 功能极其丰富和成熟：高级定制化能力（如强大的ContractResolver、JsonConverter体系）远超System.Text.Json。
• 广泛的社区支持和遗留代码库：无数NuGet包和项目依赖它，生态稳固。
• 对“非标准”JSON和复杂场景处理更好：如动态类型（JToken）、JSON Path查询、更灵活的日期/数字格式处理。

System.Text.Json的优势：

• 性能更高：特别是在大量小对象序列化场景下，速度更快，分配的内存更少。
• 与.NET运行时集成更紧密：无需额外NuGet依赖。
• 默认更安全：例如，默认不解析注释，TypeNameHandling默认关闭，减少了反序列化攻击面。

迁移决策建议：

• 新项目：如果项目从.NET Core 3.1/ .NET 5+开始，且JSON处理需求不复杂（主要是简单的DTO序列化），优先考虑System.Text.Json。它的性能优势是实实在在的。
• 现有项目（重度使用Json.NET高级特性）：如果项目大量使用了自定义转换器、复杂的契约解析、JToken动态操作、或依赖某些Json.NET特有的特性（如JsonProperty的DefaultValueHandling），谨慎迁移。迁移成本可能很高，且System.Text.Json的API和默认行为有不少差异，需要仔细测试。
• 混合使用：在一些大型项目中，可以并存。对新模块使用System.Text.Json，老模块继续使用Json.NET。但要注意避免在两个库之间频繁转换同一对象，这会产生额外开销。

如果决定迁移，务必仔细阅读微软的官方迁移指南，重点关注API差异、默认行为差异（如日期格式、大小写策略、循环引用处理）以及特性（Attribute）的替换（如[JsonPropertyName]替代[JsonProperty]）。