options.JsonSerializerOptions了解

options.JsonSerializerOptions 就是 System.Text.Json 的“遥控器”——
你通过它告诉序列化器：
“属性名用驼峰还是原样？要不要缩进？遇到循环引用怎么办？日期怎么格式化？哪些字段要忽略？”
所有开关都在这个类里，不改就按默认行为，改了立即生效。

---

1. 所在位置（ASP.NET Core 里常见 3 个入口）

---

表格

复制

入口	影响范围
builder.Services.Configure<JsonOptions>(o => o.SerializerOptions.XXX = …)	整个 MVC / WebAPI 的 Ok()、return Json(obj)
builder.Services.ConfigureHttpJsonOptions(o => o.SerializerOptions.XXX = …)	最小 API 的 Results.Json()
手动 JsonSerializer.Serialize(obj, new JsonSerializerOptions { … })	仅这一次调用

---

2. 常用开关速查表（.NET 6+）

---

表格

复制

属性	示例值	作用
PropertyNamingPolicy	JsonNamingPolicy.CamelCase	属性名驼峰化 userName
WriteIndented	true	输出带缩进的漂亮 JSON
DefaultIgnoreCondition	JsonIgnoreCondition.WhenWritingNull	不序列化 null 值
ReferenceHandler	ReferenceHandler.IgnoreCycles	打破循环引用
Converters	new(){ new JsonStringEnumConverter() }	注册自定义转换器（枚举转字符串、DateOnly、long→string 防精度丢等）
PropertyNameCaseInsensitive	true	反序列化时属性名不区分大小写
NumberHandling	JsonNumberHandling.AllowReadingFromString	允许字符串 "123" 转数字
Encoder	JavaScriptEncoder.UnsafeRelaxedJsonEscaping	中文不转义成 \u4E2D
MaxDepth	64	最大嵌套深度，默认 64
IncludeFields	true	把 public 字段 也当 JSON 属性

---

3. 一段代码看全效果

---

csharp

复制

builder.Services.Configure<JsonOptions>(options =>
{
    options.SerializerOptions = new JsonSerializerOptions
    {
        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
        WriteIndented = true,
        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
        ReferenceHandler = ReferenceHandler.IgnoreCycles,
        Converters = { new JsonStringEnumConverter(), new DateOnlyConverter() },
        Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping
    };
});

 

---

4. 与 Newtonsoft.Json 的对比提醒

---

• System.Text.Json 默认更严格（大小写敏感、不序列化字段、不处理循环）。
• 只要记住：所有“宽容”行为都要手动在 JsonSerializerOptions 里打开。

---

一句话总结

JsonSerializerOptions 就是 System.Text.Json 的“配置面板”——
你想让序列化器“驼峰、忽略 null、打破循环、枚举转字符串、中文不转义”……统统在这里拧开关。