1. 项目概述为什么C#开发者绕不开JSON处理如果你用C#做过任何形式的网络通信、配置文件读写或者前后端数据交换那你肯定和JSON打过交道。这玩意儿现在几乎是数据交换的“普通话”从Web API的响应体到应用程序的本地配置无处不在。我刚开始接触C#那会儿处理JSON还是一件挺折腾的事要么手动拼接字符串那叫一个酸爽还容易出错要么用一些第三方库配置起来也挺麻烦。后来.NET自己内置了对JSON的支持特别是随着.NET Core和现在的.NET 5/6/7/8的演进官方库System.Text.Json越来越强大让JSON处理变成了C#开发中的一项基础且愉悦的技能。简单来说这个“项目”的核心就是掌握在C#中如何把内存中的对象比如一个Person类的实例序列化成JSON格式的字符串以及如何把接收到的JSON字符串反序列化回我们程序里可以操作的对象。这听起来简单但实际开发中你会遇到各种“坑”日期格式五花八门、字段名需要映射、循环引用导致栈溢出、性能要求苛刻的大数据量处理等等。今天我就结合自己这些年踩过的坑和积累的经验把C#里JSON解析与生成的方方面面给你掰扯清楚从最基础的用法到高阶的性能优化和疑难杂症排查让你以后遇到JSON再也不用发怵。2. 核心工具选型Newtonsoft.Json 与 System.Text.Json 的抉择在C#的世界里谈到JSON处理你主要会面对两个选择老牌劲旅Newtonsoft.Json也叫Json.NET和官方后起之秀System.Text.Json。很多新手会纠结用哪个我的建议是理解场景按需选择。2.1 Newtonsoft.Json功能全面的老将Newtonsoft.Json是一个极其流行、功能丰富的第三方库。它的最大优点是灵活性和兼容性极高。在System.Text.Json成熟之前它几乎是C#处理JSON的唯一选择积累了海量的用户和用例。它的强项包括高度可配置几乎可以定制序列化和反序列化的每一个环节。比如你可以轻松地处理私有字段、设置默认值、实现自定义的类型转换器JsonConverter。强大的错误处理默认设置下遇到JSON中多出来的字段或类型不匹配它可能更“宽容”或者提供更详细的错误信息。丰富的生态系统网上几乎所有的C# JSON相关代码示例、问题解答和第三方库集成默认都支持Newtonsoft.Json。一个典型的反序列化例子using Newtonsoft.Json; public class Person { public string Name { get; set; } public int Age { get; set; } } string json {Name:张三, Age:30, ExtraField:IgnoreMe}; // 反序列化时JSON中多余的“ExtraField”会被忽略取决于设置 Person person JsonConvert.DeserializeObjectPerson(json); Console.WriteLine(person.Name); // 输出张三注意虽然灵活但这种“宽容”有时也会掩盖数据不一致的问题在严格的系统间通信场景下需要小心。2.2 System.Text.Json高性能的官方新星System.Text.Json是微软官方从.NET Core 3.0开始引入的它的设计目标是高性能和低内存分配。对于新项目尤其是对性能有要求的ASP.NET Core Web API项目它通常是首选。它的主要特点性能卓越在序列化/反序列化速度和内存使用上通常优于Newtonsoft.Json特别是在处理大量数据时。默认安全它更严格默认情况下区分大小写并且会忽略JSON中的注释这符合JSON标准。这有助于提前发现数据契约的不匹配。与.NET平台深度集成作为基础类库的一部分无需额外安装NuGet包在较新的.NET版本中并且与ASP.NET Core的模型绑定等功能无缝衔接。同样的例子用System.Text.Json实现using System.Text.Json; public class Person { public string Name { get; set; } public int Age { get; set; } } string json {Name:张三, Age:30, ExtraField:IgnoreMe}; // 默认情况下ExtraField会导致JsonException因为Person类没有这个属性 try { Person person JsonSerializer.DeserializePerson(json); Console.WriteLine(person.Name); } catch (JsonException ex) { Console.WriteLine($解析出错{ex.Message}); }如何选择新项目尤其是.NET 5的Web API优先使用System.Text.Json。它的性能优势明显并且是微软主推的方向。遗留项目或需要高度定制化如果项目已经大量使用Newtonsoft.Json或者你需要依赖某些它特有的高级特性如支持非公共成员访问器、更复杂的类型转换那么继续使用它是合理的。需要与大量使用Newtonsoft.Json的第三方库交互为了兼容性可能仍需使用Newtonsoft.Json。我个人在近几年新建的项目中基本都转向了System.Text.Json。它的性能提升在微服务和高并发场景下感知非常明显。下面的内容我会以System.Text.Json为主进行讲解因为这是未来的趋势但也会指出与Newtonsoft.Json的关键差异。3. 基础操作序列化与反序列化详解掌握了工具我们来看看最基本的两个操作把对象变成字符串序列化和把字符串变回对象反序列化。3.1 对象到JSON字符串序列化序列化就是把一个C#对象转换成一个符合JSON格式的字符串。这是你向API发送数据或将配置保存到文件时要做的事。基本用法using System.Text.Json; var weatherForecast new WeatherForecast { Date DateTime.Parse(2023-10-27), TemperatureC 25, Summary 温暖 }; // 最简单的序列化 string jsonString JsonSerializer.Serialize(weatherForecast); Console.WriteLine(jsonString); // 输出{Date:2023-10-27T00:00:00,TemperatureC:25,Summary:温暖}关键点解析命名风格默认情况下属性名会原样输出为JSON的键Key。C#属性通常用PascalCase首字母大写而JSON习惯使用camelCase首字母小写。为了前后端协作更顺畅我们经常需要改变这个规则。日期格式如上例所示DateTime被序列化成了一种包含时区的ISO 8601格式字符串。这种格式是标准且可读的但有时你可能需要其他格式如yyyy-MM-dd。自定义序列化选项JsonSerializerOptions对象让你可以精细控制序列化行为。// 创建配置选项 var options new JsonSerializerOptions { // 1. 设置属性名称为驼峰命名法 PropertyNamingPolicy JsonNamingPolicy.CamelCase, // 2. 美化输出缩进便于阅读调试但会增加字符串体积 WriteIndented true, // 3. 忽略值为null的属性 DefaultIgnoreCondition System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull, // 4. 自定义日期格式 Converters { new DateTimeConverterUsingDateTimeFormat(yyyy-MM-dd) } // 需要自定义转换器 }; string jsonWithOptions JsonSerializer.Serialize(weatherForecast, options); Console.WriteLine(jsonWithOptions); /* 输出 { date: 2023-10-27, temperatureC: 25, summary: 温暖 } */ // 注意自定义DateTime转换器需要实现JsonConverterT这里仅为示意。实操心得对于Web API我强烈建议全局配置PropertyNamingPolicy JsonNamingPolicy.CamelCase。这样你的C#模型类保持PascalCase的整洁而API接口输出的JSON是前端JavaScript更习惯的camelCase省去很多手动映射的麻烦。可以在Program.cs或Startup.cs中配置为服务默认选项。3.2 JSON字符串到对象反序列化反序列化是序列化的逆过程将JSON字符串填充到一个C#对象的属性中。这是你接收API响应或读取配置文件时要做的事。基本用法string json {Date:2023-10-27T00:00:00,TemperatureC:25,Summary:温暖}; // 最简单的反序列化 WeatherForecast forecast JsonSerializer.DeserializeWeatherForecast(json); Console.WriteLine($日期{forecast.Date} 温度{forecast.TemperatureC}°C 概况{forecast.Summary});处理不匹配的JSON结构现实世界的JSON往往不会和你的C#类完美对应。你可能遇到JSON字段多于C#属性默认情况下System.Text.Json会忽略这些多余的字段这是3.0之后的行为。你可以通过JsonSerializerOptions.UnmappedMemberHandling.NET 7或自定义转换器来改变这一行为比如选择抛出异常以严格校验。JSON字段少于C#属性对应的C#属性将保持其默认值如int为0string为null。字段名不一致除了使用JsonPropertyName特性见下文也可以在反序列化时使用与序列化时匹配的JsonSerializerOptions如同样设置PropertyNamingPolicy。3.3 使用特性进行精细控制通过在模型类的属性上添加特性Attribute你可以进行更精细的控制而无需修改全局选项。using System.Text.Json.Serialization; public class Product { // 指定JSON中的属性名 [JsonPropertyName(product_name)] public string Name { get; set; } // 序列化和反序列化时都忽略此属性 [JsonIgnore] public string InternalCode { get; set; } // 仅当值为null时在序列化时忽略。反序列化不受影响。 [JsonIgnore(Condition JsonIgnoreCondition.WhenWritingNull)] public string Description { get; set; } // 自定义转换器例如将字符串“YES”/“NO”转换为bool [JsonConverter(typeof(YesNoBooleanConverter))] public bool IsAvailable { get; set; } }特性Attribute与选项Options的优先级特性标注的优先级高于全局的JsonSerializerOptions。例如即使全局设置了驼峰命名被[JsonPropertyName(product_name)]标记的属性在JSON中键名依然是product_name。4. 高级场景与性能优化实战基础操作能满足80%的需求但剩下的20%才是体现功力的地方。下面我们深入几个高级场景。4.1 处理多态类型继承与接口假设你有一个动物基类Animal和两个派生类Dog和Cat。你如何序列化一个ListAnimal并在反序列化时让每个元素恢复成正确的具体类型System.Text.Json对此的支持不如Newtonsoft.Json直接。在.NET 7之前你需要编写复杂的自定义转换器。从**.NET 7开始**引入了对多态序列化的原生支持大大简化了操作。.NET 7 的解决方案[JsonDerivedType(typeof(Dog), typeDiscriminator: dog)] [JsonDerivedType(typeof(Cat), typeDiscriminator: cat)] public class Animal { public string Name { get; set; } } public class Dog : Animal { public string Breed { get; set; } } public class Cat : Animal { public bool IsIndoor { get; set; } } // 序列化 ListAnimal animals new ListAnimal { new Dog { Name Buddy, Breed Golden Retriever }, new Cat { Name Whiskers, IsIndoor true } }; var options new JsonSerializerOptions { WriteIndented true, // 关键启用对派生类型的支持 TypeInfoResolver new DefaultJsonTypeInfoResolver { Modifiers { AnimalTypeInfoModifier.Modify } // 需要自定义Modifier来添加鉴别器或直接使用特性如上 } }; // 更简单的办法使用上面定义的[JsonDerivedType]特性 string json JsonSerializer.Serialize(animals, options); Console.WriteLine(json); /* 输出会包含类型鉴别器 [ { $type: dog, Name: Buddy, Breed: Golden Retriever }, { $type: cat, Name: Whiskers, IsIndoor: true } ] */ // 反序列化时能正确还原为Dog和Cat对象 ListAnimal deserializedAnimals JsonSerializer.DeserializeListAnimal(json, options); foreach (var animal in deserializedAnimals) { Console.WriteLine(${animal.Name} is a {animal.GetType().Name}); } // 输出Buddy is a Dog // Whiskers is a Cat对于**.NET 7以下版本**你需要手动实现一个JsonConverterAnimal在Write方法中根据对象实际类型输出一个类型鉴别字段在Read方法中根据这个字段创建对应的派生类实例。这个过程比较繁琐是升级到.NET 7的一个有力理由。4.2 流式处理超大JSON当你需要处理几百MB甚至GB级别的JSON文件比如从数据仓库导出的日志一次性将整个文件读入内存JsonSerializer.DeserializeT(string)会导致内存溢出OOM。这时必须使用流式处理Streaming。System.Text.Json提供了Utf8JsonReader和Utf8JsonWriter这两个高性能、低分配的类型来处理流式JSON。使用Utf8JsonReader读取解析超大JSONusing System.Text.Json; public async Task ProcessLargeJsonFileAsync(string filePath) { await using FileStream fileStream File.OpenRead(filePath); var buffer new byte[4096]; // 缓冲区 // 填充初始缓冲区 int bytesRead await fileStream.ReadAsync(buffer); var reader new Utf8JsonReader(buffer.AsSpan(0, bytesRead), isFinalBlock: false, state: default); while (true) { // 如果缓冲区数据已读完从流中读取更多 if (!reader.Read()) { if (bytesRead 0) // 流已结束 { break; } // 将剩余的有效数据移动到缓冲区开头 ReadOnlySequencebyte remaining reader.ValueSequence; // ... (这里需要处理缓冲区续读逻辑通常封装成Helper) // 简化示例我们假设文件不大一次性可读入 // 实际生产环境需处理分块读取和reader的Reset/Continue break; } // 根据Token类型处理 switch (reader.TokenType) { case JsonTokenType.StartObject: Console.WriteLine(开始对象); break; case JsonTokenType.PropertyName: string propertyName reader.GetString(); Console.WriteLine($属性名: {propertyName}); break; case JsonTokenType.String: string stringValue reader.GetString(); Console.WriteLine($字符串值: {stringValue}); break; case JsonTokenType.Number: if (reader.TryGetInt32(out int intValue)) { Console.WriteLine($整数值: {intValue}); } // 也可以处理double, long等 break; // ... 处理其他Token类型 } } }使用Utf8JsonWriter写入生成超大JSONusing System.Text.Json; public async Task GenerateLargeJsonFileAsync(string outputPath) { await using var fileStream File.Create(outputPath); using var writer new Utf8JsonWriter(fileStream, new JsonWriterOptions { Indented true }); writer.WriteStartArray(); // 写入数组开始符号 [ for (int i 0; i 1000000; i) // 模拟生成一百万条记录 { writer.WriteStartObject(); writer.WriteNumber(id, i); writer.WriteString(name, $Item_{i}); writer.WriteBoolean(active, i % 2 0); writer.WriteEndObject(); // 定期刷新缓冲区到文件流避免内存占用过高 if (i % 10000 0) { await writer.FlushAsync(); } } writer.WriteEndArray(); // 写入数组结束符号 ] await writer.FlushAsync(); // 最后刷新 }注意事项流式API是底层API使用起来比简单的Serialize/Deserialize复杂但它是处理海量数据的唯一选择。务必注意Utf8JsonReader是ref struct不能存储在堆上如类的字段且其生命周期管理需要小心。4.3 性能优化关键点缓存 JsonSerializerOptionsJsonSerializerOptions的创建和初始化成本较高。绝对不要在每次序列化/反序列化时都new一个。应该创建一个静态的、只读的实例在全局复用。// 错误做法每次调用都创建新的Options public string ToJsonBad(MyObject obj) { var options new JsonSerializerOptions { WriteIndented true }; return JsonSerializer.Serialize(obj, options); } // 正确做法缓存Options实例 private static readonly JsonSerializerOptions _options new JsonSerializerOptions { PropertyNamingPolicy JsonNamingPolicy.CamelCase, WriteIndented false // 生产环境通常关闭缩进以节省空间 }; public string ToJsonGood(MyObject obj) { return JsonSerializer.Serialize(obj, _options); }使用源生成器Source Generator这是.NET 6及以上版本提供的终极性能优化方案。它通过在编译时生成优化的序列化代码完全避免了运行时的反射开销极大地提升了性能并减少了内存分配。在项目中安装System.Text.Json源生成器包。创建一个局部类partial class并为其添加[JsonSerializable]特性。编译器会自动为该类型生成序列化代码。// 在你的模型类所在文件或新文件中 [JsonSerializable(typeof(WeatherForecast))] [JsonSerializable(typeof(ListWeatherForecast))] public partial class MyJsonContext : JsonSerializerContext { } // 使用源生成器进行序列化性能最佳 string json JsonSerializer.Serialize(forecast, MyJsonContext.Default.WeatherForecast); WeatherForecast obj JsonSerializer.Deserialize(json, MyJsonContext.Default.WeatherForecast);对于高性能场景如高频API、游戏服务器务必考虑使用源生成器。选择正确的数据类型对于已知的数字类型尽量使用int,long,double等具体类型而不是object或dynamic。System.Text.Json对具体类型的处理路径是高度优化的。5. 常见问题排查与调试技巧即使掌握了原理实际开发中还是会遇到各种奇怪的问题。下面是我总结的一些常见“坑”和解决方法。5.1 日期时间格式混乱这是最常见的问题之一。JSON标准本身没有定义日期格式导致各种系统使用的格式千奇百怪。问题场景前端传给你一个2023-10-27的字符串你直接反序列化到DateTime属性可能会失败或者得到错误的时间如时区问题。解决方案定义契约前后端或系统间首先约定使用一种标准的日期格式强烈推荐ISO 8601例如2023-10-27T14:30:00Z或2023-10-27T14:30:0008:00。这是System.Text.Json默认读写的格式。自定义转换器如果必须处理非标准格式编写自定义的JsonConverterDateTime。public class CustomDateTimeConverter : JsonConverterDateTime { private readonly string _format; public CustomDateTimeConverter(string format) _format format; public override DateTime Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) { // 从JSON字符串中读取并解析 string dateString reader.GetString(); return DateTime.ParseExact(dateString, _format, CultureInfo.InvariantCulture); } public override void Write(Utf8JsonWriter writer, DateTime value, JsonSerializerOptions options) { // 将DateTime按指定格式写入JSON字符串 writer.WriteStringValue(value.ToString(_format, CultureInfo.InvariantCulture)); } } // 使用 var options new JsonSerializerOptions(); options.Converters.Add(new CustomDateTimeConverter(yyyy-MM-dd)); string json {Date:2023-10-27}; var obj JsonSerializer.DeserializeMyClass(json, options);5.2 循环引用与堆栈溢出当两个对象互相引用时例如Order包含CustomerCustomer又有一个Orders列表序列化时会陷入无限循环导致JsonExceptionSystem.Text.Json或堆栈溢出Newtonsoft.Json在某些配置下。解决方案System.Text.Json默认会抛出JsonException。你可以通过配置JsonSerializerOptions.ReferenceHandler ReferenceHandler.IgnoreCycles来忽略循环。这会在遇到已序列化的对象引用时输出null。var options new JsonSerializerOptions { ReferenceHandler ReferenceHandler.IgnoreCycles, WriteIndented true }; string json JsonSerializer.Serialize(order, options); // Customer属性在Orders列表中被引用第二次出现时会被写为null重新设计模型更根本的解决方法是使用DTO数据传输对象。不要直接序列化完整的领域模型。为API接口创建专用的视图模型只包含前端需要的数据切断不必要的引用关系。例如OrderDto里只包含CustomerId而不是整个Customer对象。5.3 大小写敏感问题System.Text.Json默认是区分大小写的。这意味着JSON中的name和类属性Name无法自动匹配。解决方案设置全局命名策略PropertyNamingPolicy JsonNamingPolicy.CamelCase。这是最推荐的做法。使用[JsonPropertyName]特性为每个属性单独指定JSON中的名称。修改比较器设置JsonSerializerOptions.PropertyNameCaseInsensitive true。这会让反序列化时忽略属性名的大小写但可能会带来微小的性能开销。5.4 调试与日志记录当序列化/反序列化出错时异常信息有时不够直观。这里有几个调试技巧捕获并检查JsonException这个异常通常包含错误发生的路径Path和行号信息BytePositionInLine能帮你快速定位到JSON字符串中出错的位置。try { var obj JsonSerializer.DeserializeComplexModel(jsonString); } catch (JsonException ex) { Console.WriteLine($错误路径{ex.Path}); Console.WriteLine($行内位置{ex.BytePositionInLine}); Console.WriteLine($异常信息{ex.Message}); // 可以在这里记录日志甚至输出有问题的json片段 }使用在线JSON验证工具将出错的JSON字符串粘贴到如 JSONLint 这类在线工具中检查格式是否正确。对比生成与预期的JSON如果你不确定序列化出来的JSON是否正确可以先用一个已知正确的简单对象序列化看看结构再逐步复杂化。在ASP.NET Core中启用详细错误信息在开发环境你可以配置AddJsonOptions来在模型绑定失败时返回更详细的错误。builder.Services.AddControllers() .AddJsonOptions(options { // 此设置会使无效的JSON输入引发更详细的异常仅用于开发 options.JsonSerializerOptions.AllowTrailingCommas false; // 严格模式 // 其他配置... });6. 实战构建一个健壮的JSON工具类最后我把上面散落的知识点整合一下分享一个我项目中常用的JSON工具类。它封装了全局配置、异常处理和简单的性能优化开箱即用。using System.Text.Json; using System.Text.Json.Serialization; namespace YourProject.Utils { /// summary /// JSON序列化/反序列化工具类基于System.Text.Json /// /summary public static class JsonHelper { // 缓存的、线程安全的全局序列化选项 private static readonly JsonSerializerOptions _defaultOptions new JsonSerializerOptions { // 属性名使用驼峰命名法 PropertyNamingPolicy JsonNamingPolicy.CamelCase, // 忽略值为null的属性减少传输数据量 DefaultIgnoreCondition JsonIgnoreCondition.WhenWritingNull, // 处理循环引用忽略第二次及以后的引用 ReferenceHandler ReferenceHandler.IgnoreCycles, // 不美化输出生产环境为性能考虑 WriteIndented false, // 允许数字以字符串形式读取更宽松兼容某些前端库 NumberHandling JsonNumberHandling.AllowReadingFromString, // 自定义转换器可以在这里添加 // Converters { new CustomDateTimeConverter(yyyy-MM-dd) } }; // 用于需要美化输出的场景如日志、调试 private static readonly JsonSerializerOptions _indentedOptions new JsonSerializerOptions(_defaultOptions) { WriteIndented true }; /// summary /// 将对象序列化为JSON字符串 /// /summary public static string SerializeT(T value, bool indented false) { var options indented ? _indentedOptions : _defaultOptions; return JsonSerializer.Serialize(value, options); } /// summary /// 将JSON字符串反序列化为对象 /// /summary public static T DeserializeT(string json) { if (string.IsNullOrWhiteSpace(json)) { return default; // 或抛出ArgumentNullException } try { return JsonSerializer.DeserializeT(json, _defaultOptions); } catch (JsonException ex) { // 这里可以集成你的日志框架如NLog, Serilog等 // _logger.LogError(ex, JSON反序列化失败。原始JSON: {JsonTruncated}, json.Length 500 ? json.Substring(0, 500) ... : json); throw new InvalidOperationException($反序列化类型 {typeof(T).Name} 时发生错误。请检查JSON格式是否正确。, ex); } } /// summary /// 安全地尝试反序列化失败返回false /// /summary public static bool TryDeserializeT(string json, out T result) { result default; if (string.IsNullOrWhiteSpace(json)) { return false; } try { result JsonSerializer.DeserializeT(json, _defaultOptions); return true; } catch { return false; } } /// summary /// 异步从Stream反序列化用于处理大文件或网络流 /// /summary public static async ValueTaskT DeserializeFromStreamAsyncT(Stream stream, CancellationToken cancellationToken default) { try { return await JsonSerializer.DeserializeAsyncT(stream, _defaultOptions, cancellationToken); } catch (JsonException ex) { throw new InvalidOperationException($从流反序列化类型 {typeof(T).Name} 时发生错误。, ex); } } } // 示例自定义日期转换器按需启用 // public class CustomDateTimeConverter : JsonConverterDateTime // { // // ... 实现如前文所述 // } }使用示例var product new Product { Id 1, Name Test, Price 99.99m }; // 序列化 string json JsonHelper.Serialize(product); // 紧凑格式 string prettyJson JsonHelper.Serialize(product, indented: true); // 美化格式用于调试 // 反序列化 try { Product deserializedProduct JsonHelper.DeserializeProduct(json); } catch (InvalidOperationException ex) { Console.WriteLine($操作失败{ex.Message}); } // 安全尝试 if (JsonHelper.TryDeserializeProduct(someJsonString, out var safeProduct)) { // 使用 safeProduct }这个工具类提供了基础的安全性和便利性。你可以根据项目需求在其中集成更复杂的逻辑比如基于环境的配置切换、更详细的审计日志等。记住对于性能至关重要的模块考虑使用源生成器创建特定的JsonSerializerContext来替代这个通用的工具类。
