C# JSON序列化完整指南与常见问题解决方法

C# JSON序列化：那些看似“玄学”的问题，其实都有章可循

在C#里处理JSON，JsonSerializer.Serialize 或 JsonConvert.SerializeObject 这两行代码谁都会写。但真正让人头疼的，往往不是“怎么调”，而是那些藏在类型、配置、时区、命名规则里的细节。它们一旦对不上，轻则字段错位，重则数据丢失。下面这四大高频问题，几乎每个.NET开发者都会踩到。

System.Text.Json 默认驼峰命名、Newtonsoft.DateTime格式异常、字典键被改、long精度丢失是四大高频问题；需分别通过设置PropertyNamingPolicy=null、DateFormatHandling.IsoDateFormat、DefaultContractResolver、long转字符串解决。

System.Text.Json 默认驼峰命名导致字段名被改写

你有没有遇到过这种情况：明明在C#里定义的是 public string UserName { get; set; }，序列化出去却变成了 "userName"？先别急着怀疑人生，这通常不是bug，而是特性在起作用。

从.NET 6开始，System.Text.Json 默认启用了 JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase。这个策略尤其在ASP.NET Core Web API中会自动生效，目的是为了迎合前端Ja vaScript社区的命名习惯。

• 先确认需求：如果你的服务是内部系统，或者主要对接前端，用驼峰命名大概率没问题。但如果是和Ja va、Python等其他后端服务互通，对方很可能期望的是PascalCase（即首字母大写），这时就需要关掉它。
• 如何关掉：很简单，var options = new JsonSerializerOptions { PropertyNamingPolicy = null }; 就能让命名策略失效。
• 注意边界：这个设置只影响类的public属性名，默认不影响字典的key。除非你用的是.NET 7及以上版本，并且显式设置了 DictionaryKeyPolicy。
• 别混淆了：全局的 PropertyNamingPolicy 和单个属性上的 [JsonPropertyName("CustomName")] 特性是两回事。后者的优先级更高，可以覆盖全局策略。

Newtonsoft.Json 序列化 DateTime 输出 /Date(1234567890000)/ 格式

如果你还在用Newtonsoft.Json（即Json.NET），可能会发现序列化出来的时间戳长这样：/Date(1234567890000)/。这是库默认使用 Ja vaScriptDateTimeConverter 的结果，一种比较古老的格式。现代的API接口基本已经不认这种格式了，前端解析时要么失败，要么时间错乱。

• 强制使用ISO标准格式：最直接的解决方法是配置序列化设置：new JsonSerializerSettings { DateFormatHandling = DateFormatHandling.IsoDateFormat }。这样输出的就是 "2023-10-27T10:30:00Z" 这种通用格式。
• 时区问题不能只靠配置：如果服务端明确要求UTC时间，千万别只依赖这个配置。务必在序列化前，对DateTime对象调用 .ToUniversalTime()。否则，本地时区的时间会被直接当成UTC时间写进去，造成误解。
• 自定义格式更稳妥：对于有固定格式要求的场景，可以设置 DateFormatString = "yyyy-MM-dd HH:mm:ss"。但要注意，这个设置只在 DateFormatHandling = DateFormatHandling.Custom 时才会生效。
• 避免配置冲突：别在同一个属性的头上既标记了 [JsonConverter(typeof(DateTimeConverter))]，又在全局配置里配一遍，这样很容易导致行为不一致。

序列化 Dictionary 后键名丢失或全小写

字典序列化后，发现key的名字变了，甚至全变成小写了？别慌，数据没丢，是序列化库的默认策略在“动”你的key。

这里有个关键区别：System.Text.Json 默认会保留字典键的原样；而 Newtonsoft.Json 的行为则严重受 ContractResolver 影响。

• 检查Newtonsoft的解析器：如果你用了 CamelCasePropertyNamesContractResolver，那要注意了，它不仅会把属性名改成驼峰，字典的key也会被一并改造。
• 锁死原始键名：在Newtonsoft中，想保持key不变，可以使用默认的解析器：new JsonSerializerSettings { ContractResolver = new DefaultContractResolver() }。
• System.Text.Json的版本陷阱：在.NET 6及以后版本，如果你启用了全局的 PropertyNamingPolicy（比如驼峰），那么字典的key也会被影响而改变。这一点在早期版本中是不会发生的，非常容易忽略。
• 警惕嵌套序列化：如果字典的value是匿名对象或者动态的 JObject，要确保它本身没有被二次序列化。一个常见的坑是：JsonConvert.SerializeObject(new { data = JObject.Parse(json) })，里面的JObject可能已经被处理过一次了。

序列化 long 类型 ID 到前端时精度丢失

这是前后端联调时的一个经典“惨案”。C#里的 long 类型（Int64）最大值可以达到 2^63 - 1，常用于生成雪花ID等大数字。但Ja vaScript的 Number 类型，其最大安全整数是 2^53 - 1。一旦超过这个范围，数字传到前端就会精度丢失，变成一串奇怪的尾数。

• 根本解法：转成字符串：必须把long类型的值，在序列化阶段就转换成字符串。不要指望前端用 parseInt 去补救，那为时已晚。
• Newtonsoft的解决方案：推荐编写一个自定义转换器。继承 JsonConverter，然后重写 WriteJson 方法，在里面调用 writer.WriteValue(value.ToString()) 即可。
• System.Text.Json的解决方案：思路类似，继承 JsonConverter，实现对应的 Write 方法。最后记得在 JsonSerializerOptions 里通过 options.Converters.Add(new LongToStringConverter()) 注册这个转换器。
• 格式化不是关键：别纠结于用 ToString("D") 还是其他数字格式，只要最终输出的JSON值是带引号的字符串（如 "id": "1234567890123456789"），前端就能无损接收。

最后，还有一个最常被跳过的环节：序列化后的校验。代码跑通了，不代表JSON就对了。在把数据发出去之前，不妨先用 JsonDocument.Parse(json) 快速验证一下结构，或者扔到在线JSON格式化工具里看一眼。很多时候所谓的“序列化失败”，其实是上游数据拼接时字符串就错了，问题根本不在序列化逻辑本身。