Hot Chocolate 15 中的 ID 序列化回归问题分析与解决方案

问题背景

在 GraphQL 中，ID 类型是一个特殊的标量类型，用于唯一标识对象。Hot Chocolate 作为 .NET 平台的 GraphQL 框架，在版本 15 中对 ID 序列化机制进行了重大调整，这导致了一些向后兼容性问题。

问题现象

从 Hot Chocolate 14.3.0 升级到 15.0.3 后，开发者遇到了以下问题：

1. 使用自定义 ID 类型（如示例中的 MyKey 结构体）时，系统无法正确处理 ID 序列化
2. 即使调用了 AddLegacyNodeIdSerializer() 方法，ID 仍然以新格式输出
3. 查询返回错误："Cannot return null for non-nullable field" 和 "No serializer registered for type"

技术分析

旧版行为（v14.3.0）

在 Hot Chocolate 14 中，系统能够正确处理自定义 ID 类型的序列化：

• 自动使用注册的类型转换器（AddTypeConverter）
• 正确应用旧版 ID 序列化格式（Base64 编码的字符串）
• 无需额外配置即可工作

新版变化（v15.0.3）

Hot Chocolate 15 引入了以下变化：

1. 新的 ID 序列化格式（默认情况下）
2. 更严格的类型序列化检查
3. 需要显式注册自定义 ID 类型的序列化器

解决方案

方案一：注册自定义序列化器

开发者需要实现 INodeIdValueSerializer 接口并注册：

internal sealed class MyNodeIdValueSerializer : INodeIdValueSerializer
{
    public bool IsSupported(Type type) => type == typeof(MyKey);

    public NodeIdFormatterResult Format(Span<byte> buffer, object value, out int written)
    {
        var @string = ((MyKey)value).ToString();
        var bytes = Encoding.UTF8.GetBytes(@string);

        if (bytes.Length > buffer.Length)
        {
            written = 0;
            return NodeIdFormatterResult.BufferTooSmall;
        }

        bytes.CopyTo(buffer);
        written = bytes.Length;
        return NodeIdFormatterResult.Success;
    }

    public bool TryParse(ReadOnlySpan<byte> buffer, [NotNullWhen(true)] out object? value)
    {
        try
        {
            var @string = Encoding.UTF8.GetString(buffer);
            value = MyKey.Parse(@string);
            return true;
        }
        catch
        {
            value = null;
            return false;
        }
    }
}

方案二：强制使用旧版序列化格式

在注册自定义序列化器的同时，需要显式指定使用旧版格式：

services.AddGraphQLServer()
    .AddLegacyNodeIdSerializer()
    .AddGlobalObjectIdentification(false)
    .AddDefaultNodeIdSerializer(outputNewIdFormat: false)
    .AddSingleton<INodeIdValueSerializer, MyNodeIdValueSerializer>();

最佳实践建议

1. 评估升级必要性：如果不依赖新功能，可暂缓升级
2. 全面测试：升级后对所有ID相关功能进行测试
3. 文档参考：仔细阅读版本迁移指南
4. 统一格式：团队内部统一使用新版或旧版格式

总结

Hot Chocolate 15 对 ID 序列化机制的改进虽然带来了更好的灵活性和类型安全，但也增加了升级的复杂性。开发者需要根据项目需求选择合适的解决方案，确保平稳过渡。对于大型项目，建议分阶段实施升级，先解决核心功能，再逐步完善边缘案例。