C# System.Text.Json 中 JsonNamingPolicy 利用详解

来自云龙湖轮廓分明的月亮  论坛元老 | 2025-4-4 14:06:55 | 显示全部楼层 | 阅读模式
打印 上一主题 下一主题
楼主

主题 1511|帖子 1511|积分 4543

马上注册，结交更多好友，享用更多功能，让你轻松玩转社区。

您需要 登录 才可以下载或查看，没有账号？立即注册

x
总目录

一、JsonNamingPolicy 是什么？

1. 界说

JsonNamingPolicy 是 System.Text.Json 中用于 控制属性名称在序列化/反序列化时的定名格式的计谋类。它答应开发者将 .NET 对象的属性名称转换为指定的格式（如 camelCase、snake_case 等），或自界说其他定名规则。
   JsonNamingPolicy 是 System.Text.Json 定名空间中的一个类，用于界说如安在序列化和反序列化过程中处置惩罚属性名称与 JSON 字段名称之间的映射关系。
  

  • 通过利用 JsonNamingPolicy，开发者可以自界说 JSON 字段的定名约定，比方将 C# 中的驼峰定名约定转换为 JSON 中的蛇形定名约定，或者反之。
  • JsonNamingPolicy 通过重写 ConvertName 方法来实现名称转换逻辑。在序列化过程中，ConvertName 方法接收 C# 属性名称并返回 JSON 字段名称；在反序列化过程中，它接收 JSON 字段名称并返回 C# 属性名称。这种双向映射机制确保了在序列化和反序列化过程中名称转换的划一性。
  2. 核心作用



  • 序列化时：将 C# 属性名转换为指定格式（如 PascalCase → camelCase）。
  • 反序列化时：将 JSON 中的键名转换为对象的属性名。
  • 定名优先级：显式标记 [JsonPropertyName] 的属性优先级高于定名计谋。
3. 适用场景

JsonNamingPolicy 是 System.Text.Json 中 控制属性名称格式的核心工具，适用于以下场景：


  • 适配前后端定名规范（如 C# 的 PascalCase 转为前端的 camelCase）。
  • 同一 API 接口的键名格式（如 snake_case）。
  • 自界说特别定名规则（如添加前缀/后缀）。
通过内置计谋或自界说实现，开发者可以灵活控制 JSON 的属性名称，确保与外部系统的兼容性及代码的可维护性。
二、内置定名计谋

System.Text.Json 提供了多种内置定名计谋，以满意不同的定名约定需求：
1. 默认计谋

默认情况下，无计谋（null） ，即保存原始属性名（如 UserName → UserName）。
   不过通常在 C# 中 属性会遵守PascalCase 定名计谋
  1. public class User
  2. {
  3.     public string UserName { get; set; }
  4.     public int UserAge { get; set; }
  5. }
  6. class Program
  7. {
  8.     static void Main()
  9.     {
  10.         var user = new User { UserName = "John", UserAge = 15 };
  11.         
  12.         // 序列化
  13.         string json = JsonSerializer.Serialize(user);
  14.         Console.WriteLine(json);
  15.         // 输出：{"UserName":"John","UserAge":15}
  17.         // 反序列化
  18.         string jsonString = """{"UserName":"John","UserAge":15}""";
  19.         var u= JsonSerializer.Deserialize<User>(jsonString);
  20.         Console.WriteLine($"UserName = {u.UserName} ,UserAge = {u.UserAge}");
  21.         // 输出：UserName = John ,UserAge = 15
  22.     }
  23. }
复制代码
2. CamelCase

JsonNamingPolicy.CamelCase 计谋将 PascalCase 的 C# 属性名称转换为 camelCase 的 JSON 字段名称。比方，PublicProperty 将被转换为 “publicProperty”。
  1. public class User
  2. {
  3.     public string UserName { get; set; }
  4.     public int UserAge { get; set; }
  5. }
  6. class Program
  7. {
  8.     static void Main()
  9.     {
  10.         var user = new User { UserName = "John", UserAge = 15 };
  12.         var options = new JsonSerializerOptions
  13.         {
  14.             PropertyNamingPolicy = JsonNamingPolicy.CamelCase
  15.         };
  16.         // 序列化
  17.         string json = JsonSerializer.Serialize(user,options);
  18.         Console.WriteLine(json);
  19.         // 输出：{"userName":"John","userAge":15}
  21.         // 反序列化
  22.         string jsonString = """{"userName":"John","userAge":15}""";
  23.         var u= JsonSerializer.Deserialize<User>(jsonString);
  24.         Console.WriteLine($"UserName = {u.UserName} ,UserAge = {u.UserAge}");
  25.         // 输出：UserName =  ,UserAge = 0
  27.         var u2 = JsonSerializer.Deserialize<User>(jsonString,options);
  28.         Console.WriteLine($"UserName = {u2.UserName} ,UserAge = {u2.UserAge}");
  29.         // 输出：UserName = John ,UserAge = 15
  30.     }
  31. }
