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 8Json.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的处理。对于强类型你使用泛型方法DeserializeObjectT。对于完全未知或结构多变的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。你需要自定义转换器的典型场景包括处理特殊的日期/时间格式API返回的可能是Unix时间戳或某种自定义字符串格式。序列化枚举为字符串而非数字提高JSON的可读性。处理多态类型JSON中的一个字段根据其值可能对应多个不同的子类。自定义集合或字典的序列化方式。处理循环引用虽然可以通过ReferenceLoopHandling设置但有时需要更精细的控制。编写一个自定义JsonConverter需要实现三个主要方法CanConvert判断该转换器是否能处理指定类型、WriteJson将C#对象写入JSON、ReadJson从JSON读取并构造C#对象。通过转换器你可以完全掌控序列化和反序列化的过程。3. 基础到进阶核心API详解与实战让我们从最常用的API开始逐步深入到高级配置和定制化操作。3.1 序列化与反序列化不止是简单的调用JsonConvert.SerializeObject和DeserializeObjectT是入口点但它们的威力来自于可传入的JsonSerializerSettings参数。基础但关键的设置Formatting.Indented生成格式化的、带缩进的JSON字符串便于调试和阅读。生产环境通常使用Formatting.None以节省空间。NullValueHandling控制如何处理null值。NullValueHandling.Ignore会在序列化时跳过值为null的属性让生成的JSON更简洁。DefaultValueHandling控制如何处理默认值如int的0bool的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.Valuestring(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.Valuestring()).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 JSONJToken实现了IEnumerableJToken因此可以无缝使用LINQ进行查询和转换与查询内存中的集合一样直观。3.3 高级定制自定义转换器JsonConverter实战假设我们有一个API返回的日期是Unix时间戳毫秒但我们的C#模型使用DateTime。我们可以编写一个转换器。public class UnixTimestampMillisecondsConverter : JsonConverterDateTime { 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 方法在泛型 JsonConverterT 中已实现通常不需要重写 // 但如果转换器要处理非泛型情况可能需要。 }使用这个转换器有两种方式在属性上标记[JsonConverter(typeof(UnixTimestampMillisecondsConverter))]添加到全局设置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.DeserializeMyItem(jsonReader); ProcessItem(item); // 处理单个对象然后它可以被GC回收 } } }流式写入同理使用JsonTextWriter逐个写入对象而不是在内存中构建完整的JSON字符串。4.3 选择合适的契约解析器ContractResolverDefaultContractResolver在首次为某个类型创建契约时会进行反射这个过程相对较慢。Json.NET提供了CamelCasePropertyNamesContractResolver自动将属性名转为小驼峰命名等内置解析器。一个重要的优化是使用CachedContractResolver模式或者直接使用静态实例。确保你的自定义IContractResolver是线程安全的并且其ResolveContract方法的结果被有效缓存。// 创建一个全局的、缓存的契约解析器实例 private static readonly IContractResolver _myContractResolver new MyCustomContractResolver(); public class MyCustomContractResolver : DefaultContractResolver { // 重写方法以实现自定义逻辑... // DefaultContractResolver内部有缓存机制所以通常不需要自己再实现缓存。 }4.4 模型设计的优化使用属性Property而非字段FieldJson.NET默认序列化公共属性。字段需要额外配置IncludeFields设置或[JsonProperty]特性。为常用模型添加[JsonObject]和[JsonProperty]特性虽然特性不是必须的但显式声明可以减少运行时反射的决策对性能有轻微正面影响更重要的是提高了代码的清晰度和可控性。你可以用[JsonProperty(PropertyName jsonName)]来指定序列化后的名称。避免过度嵌套和复杂对象图非常深或关系复杂的对象图在序列化时会消耗更多CPU和内存也更容易遇到循环引用问题。考虑使用DTO数据传输对象来扁平化数据结构。5. 常见问题排查与调试技巧即使对Json.NET很熟悉也难免会遇到一些棘手的问题。下面是一些常见坑点及其解决方法。5.1 日期时间格式问题这是最常见的问题之一。JSON标准中没有明确的日期格式因此不同系统可能使用不同的格式。问题反序列化时抛出JsonSerializationException: Could not convert string to DateTime.排查首先检查原始的JSON字符串确认日期字段的格式。是ISO 8601如2023-10-27T12:00:00Z还是Unix时间戳或者是MM/dd/yyyy查看你的JsonSerializerSettings中的DateFormatString设置或者模型属性上是否有[JsonConverter]或[JsonProperty]特性指定了格式。解决如果格式是ISO 8601Json.NET默认可以处理。确保你的DateTime属性类型正确使用DateTime或DateTimeOffset。如果是自定义字符串格式在JsonSerializerSettings中设置正确的DateFormatString。如果是数字时间戳使用自定义的JsonConverter如前文示例。设置DateTimeZoneHandling来处理时区。DateTimeZoneHandling.Utc是个安全的选择可以避免本地时区带来的混乱。5.2 循环引用与堆栈溢出问题序列化包含循环引用的对象时可能进入无限循环导致JsonSerializationException提示循环引用或直接堆栈溢出。解决设置ReferenceLoopHandlingReferenceLoopHandling.Ignore会忽略导致循环的属性简单有效但会丢失部分数据。ReferenceLoopHandling.Serialize会使用$ref但需确认数据消费者是否支持。重新设计模型这是最根本的方法。考虑使用视图模型ViewModel或DTO在序列化前将对象图扁平化切断不必要的循环引用。使用[JsonIgnore]特性在导致循环的导航属性上标记此特性使其不被序列化。5.3 反序列化到抽象类或接口多态类型问题JSON中包含一个type字段来决定具体类型但反序列化目标是一个接口或抽象类。解决使用TypeNameHandling设置或自定义JsonConverter。TypeNameHandling.Auto或TypeNameHandling.AllJson.NET会在JSON中嵌入.NET类型信息如$type: MyNamespace.MyClass, MyAssembly。注意这是一个安全风险如果JSON来自不可信源反序列化时可能会加载并实例化任意类型。仅在完全可信的环境中使用。推荐使用自定义JsonConverter在转换器的ReadJson方法中根据JSON中的某个判别字段如discriminator: typeA手动创建具体的子类实例然后让序列器填充其余属性。5.4 性能瓶颈诊断如果发现JSON处理变慢可以使用性能分析工具如Visual Studio的性能探查器或JetBrains dotTrace找到热点是在序列化还是反序列化以及具体的类型。检查是否在频繁创建JsonSerializerSettings改为复用全局实例。检查是否使用了慢速的自定义ContractResolver或JsonConverter优化其逻辑确保没有不必要的反射或复杂计算。考虑大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]。
