使用 Apollo Server 实现 subgraph

本文演示了如何使用Node.js和子图（subgraph）和Apollo Server创建一个超级图（supergraph）

若要使用不同的语言和/或框架创建子图，请参阅联邦兼容子图实现列表。注意，并非所有列出的库都支持所有联邦功能。

定义子图

要成为超级图的一部分，子图必须符合Apollo Federation子图规范，该规范可向您的图路由器以及Apollo Studio等工具暴露子图的特性。

将现有的单体图转换为单个子图是构建联邦超级图的一个方便的第一步。首先，以下是一个非联邦 Apollo Server的设置：

index.ts

1
import { ApolloServer } from '@apollo/server';
2
import { startStandaloneServer } from '@apollo/server/standalone';
3
import gql from 'graphql-tag';
4

5
const typeDefs = gql`
6
  type Query {
7
    me: User
8
  }
9

10
  type User {
11
    id: ID!
12
    username: String
13
  }
14
`;
15

16
const resolvers = {
17
  Query: {
18
    me() {
19
      return { id: '1', username: '@ava' };
20
    },
21
  },
22
};
23

24
const server = new ApolloServer({
25
  typeDefs,
26
  resolvers,
27
});
28

29
// Note the top-level await!
30
const { url } = await startStandaloneServer(server);
31
console.log(`🚀  Server ready at ${url}`);

index.js

1
import { ApolloServer } from '@apollo/server';
2
import { startStandaloneServer } from '@apollo/server/standalone';
3
import gql from 'graphql-tag';
4

5
const typeDefs = gql`
6
  type Query {
7
    me: User
8
  }
9

10
  type User {
11
    id: ID!
12
    username: String
13
  }
14
`;
15

16
const resolvers = {
17
  Query: {
18
    me() {
19
      return { id: '1', username: '@ava' };
20
    },
21
  },
22
};
23

24
const server = new ApolloServer({
25
  typeDefs,
26
  resolvers,
27
});
28

29
// Note the top-level await!
30
const { url } = await startStandaloneServer(server);
31
console.log(`🚀  Server ready at ${url}`);

上面，我们把我们的模式用gql 标签来自 graphql-tag 包，将我们的 schema 转换为 AST（即 DocumentNode）。虽然 Apollo Server 可以接受一个 string（或者 DocumentNode）作为它的 typeDefs，下面的 buildSubgraphSchema 函数需要我们传递的 schema 是一个 DocumentNode。

如果你之前已经设置过 Apollo Server，这应该看起来很熟悉。如果你还没有，我们在开始联邦之前推荐你先熟悉一下基础知识。

现在，让我们将其转换为 subgraph！

1. 安装并导入 `@apollo/subgraph`

第一步是在服务器项目中安装 @apollo/subgraph@apollo/subgraph 包：

1
npm install @apollo/subgraph

我们还需要在这个文件中引入 buildSubgraphSchemabuildSubgraphSchema 函数（我们稍后会用到）在初始化 ApolloServerApolloServer 的文件中：

index.ts

1
import { buildSubgraphSchema } from '@apollo/subgraph';

index.js

1
import { buildSubgraphSchema } from '@apollo/subgraph';

2. 集成 Federation 2

为了使 subgraph 使用 Federation 2 的新功能，它的 schema 需要包含以下 extend schemaextend schema 定义：

1
import gql from 'graphql-tag';
2

3
const typeDefs = gql`
4
  # highlight-start
5
  extend schema @link(url: "https://specs.apollo.dev/federation/v2.0", import: ["@key", "@shareable"])
6
  # highlight-end
7

8
  type Query {
9
    me: User
10
  }
11

12
  type User {
13
    id: ID!
14
    username: String
15
  }
16
`;

1
import gql from 'graphql-tag';
2

3
const typeDefs = gql`
4
  extend schema @link(url: "https://specs.apollo.dev/federation/v2.0", import: ["@key", "@shareable"])
5

6
  type Query {
7
    me: User
8
  }
9

10
  type User {
11
    id: ID!
12
    username: String
13
  }
14
`;

这个定义使得 schema 能够使用 Federation 2 功能。没有它，Federation 2 的 composition 会假定 subgraph 使用 Federation 1，这会为了向后兼容而设置一些默认值。

当你开始使用更多与 federation 相关的指令（超出 @key 和 @shareable），你需要在上述的 import 数组中添加这些 directives。

3. 定义实体

实体在 subgraph 中不是必需的，但它们是联邦 supergraph 的核心构建块，所以练习定义它们是有好处的。

作为我们的联邦架构的一部分，我们希望其他 subgraph 能够向 User 类型贡献 fields。为了启用此功能，我们在 User 类型的定义中添加 @key directive，将其指定为 entity：

index.ts

1
const typeDefs = gql`
2
  extend schema @link(url: "https://specs.apollo.dev/federation/v2.0", import: ["@key", "@shareable"])
3

4
  type Query {
5
    me: User
6
  }
7

8
  type User
9
    @key(fields: "id") { # highlight-line
10
    id: ID!
11
    username: String
12
  }
13
`;