复制代码
  留意：序列化和反序列化的时候须要保持利用划一的定名计谋，否则就会出现如上案例所示的问题
  3. SnakeCaseLower/SnakeCaseUpper



  • JsonNamingPolicy.SnakeCaseLower 计谋将 PascalCase 的 C# 属性名称转换为 snake_case 的 JSON 字段名称，并且字段名称为小写。比方，PublicProperty 将被转换为 “public_property”。
  • JsonNamingPolicy.SnakeCaseUpper 计谋将 PascalCase 的 C# 属性名称转换为 SNAKE_CASE 的 JSON 字段名称，并且字段名称为大写。比方，PublicProperty 将被转换为 “PUBLIC_PROPERTY”。
  1. public class User
  2. {
  3.     public string UserName { get; set; }
  4.     public int UserAge { get; set; }
  5. }
  6. class Program
  7. {
  8.     static void Main()
  9.     {
  10.         var user = new User { UserName = "John", UserAge = 15 };
  12.         var options = new JsonSerializerOptions
  13.         {
  14.             PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseUpper
  15.         };
  17.         var options2 = new JsonSerializerOptions
  18.         {
  19.             PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower
  20.         };
  22.         // 序列化
  23.         string json = JsonSerializer.Serialize(user,options);
  24.         Console.WriteLine(json);
  25.         // 输出：{"USER_NAME":"John","USER_AGE":15}
  27.         json = JsonSerializer.Serialize(user, options2);
  28.         Console.WriteLine(json);
  29.         // 输出：{"user_name":"John","user_age":15}
  32.         // 反序列化
  33.         string jsonString = """{"USER_NAME":"John","USER_AGE":15}""";
  34.         var u= JsonSerializer.Deserialize<User>(jsonString,options);
  35.         Console.WriteLine($"UserName = {u.UserName} ,UserAge = {u.UserAge}");
  36.         // 输出：UserName = John ,UserAge = 15
  37.     }
  38. }
复制代码
4. KebabCaseUpper/KebabCaseLower



  • JsonNamingPolicy.KebabCaseLower 计谋将 PascalCase 的 C# 属性名称转换为 kebab-case 的 JSON 字段名称，并且字段名称为小写。比方，UserName 将被转换为 “user-name”。
  • JsonNamingPolicy.KebabCaseUpper 计谋将 PascalCase 的 C# 属性名称转换为 KEBAB_CASE 的 JSON 字段名称，并且字段名称为大写。比方，UserName 将被转换为 “USER-NAME”。
  1. public class User
  2. {
  3.     public string UserName { get; set; }
  4.     public int UserAge { get; set; }
  5. }
  6. class Program
  7. {
  8.     static void Main()
  9.     {
  10.         var user = new User { UserName = "John", UserAge = 15 };
  12.         var options = new JsonSerializerOptions
  13.         {
  14.             PropertyNamingPolicy = JsonNamingPolicy.KebabCaseUpper
  15.         };
  17.         var options2 = new JsonSerializerOptions
  18.         {
  19.             PropertyNamingPolicy = JsonNamingPolicy.KebabCaseLower
  20.         };
  22.         // 序列化
  23.         string json = JsonSerializer.Serialize(user,options);
  24.         Console.WriteLine(json);
  25.         // 输出：{"USER-NAME":"John","USER-AGE":15}
  27.         json = JsonSerializer.Serialize(user, options2);
  28.         Console.WriteLine(json);
  29.         // 输出：{"user-name":"John","user-age":15}
  32.         // 反序列化
  33.         string jsonString = """{"USER-NAME":"John","USER-AGE":15}""";
  34.         var u= JsonSerializer.Deserialize<User>(jsonString,options);
  35.         Console.WriteLine($"UserName = {u.UserName} ,UserAge = {u.UserAge}");
  36.         // 输出：UserName = John ,UserAge = 15
  37.     }
  38. }
复制代码
5. 示例：内置计谋与 WriteIndented 共同利用

