HotChocolate 中为自动生成类型添加 Federation 共享指令的解决方案

背景介绍

在 GraphQL 联邦架构（Federation）中，当多个子图共享相同的类型时，Federation v2 规范要求这些共享值类型必须标记为 @shareable 指令。然而，在使用 HotChocolate 框架时，框架自动生成的类型（如分页查询中的 PageInfo 类型）默认没有这个标记，导致子图校验失败。

问题表现

当使用 UsePaging 属性时，HotChocolate 会自动生成 PageInfo 类型。在联邦架构中，如果多个子图都使用了分页功能，就会出现 PageInfo 类型的字段被多个子图解析的情况。由于这些字段没有被标记为 @shareable，Federation 会报错：

Non-shareable field "PageInfo.hasNextPage" is resolved from multiple subgraphs

解决方案演进

1. 类型拦截器方案（早期方案）

最初开发者尝试通过自定义类型拦截器来添加 @shareable 指令：

public class ShareableDirectiveTypeInterceptor : TypeInterceptor
{
    public override void OnBeforeCompleteType(
        ITypeCompletionContext completionContext,
        DefinitionBase definition)
    {
        if (definition is ObjectTypeDefinition otd && definition.Name == "PageInfo")
        {
            otd.AddDirective("shareable", completionContext.TypeInspector);
        }
        base.OnBeforeCompleteType(completionContext, definition);
    }
}

但这种方法需要额外添加一个虚拟类型来确保 @shareable 指令被正确导入到 @link 指令中。

2. 类型扩展方案（推荐方案）

更简洁的解决方案是使用 HotChocolate 的类型扩展功能：

public class PageInfoType : ObjectTypeExtension
{
    protected override void Configure(IObjectTypeDescriptor descriptor)
    {
        descriptor.Name("PageInfo");
        descriptor.Shareable();
    }
}

然后在服务配置中注册这个扩展：

services.AddGraphQLServer()
    .AddApolloFederation()
    .AddTypeExtension<PageInfoType>();

这种方法更加直观和简洁，不需要额外的虚拟类型或复杂的拦截器逻辑。

官方实现

HotChocolate 团队在 14.1 版本中已经将这一功能集成到核心代码中。开发者现在可以直接使用框架提供的原生支持，而不需要自己实现解决方案。

最佳实践建议

1. 对于新项目：建议升级到最新版本的 HotChocolate，直接使用框架内置的支持。

2. 对于现有项目：

   • 如果可以升级，优先升级框架版本
   • 如果暂时不能升级，使用类型扩展方案是最简洁的临时解决方案
   • 类型拦截器方案可以作为备选，但需要额外处理指令导入问题

3. 联邦架构设计：在联邦架构中，所有可能被多个子图共享的类型都应该标记为 @shareable，包括框架自动生成的类型。

总结

HotChocolate 框架对 Federation 的支持正在不断完善。通过理解框架的扩展机制，开发者可以灵活地解决自动生成类型的联邦共享问题。随着框架的更新，这些解决方案会变得更加简单和标准化。