JsonProperty序列化时属性名不匹配怎么办？

Question

在使用 `JsonProperty` 特性进行 JSON 序列化时，常遇到属性名与实际 JSON 字段不匹配的问题。例如，C# 属性名为 `UserName`，但期望序列化为 `user_name` 或 `userName`。若未正确配置 `JsonProperty` 特性，会导致反序列化失败或字段丢失。此问题多因命名约定差异（如驼峰、下划线）引起，尤其在对接第三方 API 时尤为常见。需确保在实体类中显式使用 `JsonProperty("user_name")` 指定对应字段名，并确认所用序列化库（如 Newtonsoft.Json 或 System.Text.Json）支持该特性，避免因忽略特性或拼写错误导致映射失效。

Answer 1

1. 问题背景与常见场景分析

在现代 Web 开发中，C# 后端服务常需与前端或第三方 API 进行 JSON 数据交互。由于不同平台对命名约定的偏好不同（如 JavaScript 常用 camelCase，Python 偏好 snake_case），导致 C# 中的 PascalCase 属性名（如 UserName）无法直接映射到 JSON 字段（如 user_name 或 userName）。

若未正确使用 [JsonProperty] 特性，序列化库将默认按照属性名进行转换，造成字段不匹配、反序列化失败或数据丢失。尤其是在对接 OpenAPI 规范定义的接口时，此类问题尤为突出。

2. 核心机制：JsonProperty 特性的基本用法

• [JsonProperty("user_name")] 显式指定属性在 JSON 中的名称。
• 适用于 Newtonsoft.Json 和 System.Text.Json（需启用兼容模式）。
• 可应用于属性、字段，甚至支持条件性序列化（通过 NullValueHandling 等设置）。

public class User
{
    [JsonProperty("user_name")]
    public string UserName { get; set; }

    [JsonProperty("created_at")]
    public DateTime CreatedAt { get; set; }
}

3. 深层解析：Newtonsoft.Json 与 System.Text.Json 的差异

特性	Newtonsoft.Json	System.Text.Json
JsonProperty 支持	原生支持	需添加 [JsonConverter] 或配置命名策略
默认命名策略	PascalCase	camelCase（默认）
自定义命名策略	通过 ContractResolver	通过 JsonNamingPolicy
性能表现	较慢	更高性能

4. 实际开发中的典型错误案例

1. 忘记添加 [JsonProperty] 导致字段映射失败。
2. 拼写错误，如写成 [JsonProperty("useer_name")]。
3. 混合使用两个序列化库，导致特性被忽略。
4. 未统一全局命名策略，部分字段手动标注，部分依赖默认行为。
5. 在继承体系中父类字段未正确标记，子类反序列化时值为 null。
6. 忽略只读属性或私有 setter 的序列化支持。
7. 使用匿名对象或 ExpandoObject 时误以为 JsonProperty 生效。
8. 在 ASP.NET Core 中未配置 MVC 选项以统一序列化行为。
9. 缓存了旧版本 DTO 类型，导致运行时映射异常。
10. 未处理大小写敏感性问题，特别是在非严格模式下解析 JSON。

5. 解决方案设计：从局部到全局的映射策略

针对命名不一致问题，建议采用分层解决思路：

// 全局配置示例（System.Text.Json）
var options = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    PropertyNameCaseInsensitive = true
};

// 或使用自定义策略（snake_case）
options.PropertyNamingPolicy = new SnakeCaseNamingPolicy();

// 自定义命名策略实现
public class SnakeCaseNamingPolicy : JsonNamingPolicy
{
    public override string ConvertName(string name)
        => string.Concat(
            (name ?? "").Select((c, i) => i > 0 && char.IsUpper(c) ? $"_{char.ToLower(c)}" : c.ToString())).ToLower();
}
  

6. 架构级最佳实践与流程控制

graph TD A[定义数据传输对象DTO] --> B{是否对接外部API?} B -- 是 --> C[显式使用[JsonProperty]] B -- 否 --> D[采用统一命名策略] C --> E[测试序列化输出] D --> E E --> F{字段匹配正确?} F -- 否 --> G[检查特性拼写/库兼容性] F -- 是 --> H[集成至业务逻辑] G --> I[修正配置并重新验证] I --> E