GraphQL报错Field can only be defined once 双subgraph调用buildFederatedSchema求解

错误原因 #

你遇到的Field can only be defined once报错核心是buildFederatedSchema的使用逻辑错误：

• buildFederatedSchema是子图（subgraph）侧的工具函数，作用是给单个子图的schema添加联邦规范支持，每个子图仅需要在自己的服务内调用一次，生成自己的独立schema即可。
• 你在网关侧两次调用该函数、传入两个子图的类型定义合并，相当于把两个子图的所有类型、字段放在同一个schema内重复定义，自然触发重复声明错误。

解决步骤 #

步骤1：调整子图侧配置 #

保持template和fileserver两个子图为独立运行的服务，各自在自己的代码中调用buildFederatedSchema生成自身的schema，分别绑定不同的端口启动，先单独验证两个子图的查询功能正常。

步骤2：调整网关侧配置 #

网关侧不需要使用buildFederatedSchema，改用@apollo/gateway提供的网关能力，自动拉取、合并多个子图的schema，参考代码如下：

// 网关侧代码示例
const { ApolloServer } = require('@apollo/server');
const { ApolloGateway } = require('@apollo/gateway');
const { startStandaloneServer } = require('@apollo/server/standalone');

// 配置子图服务列表
const gateway = new ApolloGateway({
  serviceList: [
    { name: 'template', url: 'http://localhost:<template子图端口>/graphql' },
    { name: 'fileserver', url: 'http://localhost:<fileserver子图端口>/graphql' },
  ],
});

const server = new ApolloServer({ gateway });

// 启动网关服务
startStandaloneServer({ server, port: 4000 }).then(({ url }) => {
  console.log(`联邦网关已启动，访问地址：${url}`);
});

额外检查项 #

如果调整后仍然报错，检查两个子图的类型定义：

• 确认跨子图共享的实体类型都添加了@key注解声明实体主键，符合联邦实体规范
• 确认没有在两个子图中定义同名、且不属于联邦实体的普通类型，这类重复声明的普通类型也会触发报错，可以将公共类型抽离为共享 schema 片段统一引入，避免重复定义。

内容的提问来源于stack exchange，提问作者Generic Technology