JsonNamingPolicy 不但可以处置惩罚简单的对象，还可以处置惩罚包含嵌套对象和聚集的复杂对象图。定名计谋会递归地应用于对象图中的全部对象。
  1. public class Person
  2. {
  3.     public string FirstName { get; set; }
  4.     public string LastName { get; set; }
  5.     public Address Address { get; set; }
  6. }
  7. public class Address
  8. {
  9.     public string Street { get; set; }
  10.     public string City { get; set; }
  11.     public List<PhoneNumber> PhoneNumbers { get; set; }
  12. }
  13. public class PhoneNumber
  14. {
  15.     public string Type { get; set; }
  16.     public string Number { get; set; }
  17. }
  18. var person = new Person
  19. {
  20.     FirstName = "John",
  21.     LastName = "Doe",
  22.     Address = new Address
  23.     {
  24.         Street = "123 Main St",
  25.         City = "New York",
  26.         PhoneNumbers = new List<PhoneNumber>
  27.         {
  28.             new PhoneNumber { Type = "home", Number = "555-1234" },
  29.             new PhoneNumber { Type = "work", Number = "555-5678" }
  30.         }
  31.     }
  32. };
  33. var options = new JsonSerializerOptions
  34. {
  35.     NamingPolicy = JsonNamingPolicy.CamelCase,
  36.     WriteIndented = true
  37. };
  38. string json = JsonSerializer.Serialize(person, options);
  39. // 输出:
  40. //{
  41. //  "firstName": "John",
  42. //  "lastName": "Doe",
  43. //  "address": {
  44. //    "street": "123 Main St",
  45. //    "city": "New York",
  46. //    "phoneNumbers": [
  47. //      {
  48. //        "type": "home",
  49. //        "number": "555-1234"
  50. //      },
  51. //      {
  52. //        "type": "work",
  53. //        "number": "555-5678"
  54. //      }
  55. //    ]
  56. //  }
  57. //}
复制代码
三、自界说定名计谋

除了内置的定名计谋外，System.Text.Json 还答应开发者创建自界说的定名计谋，以满意特定的定名转换需求。要创建自界说定名计谋，须要创建一个继续自 JsonNamingPolicy 的类，并重写 ConvertName 方法。
1. 创建并利用自界说定名计谋

1）创建自界说定名计谋

通过继续 JsonNamingPolicy 并重写 ConvertName 方法，可以实现自界说的定名规则。
  1. public class AllUppercaseNamingPolicy : JsonNamingPolicy
  2. {
  3.     public override string ConvertName(string name)
  4.     {
  5.         return name.ToUpper();
  6.     }
  7. }
复制代码
在上述示例中，AllUppercaseNamingPolicy 类将全部属性名称转换为全大写。
2）利用自界说定名计谋

要利用这个自界说计谋，可以将其配置到 JsonSerializerOptions 中：
  1. public class User
  2. {
  3.     public string UserName { get; set; }
  4.     public int UserAge { get; set; }
  5. }
  6. class Program
  7. {
  8.     static void Main()
  9.     {
  10.         var user = new User { UserName = "John", UserAge = 15 };
  12.         var options = new JsonSerializerOptions
  13.         {
  14.             PropertyNamingPolicy = new AllUppercaseNamingPolicy()
  15.         };
  17.         // 序列化
  18.         string json = JsonSerializer.Serialize(user,options);
  19.         Console.WriteLine(json);
  20.         // 输出：{"USERNAME":"John","USERAGE":15}
  22.         // 反序列化
  23.         string jsonString = """{"USERNAME":"John","USERAGE":15}""";
  24.         var u= JsonSerializer.Deserialize<User>(jsonString,options);
  25.         Console.WriteLine($"UserName = {u.UserName} ,UserAge = {u.UserAge}");
  26.         // 输出：UserName = John ,UserAge = 15
  27.     }
  28. }
复制代码
2. 自界说定名计谋处置惩罚定名冲突

在某些情况下，JSON 字段名称大概与 C# 属性名称不匹配，或者存在定名冲突。通过创建自界说的定名计谋，可以解决这些问题。
  1. public class CustomNamingPolicy : JsonNamingPolicy
  2. {
  3.     public override string ConvertName(string name)
  4.     {
  5.         // 处理特定的命名转换
  6.         if (name == "CreatedDate")
  7.             return "created_at";
  8.         
  9.         // 对于其他属性，使用默认的 PascalCase 到 snake_case 转换
  10.         return name.Replace(" ", "_").ToLower();
  11.     }
  12. }
