企业官网建设流程全解析

从Newtonsoft.Json迁移到System.Text.Json的实战避坑指南

如果你正在维护一个使用Newtonsoft.Json的C#项目，可能会考虑迁移到.NET官方推荐的System.Text.Json库。这种迁移不仅能减少第三方依赖，还能获得更好的性能表现。但迁移过程并非简单的替换命名空间，两个库在API设计、默认行为和扩展机制上存在诸多差异。本文将带你深入剖析迁移过程中的关键挑战，并提供可落地的解决方案。

1. 迁移前的战略准备

在动手修改代码之前，需要做好充分的准备工作。我们团队在最近一次大型项目迁移中，发现前期规划能减少70%以上的意外问题。

首先进行依赖分析，使用Visual Studio的解决方案资源管理器或dotnet list package命令，统计项目中所有引用Newtonsoft.Json的地方。重点关注：

• 直接项目引用
• 间接依赖（通过其他NuGet包引入）
• 动态加载的插件或模块

关键检查点清单：

1. 项目中Newtonsoft.Json的版本分布
2. 使用[JsonProperty]特性的类数量
3. 自定义转换器的实现类
4. 全局序列化设置的调用位置

建立完整的测试覆盖是迁移成功的保障。建议准备三类测试用例：

// 基础功能测试示例 public class SerializationTests { [Fact] public void BasicObject_ShouldSerializeCorrectly() { var obj = new { Name = "Test", Value = 42 }; var json = JsonConvert.SerializeObject(obj); var result = JsonSerializer.Deserialize<dynamic>(json); Assert.Equal("Test", result.Name.GetString()); } }

性能基准测试也不可忽视。可以使用BenchmarkDotNet建立对比测试：

2. API差异与行为变更的应对策略

两个库最明显的区别在于顶层API设计。Newtonsoft.Json使用静态类JsonConvert，而System.Text.Json采用实例模式。这种差异会影响全局配置方式：

// Newtonsoft.Json全局配置 JsonConvert.DefaultSettings = () => new JsonSerializerSettings { NullValueHandling = NullValueHandling.Ignore, Formatting = Formatting.Indented }; // System.Text.Json等效配置 var options = new JsonSerializerOptions { DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull, WriteIndented = true }; // 需要显式传递options到每个序列化调用

大小写策略是另一个常见痛点。System.Text.Json默认使用camelCase，而Newtonsoft.Json默认保留原始大小写。可以通过以下方式统一行为：

// Newtonsoft.Json配置 { "PropertyNamingPolicy": "CamelCase" } // System.Text.Json等效配置 new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase }

特殊类型处理需要特别注意：

• 枚举类型：System.Text.Json默认序列化为数字，需配置JsonStringEnumConverter
• DateTime：System.Text.Json默认采用ISO 8601格式（"yyyy-MM-ddTHH:mm:ss.fffZ"）
• 集合类型：空集合处理策略不同

3. 自定义转换器的深度改造

自定义转换器是迁移过程中最具挑战性的部分。System.Text.Json的转换器接口完全不同，需要重写实现逻辑。以下是一个处理特殊日期格式的转换器对比：

Newtonsoft.Json实现：

public class CustomDateConverter : JsonConverter<DateTime> { public override DateTime ReadJson(JsonReader reader, Type type, object value, JsonSerializer serializer) { var str = reader.Value.ToString(); return DateTime.ParseExact(str, "dd/MM/yyyy", CultureInfo.InvariantCulture); } public override void WriteJson(JsonWriter writer, object value, JsonSerializer serializer) { writer.WriteValue(((DateTime)value).ToString("dd/MM/yyyy")); } }

System.Text.Json等效实现：

public class CustomDateConverter : JsonConverter<DateTime> { public override DateTime Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) { var str = reader.GetString(); return DateTime.ParseExact(str, "dd/MM/yyyy", CultureInfo.InvariantCulture); } public override void Write(Utf8JsonWriter writer, DateTime value, JsonSerializerOptions options) { writer.WriteStringValue(value.ToString("dd/MM/yyyy")); } }

循环引用处理是另一个关键差异点。Newtonsoft.Json默认支持循环引用检测，而System.Text.Json需要显式配置：

// System.Text.Json循环引用解决方案 options.ReferenceHandler = ReferenceHandler.Preserve;

这将改变JSON输出结构，添加额外的$id和$ref元数据。

4. 渐进式迁移实战方案

对于大型项目，推荐采用渐进式迁移策略。我们团队在实践中总结出三步走方案：

1. 并行运行阶段（1-2周）
   • 同时引用两个库
   • 逐步替换核心模块
   • 使用适配器模式统一接口

public interface IJsonSerializer { string Serialize<T>(T obj); T Deserialize<T>(string json); } // System.Text.Json实现 public class SystemTextJsonSerializer : IJsonSerializer { private readonly JsonSerializerOptions _options; public string Serialize<T>(T obj) => JsonSerializer.Serialize(obj, _options); public T Deserialize<T>(string json) => JsonSerializer.Deserialize<T>(json, _options); }

2. 过渡验证阶段（2-4周）

   • 新旧实现结果对比验证
   • 性能监控
   • 边缘case测试

3. 完全切换阶段（1周）

   • 移除Newtonsoft.Json依赖
   • 清理适配器代码
   • 更新构建脚本

迁移路线图关键节点：

5. 性能优化与最佳实践

迁移完成后，可以通过以下技巧进一步提升System.Text.Json的性能：

1. 重用JsonSerializerOptions实例
2. 对热路径代码使用源生成器
3. 合理配置序列化选项

源生成器是.NET 6引入的重大改进，可以显著提升性能：

[JsonSerializable(typeof(MyPoco))] public partial class MyJsonContext : JsonSerializerContext {} // 使用生成的序列化代码 var json = JsonSerializer.Serialize(obj, MyJsonContext.Default.MyPoco);

提示：源生成器在AOT编译场景下尤其重要，可以完全避免反射开销

内存分配优化对比：

最后，分享几个我们踩过的坑及解决方案：

1. 异步流处理：System.Text.Json的DeserializeAsync方法需要特别注意流的位置管理
2. 多态序列化：使用[JsonDerivedType]特性替代Newtonsoft的类型转换器
3. 动态类型：JsonNode类提供了类似JToken的动态访问能力