Newtonsoft.Json 高级玩法：用 JsonSerializerSettings 定制你的 JSON 序列化规则

Newtonsoft.Json 高级玩法用 JsonSerializerSettings 定制你的 JSON 序列化规则在数据交换和存储的场景中JSON 格式因其轻量和易读性而广受欢迎。对于 C# 开发者来说Newtonsoft.Json现称 Json.NET无疑是处理 JSON 数据的首选库。虽然基础的序列化和反序列化操作很简单但当你需要处理复杂场景时JsonSerializerSettings 类提供的丰富配置选项就能大显身手。想象一下这些场景你需要将 API 返回的 JSON 属性名统一转换为小驼峰命名或者要处理包含循环引用的对象图又或者需要将特定类型的值序列化为自定义格式。这些需求都可以通过 JsonSerializerSettings 轻松实现。本文将带你深入探索这些高级配置选项让你的 JSON 处理能力更上一层楼。1. 核心配置选项解析JsonSerializerSettings 提供了数十个配置属性我们先来看几个最常用且强大的选项。1.1 格式化与空值处理最基本的配置莫过于控制 JSON 输出的格式和空值处理方式var settings new JsonSerializerSettings { Formatting Formatting.Indented, // 美化输出带缩进和换行 NullValueHandling NullValueHandling.Ignore, // 忽略null值 DefaultValueHandling DefaultValueHandling.Ignore // 忽略默认值 };这三个配置特别适合 API 响应场景可以显著减少不必要的数据传输量。例如一个用户对象中未设置的属性和默认值如 int 的 0、bool 的 false将不会被包含在输出 JSON 中。1.2 日期处理策略日期时间格式是跨平台交互中最容易出问题的地方之一。JsonSerializerSettings 提供了多种日期处理方式配置选项说明示例输出DateFormatHandling.IsoDateFormatISO 8601 标准格式2023-08-20T14:30:00ZDateFormatHandling.MicrosoftDateFormat微软传统格式/Date(1692534600000)/自定义 DateFormatString指定特定格式2023-08-20var dateSettings new JsonSerializerSettings { DateFormatHandling DateFormatHandling.IsoDateFormat, // 或者指定自定义格式 DateFormatString yyyy-MM-dd HH:mm:ss };1.3 循环引用处理对象间的循环引用是序列化时的常见难题。考虑以下场景public class Employee { public string Name { get; set; } public Employee Manager { get; set; } } var employee new Employee { Name Alice }; employee.Manager new Employee { Name Bob, Manager employee }; // 循环引用JsonSerializerSettings 提供了三种处理策略Error默认行为遇到循环引用时抛出异常Ignore忽略循环引用相关属性输出为 nullSerialize保留循环引用需要配合 PreserveReferencesHandlingvar loopSettings new JsonSerializerSettings { ReferenceLoopHandling ReferenceLoopHandling.Ignore };2. 高级定制技巧2.1 属性命名策略在不同系统间交换数据时属性命名约定可能不同。Newtonsoft.Json 提供了灵活的命名策略控制var namingSettings new JsonSerializerSettings { ContractResolver new CamelCasePropertyNamesContractResolver() // 转为小驼峰 };你还可以创建自定义的命名解析器。例如将所有属性名转换为大写public class UpperCasePropertyNamesContractResolver : DefaultContractResolver { protected override string ResolvePropertyName(string propertyName) { return propertyName.ToUpper(); } }2.2 类型信息处理在反序列化多态对象时保留类型信息至关重要var typeSettings new JsonSerializerSettings { TypeNameHandling TypeNameHandling.Auto, TypeNameAssemblyFormatHandling TypeNameAssemblyFormatHandling.Simple }; var shapes new ListShape { new Circle(), new Square() }; var json JsonConvert.SerializeObject(shapes, typeSettings); // 输出包含$type字段指明具体类型注意TypeNameHandling 可能带来安全风险特别是在反序列化不受信任的数据时。确保只在可信环境中使用此功能。2.3 自定义转换器当内置的序列化逻辑不满足需求时可以创建自定义转换器。例如将枚举值序列化为描述字符串public class StatusEnumConverter : JsonConverter { public override bool CanConvert(Type objectType) objectType typeof(Status); public override void WriteJson(JsonWriter writer, object value, JsonSerializer serializer) { var status (Status)value; writer.WriteValue(status.GetDescription()); // 获取枚举的描述属性 } public override object ReadJson(JsonReader reader, Type objectType, object existingValue, JsonSerializer serializer) { var description (string)reader.Value; return EnumHelper.GetValueFromDescriptionStatus(description); } }使用时只需添加到 Converters 集合var converterSettings new JsonSerializerSettings { Converters new ListJsonConverter { new StatusEnumConverter() } };3. 实战应用场景3.1 API 响应标准化构建 Web API 时通常需要统一的 JSON 响应格式。以下是一个推荐的配置var apiSettings new JsonSerializerSettings { Formatting Formatting.None, // 生产环境通常不需要美化 NullValueHandling NullValueHandling.Ignore, ContractResolver new CamelCasePropertyNamesContractResolver(), DateFormatHandling DateFormatHandling.IsoDateFormat, ReferenceLoopHandling ReferenceLoopHandling.Ignore, Converters new ListJsonConverter { new StringEnumConverter() } // 枚举转字符串 }; // 在ASP.NET Core中全局配置 services.AddControllers() .AddNewtonsoftJson(options { options.SerializerSettings.ContractResolver new CamelCasePropertyNamesContractResolver(); options.SerializerSettings.NullValueHandling NullValueHandling.Ignore; });3.2 特殊数据处理处理特殊数据结构时如 Dictionary 的键不是字符串时public class DictionaryWithNonStringKeyConverter : JsonConverter { public override bool CanConvert(Type objectType) { return objectType.IsGenericType objectType.GetGenericTypeDefinition() typeof(Dictionary,) objectType.GetGenericArguments()[0] ! typeof(string); } public override void WriteJson(JsonWriter writer, object value, JsonSerializer serializer) { var dictionary (IDictionary)value; writer.WriteStartArray(); foreach (DictionaryEntry entry in dictionary) { writer.WriteStartObject(); writer.WritePropertyName(Key); serializer.Serialize(writer, entry.Key); writer.WritePropertyName(Value); serializer.Serialize(writer, entry.Value); writer.WriteEndObject(); } writer.WriteEndArray(); } public override object ReadJson(JsonReader reader, Type objectType, object existingValue, JsonSerializer serializer) { throw new NotImplementedException(); } }3.3 性能优化配置对于高性能场景可以调整以下设置var perfSettings new JsonSerializerSettings { Formatting Formatting.None, MaxDepth 32, // 限制序列化深度 ReferenceLoopHandling ReferenceLoopHandling.Error, // 尽早发现循环引用 TypeNameHandling TypeNameHandling.None // 避免类型信息开销 };4. 调试与问题排查即使有了完善的配置序列化过程仍可能遇到各种问题。以下是一些常见问题及解决方案4.1 忽略特定属性有时需要动态控制哪些属性应该被序列化public class DynamicContractResolver : DefaultContractResolver { private readonly HashSetstring _propertiesToIgnore; public DynamicContractResolver(IEnumerablestring propertiesToIgnore) { _propertiesToIgnore new HashSetstring(propertiesToIgnore); } protected override JsonProperty CreateProperty(MemberInfo member, MemberSerialization memberSerialization) { var property base.CreateProperty(member, memberSerialization); if (_propertiesToIgnore.Contains(property.PropertyName)) { property.ShouldSerialize _ false; } return property; } } // 使用示例 var resolver new DynamicContractResolver(new[] { Password, CreditCard }); var settings new JsonSerializerSettings { ContractResolver resolver };4.2 处理版本兼容性当数据结构发生变化时可以配置如何处理缺失或额外的属性var versionSettings new JsonSerializerSettings { MissingMemberHandling MissingMemberHandling.Ignore, // 忽略JSON中多余的属性 DefaultValueHandling DefaultValueHandling.Populate // 为缺失属性设置默认值 };4.3 性能分析对于大型对象序列化可以使用以下技巧分析性能瓶颈public class ProfilingJsonConverter : JsonConverter { public override bool CanConvert(Type objectType) true; public override void WriteJson(JsonWriter writer, object value, JsonSerializer serializer) { var stopwatch Stopwatch.StartNew(); serializer.Serialize(writer, value); stopwatch.Stop(); Console.WriteLine($Serialized {value.GetType().Name} in {stopwatch.ElapsedMilliseconds}ms); } public override object ReadJson(JsonReader reader, Type objectType, object existingValue, JsonSerializer serializer) { throw new NotImplementedException(); } }