复制代码
四、字典键的定名计谋（DictionaryKeyPolicy）

通过 JsonSerializerOptions.DictionaryKeyPolicy，可以控制 字典键名的格式。
示例：字典键转为驼峰定名
  1. class Program
  2. {
  3.     static void Main()
  4.     {
  5.         var dictionary = new Dictionary<string, string>
  6.         {
  7.             ["UserName"] = "John",
  8.             ["UserPwd"] = "123"
  9.         };
  11.         var options = new JsonSerializerOptions
  12.         {
  13.             DictionaryKeyPolicy = JsonNamingPolicy.CamelCase // 字典键转为 camelCase
  14.         };
  16.         string json = JsonSerializer.Serialize(dictionary, options);
  17.         Console.WriteLine(json); //输出：{"userName":"John","userPwd":"123"}
  19.         var options2 = new JsonSerializerOptions
  20.         {
  21.             DictionaryKeyPolicy = new CustomCamelCasePolicy()
  22.         };
  23.         json = JsonSerializer.Serialize(dictionary, options2);
  24.         Console.WriteLine(json); //输出：{"userName":"John","userPwd":"123"}
  25.     }
  26. }
  28. public class CustomCamelCasePolicy : JsonNamingPolicy
  29. {
  30.     public override string ConvertName(string name)
  31.     {
  32.         return  char.ToLower(name[0]) + name.Substring(1);
  33.     }
  34. }
复制代码
五、与 JsonPropertyName 特性联合

JsonPropertyNameAttribute 的优先级高于 JsonNamingPolicy，可覆盖定名计谋。
  1. public class Product
  2. {
  3.     [JsonPropertyName("product_id")] // 显式指定名称
  4.     public int Id { get; set; }
  5.     public string Name { get; set; } // 使用命名策略
  6. }
  8. var options = new JsonSerializerOptions
  9. {
  10.     PropertyNamingPolicy = JsonNamingPolicy.CamelCase
  11. };
  13. var product = new Product { Id = 1, Name = "Laptop" };
  14. string json = JsonSerializer.Serialize(product, options);
  15. // 输出：{"product_id":1,"name":"Laptop"}（Name 转为 name）
复制代码
六、定名计谋的留意事项

在利用 JsonNamingPolicy 时，须要留意以下几点：

  • 计谋划一性：在序列化和反序列化过程中，应利用相同的定名计谋，以确保名称映射的划一性。
    1. // 序列化时使用驼峰命名
    2. var serializedJson = JsonSerializer.Serialize(user, options); // 输出 {"userName":"Alice"}
    4. // 反序列化时需使用相同策略
    5. var deserializedUser = JsonSerializer.Deserialize<User>(serializedJson, options);
    6. // 成功匹配属性
    复制代码
  • 性能思量：利用定名计谋大概会对性能产生轻微的影响，因为须要举行额外的字符串转换操纵。对于性能敏感的应用

    • 可以思量优化名称转换逻辑。
    • 避免频繁创建 JsonSerializerOptions：如果定名计谋是固定的，可以创建一个静态的 JsonSerializerOptions 实例，并在应用程序中复用它。

  • 忽略大小写：默认情况下，System.Text.Json 在反序列化过程中是大小写敏感的。如果须要举行大小写不敏感的匹配，可以设置 PropertyNameCaseInsensitive 选项为 true。
    1. var options = new JsonSerializerOptions
    2. {
    3.     PropertyNameCaseInsensitive = true
    4. };
    复制代码
结语

回到目录页：C#/.NET 知识汇总
盼望以上内容可以帮助到各人，如文中有不对之处，还请品评指正。
参考资料：


  • .NET 官方文档：JsonNamingPolicy
  • System.Text.Json 完全指南

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。
回复

使用道具 举报

0 个回复

倒序浏览
返回列表

快速回复

高级模式
B Color Image Link Quote Code Smilies
您需要登录后才可以回帖 登录 or 立即注册

本版积分规则

来自云龙湖轮廓分明的月亮

论坛元老
这个人很懒什么都没写!

楼主热帖

标签云

集成商 AI 运维 CIO 存储 服务器
微信订阅号
微信服务号
微信客服
小程序
H5
关于我们 商务合作 网站地图
©Copyright 2022-2024 杭州祥升科技有限公司 版权所有 浙ICP备20004199号
快速回复 返回顶部 返回列表