index.js

1
const typeDefs = gql`
2
  extend schema @link(url: "https://specs.apollo.dev/federation/v2.0", import: ["@key", "@shareable"])
3

4
  type Query {
5
    me: User
6
  }
7

8
  type User
9
    @key(fields: "id") { 
10
    id: ID!
11
    username: String
12
  }
13
`;

该@key 指令告知网关哪个字段能够唯一标识User 实体的特定实例。在这种情况下，网关可以使用单个id。

接下来，我们为User 实体添加一个引用解析器。一个引用解析器告诉网关如何通过它的@key 字段来获取实体：

index.ts

1
const resolvers = {
2
  Query: {
3
    me() {
4
      return { id: '1', username: '@ava' };
5
    },
6
  },
7
  User: {
8
    __resolveReference(user, { fetchUserById }) {
9
      return fetchUserById(user.id);
10
    },
11
  },
12
};

index.js

1
const resolvers = {
2
  Query: {
3
    me() {
4
      return { id: '1', username: '@ava' };
5
    },
6
  },
7
  User: {
8
    __resolveReference(user, { fetchUserById }) {
9
      return fetchUserById(user.id);
10
    },
11
  },
12
};

（此示例需要定义fetchUserById函数以从我们的后端数据存储中获取适当的User。）

了解更多关于实体信息。

4. 生成子图模式

最后，我们使用来自@apollo/subgraph包的buildSubgraphSchema函数来添加对联盟支持的增强到我们的模式定义中。我们向ApolloServer构造函数提供此函数的结果：

index.ts

1
const server = new ApolloServer({
2
  schema: buildSubgraphSchema({ typeDefs, resolvers }),
3
});
4

5
// Note the top level await!
6
const { url } = await startStandaloneServer(server);
7
console.log(`🚀  Server ready at ${url}`);

index.js

1
const server = new ApolloServer({
2
  schema: buildSubgraphSchema({ typeDefs, resolvers }),
3
});
4

5
// Note the top level await!
6
const { url } = await startStandaloneServer(server);
7
console.log(`🚀  Server ready at ${url}`);

服务器现在已准备好作为一个联邦图中的子图执行！

综合示例

以下是上述代码片段的合并（请注意，为了使此示例完整，您必须为您的数据源定义fetchUserById函数）：

index.ts

1
import { ApolloServer } from '@apollo/server';
2
import { startStandaloneServer } from '@apollo/server/standalone';
3
import gql from 'graphql-tag';
4
import { buildSubgraphSchema } from '@apollo/subgraph';
5

6
const typeDefs = gql`
7
  extend schema @link(url: "https://specs.apollo.dev/federation/v2.0", import: ["@key", "@shareable"])
8

9
  type Query {
10
    me: User
11
  }
12

13
  type User @key(fields: "id") {
14
    id: ID!
15
    username: String
16
  }
17
`;
18

19
const resolvers = {
20
  Query: {
21
    me() {
22
      return { id: '1', username: '@ava' };
23
    },
24
  },
25
  User: {
26
    __resolveReference(user, { fetchUserById }) {
27
      return fetchUserById(user.id);
28
    },
29
  },
30
};
31

32
const server = new ApolloServer({
33
  schema: buildSubgraphSchema({ typeDefs, resolvers }),
34
});
35

36
const { url } = await startStandaloneServer(server);
37
console.log(`🚀  Server ready at ${url}`);

index.js

1
import { ApolloServer } from '@apollo/server';
2
import { startStandaloneServer } from '@apollo/server/standalone';
3
import gql from 'graphql-tag';
4
import { buildSubgraphSchema } from '@apollo/subgraph';
5

6
const typeDefs = gql`
7
  extend schema @link(url: "https://specs.apollo.dev/federation/v2.0", import: ["@key", "@shareable"])
8

9
  type Query {
10
    me: User
11
  }
12

13
  type User @key(fields: "id") {
14
    id: ID!
15
    username: String
16
  }
17
`;
18

19
const resolvers = {
20
  Query: {
21
    me() {
22
      return { id: '1', username: '@ava' };
23
    },
24
  },
25
  User: {
26
    __resolveReference(user, { fetchUserById }) {
27
      return fetchUserById(user.id);
28
    },
29
  },
30
};
31

32
const server = new ApolloServer({
33
  schema: buildSubgraphSchema({ typeDefs, resolvers }),
34
});
35

36
const { url } = await startStandaloneServer(server);
37
console.log(`🚀  Server ready at ${url}`);

自定义指令

请参阅有关子图中自定义指令的信息子图中的自定义指令。

事件参考

@apollo/subgraph参考

使用 Apollo Server 实现 subgraph

定义子图

1. 安装并导入 @apollo/subgraph

2. 集成 Federation 2

3. 定义实体

4. 生成子图模式

综合示例

自定义指令

1. 安装并导入 `@apollo/subgraph`