C# ASP.NET Core JSON配置方法

全局JSON配置须在Program.cs服务注册阶段、AddControllers()之后Build()之前调用ConfigureHttpJsonOptions；System.Text.Json需手动设CamelCase、WhenWritingNull等，Newtonsoft需AddNewtonsoftJson且注意版本兼容。

ASP.NET Core 6+ 中 ConfigureJsonOptions 的正确注册位置

全局 JSON 序列化配置必须在 Program.cs 的服务注册阶段完成，且要在 AddControllers() 或 AddEndpointsApiExplorer() 之后、Build() 之前调用 ConfigureJsonOptions；否则配置不生效。常见错误是把它写在 app.Use...() 链中，或误放在 WebApplication.CreateBuilder() 之前。

• ASP.NET Core 6+ 推荐写法：builder.Services.ConfigureHttpJsonOptions(options => { ... })（用于 System.Text.Json）
• 若项目仍用 Newtonsoft.Json，需先安装 Microsoft.AspNetCore.Mvc.NewtonsoftJson，再用 AddControllers().AddNewtonsoftJson(options => { ... })
• ConfigureJsonOptions 是扩展方法，本质是对 IOptionsMonitor 的配置，不是直接修改单例实例

System.Text.Json 全局配置常用选项与陷阱

System.Text.Json 默认不支持循环引用、不忽略 null 值、属性名大小写敏感，且无法直接序列化 DateTime 为 Unix 时间戳——这些都得手动配。最易踩的坑是以为 PropertyNamingPolicy 能影响反序列化字段映射，其实它只控制序列化输出的 key 名，反序列化仍依赖属性名或 [JsonPropertyName] 特性。

• 驼峰命名：options.PropertyNamingPolicy = JsonNamingPolicy.CamelCase
• 忽略 null 值：options.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull（注意是 WhenWritingNull，不是 Always）
• 处理循环引用：原生不支持，必须改用 ReferenceHandler.Preserve（.NET 6+），但会引入 $id/$ref 字段，前端需兼容
• 自定义 DateTime 格式：需添加 Converters.Add(new JsonStringEnumConverter()) 类似方式注册 JsonConverter 子类

Newtonsoft.Json 在 ASP.NET Core 中的全局配置方式

虽然微软已转向 System.Text.Json，但大量老项目仍依赖 Newtonsoft.Json 的灵活性，比如动态属性、 TypeNameHandling、更细粒度的日期格式控制。它的全局配置入口和生命周期与原生不同，不能混用 ConfigureJsonOptions。

• 必须显式调用 AddNewtonsoftJson()，例如：services.AddControllers().AddNewtonsoftJson(options => { options.DateFormatString = "yyyy-MM-dd HH:mm:ss"; })
• ContractResolver 是核心扩展点，如用 CamelCasePropertyNamesContractResolver 实现驼峰，但它不会自动处理下划线转驼峰（需继承并重写 ResolvePropertyName）
• 若控制器方法返回 JsonResult，且未指定 JsonSerializerSettings，才走全局配置；若手动 new JsonSerializer，则不受影响
• 注意包版本兼容性：Microsoft.AspNetCore.Mvc.NewtonsoftJson 6.0.x 只支持 .NET 6，不兼容 .NET 8 运行时

如何让 API 返回值和 ModelBinding 输入共用同一套 JSON 配置

默认情况下，System.Text.Json 的序列化（输出）和反序列化（ModelBinding 输入）共享同一组 JsonOptions，但有个关键例外：JsonSerializerOptions 中的 ReadCommentHandling 和 AllowTrailingCommas 只影响反序列化，而 DefaultIgnoreCondition 同时影响双向。最容易被忽略的是绑定数组或集合时的空字符串处理——它不走 JSON 配置，而是由 ArrayModelBinder 或 ComplexObjectModelBinder 控制。

• 确保 services.Configure(...) 和 services.ConfigureHttpJsonOptions(...) 配置一致，后者优先级更高
• 若需对特定 Action 参数做定制反序列化，应使用 [FromBody] [JsonConverter(typeof(CustomConverter))]，而非改全局
• ModelBinding 对于 application/json 请求体，底层仍调用 JsonSerializer.DeserializeAsync，所以 Converters 列表对输入输出都生效
• 全局配置无法覆盖 [JsonIgnore]、[JsonPropertyName] 等特性，特性始终具有更高优先级

实际项目里，JsonOptions 配置看似简单，但一旦涉及多环境（开发/生产）、多客户端（Web/iOS/Android）、多数据源（DTO/Entity），各环节的序列化行为就容易错位。尤其要注意 DateTime 处理、null 值策略、以及 Newtonsoft 和原生 JSON 的转换器注册时机——差一行代码，就可能让前端拿到空对象或 400 错误。