.NET 5 序列化重大变更：KeyValuePair 现在遵循命名策略和编码器选项

.NET 5 序列化重大变更：KeyValuePair 现在遵循命名策略和编码器选项

痛点：KeyValuePair 序列化行为不一致

你是否曾经在使用 System.Text.Json 序列化 KeyValuePair<TKey, TValue> 时遇到过这样的困惑？在 .NET Core 3.x 及更早版本中，KeyValuePair 的序列化行为与其他字典类型不一致，它完全忽略了 JsonSerializerOptions 中配置的命名策略（Naming Policy）和编码器选项（Encoder Options）。

这种不一致性导致开发者需要为 KeyValuePair 编写特殊的处理逻辑，增加了代码复杂性和维护成本。特别是在微服务架构和API开发中，这种不一致性可能导致前后端数据格式不匹配的问题。

解决方案：.NET 5 的重大改进

从 .NET 5 开始，Microsoft 修复了这一长期存在的问题。现在 KeyValuePair<TKey, TValue> 的序列化行为与其他集合类型保持一致，完全遵循 JsonSerializerOptions 中配置的命名策略和编码器选项。

变更内容概览

特性	.NET Core 3.x 及之前	.NET 5 及之后
命名策略	忽略	遵循
编码器选项	忽略	遵循
大小写敏感性	忽略	遵循
与字典一致性	不一致	一致

代码示例：前后对比

.NET Core 3.x 行为（问题示例）

using System;
using System.Collections.Generic;
using System.Text.Json;

// 在 .NET Core 3.x 中
var options = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    PropertyNameCaseInsensitive = true
};

var kvp = new KeyValuePair<string, string>("FirstName", "John");
string json = JsonSerializer.Serialize(kvp, options);

// 输出: {"Key":"FirstName","Value":"John"}
// 注意：Key 和 Value 仍然是 PascalCase，没有应用 camelCase 策略

.NET 5+ 行为（修复后）

using System;
using System.Collections.Generic;
using System.Text.Json;

// 在 .NET 5+ 中
var options = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    PropertyNameCaseInsensitive = true
};

var kvp = new KeyValuePair<string, string>("FirstName", "John");
string json = JsonSerializer.Serialize(kvp, options);

// 输出: {"key":"FirstName","value":"John"}
// 现在正确应用了 camelCase 命名策略

技术深度解析

命名策略（Naming Policy）的工作原理

System.Text.Json 的命名策略通过 JsonNamingPolicy 类实现，主要包含：

• JsonNamingPolicy.CamelCase: 驼峰命名法
• JsonNamingPolicy.SnakeCase: 蛇形命名法（需要自定义）
• 自定义命名策略

编码器选项（Encoder Options）的影响

编码器选项控制字符编码和转义行为，包括：

var options = new JsonSerializerOptions
{
    Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping, // 宽松的JSON转义
    WriteIndented = true, // 格式化输出
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull // 忽略null值
};

实际应用场景

场景1：API响应标准化

在Web API开发中，保持响应格式的一致性至关重要：

[HttpGet("user/{id}")]
public IActionResult GetUser(int id)
{
    var user = _userService.GetUser(id);
    var metadata = new KeyValuePair<string, string>("retrievedAt", DateTime.UtcNow.ToString());
    
    var response = new
    {
        Data = user,
        Metadata = metadata
    };
    
    return Ok(response); // 现在Metadata会正确应用命名策略
}

场景2：配置序列化

public static JsonSerializerOptions GetApiJsonOptions()
{
    return new JsonSerializerOptions
    {
        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
        PropertyNameCaseInsensitive = true,
        Encoder = JavaScriptEncoder.Create(UnicodeRanges.All),
        WriteIndented = Environment.IsDevelopment()
    };
}

迁移指南

从 .NET Core 3.x 迁移到 .NET 5+

如果你现有的代码依赖于旧的序列化行为，需要进行以下检查：

1. 测试现有序列化输出：比较迁移前后的JSON输出差异
2. 更新测试用例：调整期望的JSON格式
3. 检查第三方集成：确保下游系统能够处理新的格式

向后兼容性考虑

// 如果需要保持旧行为，可以创建自定义转换器
public class LegacyKeyValuePairConverter<TKey, TValue> : JsonConverter<KeyValuePair<TKey, TValue>>
{
    public override KeyValuePair<TKey, TValue> Read(
        ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        // 实现自定义反序列化逻辑
    }

    public override void Write(
        Utf8JsonWriter writer, KeyValuePair<TKey, TValue> value, JsonSerializerOptions options)
    {
        writer.WriteStartObject();
        writer.WritePropertyName("Key"); // 硬编码属性名
        JsonSerializer.Serialize(writer, value.Key, options);
        writer.WritePropertyName("Value"); // 硬编码属性名
        JsonSerializer.Serialize(writer, value.Value, options);
        writer.WriteEndObject();
    }
}

性能考量

.NET 5 的改进不仅提供了功能一致性，还带来了性能优化：

操作	.NET Core 3.x	.NET 5+	改进幅度
KeyValuePair序列化	需要特殊处理	统一处理	~15% 更快
内存使用	较高	优化	~10% 减少
代码维护	复杂	简化	显著降低

最佳实践

1. 统一配置序列化选项

// 在Startup.cs或Program.cs中统一配置
services.Configure<JsonOptions>(options =>
{
    options.SerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
    options.SerializerOptions.PropertyNameCaseInsensitive = true;
});

2. 使用源生成器提升性能

[JsonSerializable(typeof(KeyValuePair<string, string>))]
public partial class MyJsonContext : JsonSerializerContext
{
}

// 使用源生成器进行序列化
var json = JsonSerializer.Serialize(kvp, MyJsonContext.Default.KeyValuePairStringString);

3. 测试覆盖

确保为序列化行为编写充分的测试：

[Test]
public void KeyValuePair_Serialization_RespectsNamingPolicy()
{
    var options = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase };
    var kvp = new KeyValuePair<string, int>("TestValue", 42);
    
    var json = JsonSerializer.Serialize(kvp, options);
    
    Assert.That(json, Contains.Substring("\"key\""));
    Assert.That(json, Contains.Substring("\"value\""));
}

总结

.NET 5 中 KeyValuePair 序列化行为的变更是向一致性、标准化迈出的重要一步。这个改进：

• ✅ 消除了不一致性：使 KeyValuePair 与其他集合类型的序列化行为保持一致
• ✅ 简化了代码：不再需要为 KeyValuePair 编写特殊处理逻辑
• ✅ 提升了性能：通过统一的处理路径优化了序列化性能
• ✅ 增强了可维护性：减少了代码复杂性和维护成本

对于正在迁移到 .NET 5+ 的开发者，建议充分测试现有的序列化逻辑，确保新的行为符合预期。对于新项目，可以放心使用这一改进特性，享受更加一致和高效的序列化体验。

---

立即行动：检查你的项目中是否使用了 KeyValuePair 序列化，体验 .NET 5+ 带来的这一重要改进吧！