Pothos GraphQL 中强制包含子图中的外部引用类型

在构建 GraphQL 联邦架构时，我们经常会遇到需要在子图中包含某些类型，即使这些类型没有直接通过查询或变更公开的情况。本文将探讨在 Pothos GraphQL 框架中如何解决这一问题。

问题背景

在联邦架构设计中，有时我们需要在子图中包含某些实体类型（如 User），即使这些类型没有直接暴露在任何查询或变更中。这种情况通常发生在：

1. 我们需要为这些类型添加扩展字段
2. 这些类型需要参与联邦解析
3. 其他子图可能需要引用这些类型

在 Pothos 中，当我们使用 builder.externalRef 定义外部引用类型时，默认情况下如果该类型没有在任何查询或变更中返回，它将被子图插件自动修剪掉。

解决方案

Pothos 的最新版本（1.5.0+）引入了一个新的配置选项 includeTypes，专门用于解决这个问题。这个选项允许我们显式指定哪些类型应该包含在子图中，即使它们没有被直接引用。

使用方法

import { builder } from './builder';

export const User = builder.externalRef(
  "User",
  builder.keyDirective(builder.selection<{ id: string }>("id"), false)
);

User.implement({
  externalFields: t => ({
    id: t.id({ nullable: false }),
  }),
});

builder.objectField(User, "pets", t => {
  // 添加扩展字段
});

// 在构建schema时配置
builder.toSchema({
  plugins: {
    subGraph: {
      includeTypes: ['User'] // 显式包含User类型
    }
  }
});

技术原理

这个解决方案背后的技术原理是：

1. 子图插件的工作机制：子图插件默认会修剪所有未使用的类型，这是为了保持生成的子图架构精简高效。

2. 联邦插件的特殊性：联邦插件通过 _entities 查询使某些类型变得可访问，但这个查询字段不会在 Pothos 的类型系统中显式声明。

3. 显式包含机制：includeTypes 选项提供了一种绕过自动修剪逻辑的方法，确保指定的类型一定会出现在生成的子图中。

最佳实践

在使用这个功能时，建议：

1. 只包含确实需要的类型，避免不必要的类型污染子图
2. 为每个显式包含的类型添加清晰的注释，说明为什么需要包含它
3. 在团队文档中记录这些特殊处理，方便后续维护

总结

Pothos GraphQL 的 includeTypes 选项为联邦架构开发提供了更大的灵活性，使我们能够精确控制哪些类型出现在子图中。这个功能特别适合以下场景：

• 需要为联邦实体添加扩展字段
• 构建多联邦图架构
• 需要确保某些类型在子图间共享

通过合理使用这个功能，我们可以构建出既符合联邦规范又满足业务需求的 GraphQL 架构。