NestJS 中文文档

主题

联邦 ​

联邦提供了一种将你的单体 GraphQL 服务器拆分为独立微服务的方式。它由两个组件组成：一个网关和一个或多个联邦微服务。每个微服务持有 schema 的一部分，网关将 schema 合并为一个可以被客户端使用的单一 schema。

引用 Apollo 文档，联邦的设计遵循以下核心原则：

  • 构建图应该是声明式的。 使用联邦，你可以在 schema 内部声明式地组合图，而不是编写命令式的 schema 拼接代码。
  • 代码应该按关注点分离，而不是按类型。通常没有单个团队控制像 User 或 Product 这样的重要类型的每个方面，因此这些类型的定义应该分布在团队和代码库中，而不是集中在一起。
  • 图对于客户端来说应该是简单易用的。联邦服务可以共同形成一个完整的、以产品为中心的图，准确反映客户端如何使用它。
  • 它就是 GraphQL，只使用语言的符合规范的特性。任何语言，不仅仅是 JavaScript，都可以实现联邦。

警告

联邦目前不支持订阅。

在接下来的部分中，我们将设置一个演示应用程序，它由一个网关和两个联邦端点组成：用户服务和文章服务。

使用 Apollo 的联邦 ​

首先安装所需的依赖：

bash
$ npm install --save @apollo/subgraph

Schema 优先 ​

"用户服务"提供了一个简单的 schema。注意 @key 指令：它指示 Apollo 查询规划器，如果你指定了 id，就可以获取 User 的特定实例。另外，注意我们 extend 了 Query 类型。

graphql
type User @key(fields: "id") {
  id: ID!
  name: String!
}

extend type Query {
  getUser(id: ID!): User
}

解析器提供了一个名为 resolveReference() 的额外方法。每当 Apollo Gateway 需要一个 User 实例的相关资源时，就会触发此方法。我们稍后会在文章服务中看到一个示例。请注意，该方法必须使用 @ResolveReference() 装饰器进行注解。

typescript
import { Args, Query, Resolver, ResolveReference } from '@nestjs/graphql';
import { UsersService } from './users.service';

@Resolver('User')
export class UsersResolver {
  constructor(private usersService: UsersService) {}

  @Query()
  getUser(@Args('id') id: string) {
    return this.usersService.findById(id);
  }

  @ResolveReference()
  resolveReference(reference: { __typename: string; id: string }) {
    return this.usersService.findById(reference.id);
  }
}

最后，我们通过在配置对象中传入 ApolloFederationDriver 驱动来注册 GraphQLModule：

typescript
import {
  ApolloFederationDriver,
  ApolloFederationDriverConfig,
} from '@nestjs/apollo';
import { Module } from '@nestjs/common';
import { GraphQLModule } from '@nestjs/graphql';
import { UsersResolver } from './users.resolver';

@Module({
  imports: [
    GraphQLModule.forRoot<ApolloFederationDriverConfig>({
      driver: ApolloFederationDriver,
      typePaths: ['**/*.graphql'],
    }),
  ],
  providers: [UsersResolver],
})
export class AppModule {}

代码优先 ​

首先，向 User 实体添加一些额外的装饰器。

ts
import { Directive, Field, ID, ObjectType } from '@nestjs/graphql';

@ObjectType()
@Directive('@key(fields: "id")')
export class User {
  @Field(() => ID)
  id: number;

  @Field()
  name: string;
}

解析器提供了一个名为 resolveReference() 的额外方法。每当 Apollo Gateway 需要一个 User 实例的相关资源时，就会触发此方法。我们稍后会在文章服务中看到一个示例。请注意，该方法必须使用 @ResolveReference() 装饰器进行注解。

ts
import { Args, Query, Resolver, ResolveReference } from '@nestjs/graphql';
import { User } from './user.entity';
import { UsersService } from './users.service';

@Resolver(() => User)
export class UsersResolver {
  constructor(private usersService: UsersService) {}

  @Query(() => User)
  getUser(@Args('id') id: number): User {
    return this.usersService.findById(id);
  }

  @ResolveReference()
  resolveReference(reference: { __typename: string; id: number }): User {
    return this.usersService.findById(reference.id);
  }
}

最后，我们通过在配置对象中传入 ApolloFederationDriver 驱动来注册 GraphQLModule：

typescript
import {
  ApolloFederationDriver,
  ApolloFederationDriverConfig,
} from '@nestjs/apollo';
import { Module } from '@nestjs/common';
import { UsersResolver } from './users.resolver';
import { UsersService } from './users.service'; // Not included in this example

@Module({
  imports: [
    GraphQLModule.forRoot<ApolloFederationDriverConfig>({
      driver: ApolloFederationDriver,
      autoSchemaFile: true,
    }),
  ],
  providers: [UsersResolver, UsersService],
})
export class AppModule {}

可以在这里找到代码优先模式的工作示例，在这里找到 schema 优先模式的工作示例。

联邦示例：文章 ​

文章服务应该通过 getPosts 查询提供聚合的文章，同时还要用 user.posts 字段扩展我们的 User 类型。

Schema 优先 ​

"文章服务"在其 schema 中通过 extend 关键字引用 User 类型。它还在 User 类型上声明了一个额外的属性（posts）。注意用于匹配 User 实例的 @key 指令，以及表示 id 字段在其他地方管理的 @external 指令。

graphql
type Post @key(fields: "id") {
  id: ID!
  title: String!
  body: String!
  user: User
}

extend type User @key(fields: "id") {
  id: ID! @external
  posts: [Post]
}

extend type Query {
  getPosts: [Post]
}

在下面的示例中，PostsResolver 提供了 getUser() 方法，该方法返回一个包含 __typename 和一些你的应用程序可能需要用来解析引用的额外属性的引用，在本例中是 id。__typename 被 GraphQL Gateway 用来定位负责 User 类型的微服务并检索相应的实例。上面描述的"用户服务"将在执行 resolveReference() 方法时被请求。

typescript
import { Query, Resolver, Parent, ResolveField } from '@nestjs/graphql';
import { PostsService } from './posts.service';
import { Post } from './posts.interfaces';

@Resolver('Post')
export class PostsResolver {
  constructor(private postsService: PostsService) {}

  @Query('getPosts')
  getPosts() {
    return this.postsService.findAll();
  }

  @ResolveField('user')
  getUser(@Parent() post: Post) {
    return { __typename: 'User', id: post.userId };
  }
}

最后，我们必须注册 GraphQLModule，类似于我们在"用户服务"部分所做的。

typescript
import {
  ApolloFederationDriver,
  ApolloFederationDriverConfig,
} from '@nestjs/apollo';
import { Module } from '@nestjs/common';
import { GraphQLModule } from '@nestjs/graphql';
import { PostsResolver } from './posts.resolver';

@Module({
  imports: [
    GraphQLModule.forRoot<ApolloFederationDriverConfig>({
      driver: ApolloFederationDriver,
      typePaths: ['**/*.graphql'],
    }),
  ],
  providers: [PostsResolvers],
})
export class AppModule {}

代码优先 ​

首先，我们需要声明一个表示 User 实体的类。虽然该实体本身存在于另一个服务中，但我们将在这里使用它（扩展其定义）。注意 @extends 和 @external 指令。

ts
import { Directive, ObjectType, Field, ID } from '@nestjs/graphql';
import { Post } from './post.entity';

@ObjectType()
@Directive('@extends')
@Directive('@key(fields: "id")')
export class User {
  @Field(() => ID)
  @Directive('@external')
  id: number;

  @Field(() => [Post])
  posts?: Post[];
}

现在让我们为 User 实体的扩展创建相应的解析器，如下所示：

ts
import { Parent, ResolveField, Resolver } from '@nestjs/graphql';
import { PostsService } from './posts.service';
import { Post } from './post.entity';
import { User } from './user.entity';

@Resolver(() => User)
export class UsersResolver {
  constructor(private readonly postsService: PostsService) {}

  @ResolveField(() => [Post])
  public posts(@Parent() user: User): Post[] {
    return this.postsService.forAuthor(user.id);
  }
}

我们还需要定义 Post 实体类：

ts
import { Directive, Field, ID, Int, ObjectType } from '@nestjs/graphql';
import { User } from './user.entity';

@ObjectType()
@Directive('@key(fields: "id")')
export class Post {
  @Field(() => ID)
  id: number;

  @Field()
  title: string;

  @Field(() => Int)
  authorId: number;

  @Field(() => User)
  user?: User;
}

以及它的解析器：

ts
import { Query, Args, ResolveField, Resolver, Parent } from '@nestjs/graphql';
import { PostsService } from './posts.service';
import { Post } from './post.entity';
import { User } from './user.entity';

@Resolver(() => Post)
export class PostsResolver {
  constructor(private readonly postsService: PostsService) {}

  @Query(() => Post)
  findPost(@Args('id') id: number): Post {
    return this.postsService.findOne(id);
  }

  @Query(() => [Post])
  getPosts(): Post[] {
    return this.postsService.all();
  }

  @ResolveField(() => User)
  user(@Parent() post: Post): any {
    return { __typename: 'User', id: post.authorId };
  }
}

最后，在模块中将它们连接在一起。注意 schema 构建选项，我们在其中指定 User 是一个孤立（外部）类型。

ts
import {
  ApolloFederationDriver,
  ApolloFederationDriverConfig,
} from '@nestjs/apollo';
import { Module } from '@nestjs/common';
import { User } from './user.entity';
import { PostsResolvers } from './posts.resolvers';
import { UsersResolvers } from './users.resolvers';
import { PostsService } from './posts.service'; // Not included in example

@Module({
  imports: [
    GraphQLModule.forRoot<ApolloFederationDriverConfig>({
      driver: ApolloFederationDriver,
      autoSchemaFile: true,
      buildSchemaOptions: {
        orphanedTypes: [User],
      },
    }),
  ],
  providers: [PostsResolver, UsersResolver, PostsService],
})
export class AppModule {}

可以在这里找到代码优先模式的工作示例，在这里找到 schema 优先模式的工作示例。

联邦示例：网关 ​

首先安装所需的依赖：

bash
$ npm install --save @apollo/gateway

网关需要指定端点列表，它将自动发现相应的 schema。因此，网关服务的实现对于代码优先和 schema 优先方式都是相同的。

typescript
import { IntrospectAndCompose } from '@apollo/gateway';
import { ApolloGatewayDriver, ApolloGatewayDriverConfig } from '@nestjs/apollo';
import { Module } from '@nestjs/common';
import { GraphQLModule } from '@nestjs/graphql';

@Module({
  imports: [
    GraphQLModule.forRoot<ApolloGatewayDriverConfig>({
      driver: ApolloGatewayDriver,
      server: {
        // ... Apollo server options
        cors: true,
      },
      gateway: {
        supergraphSdl: new IntrospectAndCompose({
          subgraphs: [
            { name: 'users', url: 'http://user-service/graphql' },
            { name: 'posts', url: 'http://post-service/graphql' },
          ],
        }),
      },
    }),
  ],
})
export class AppModule {}

可以在这里找到代码优先模式的工作示例，在这里找到 schema 优先模式的工作示例。

使用 Mercurius 的联邦 ​

首先安装所需的依赖：

bash
$ npm install --save @apollo/subgraph @nestjs/mercurius

提示

@apollo/subgraph 包是构建子图 schema 所必需的（buildSubgraphSchema、printSubgraphSchema 函数）。

Schema 优先 ​

"用户服务"提供了一个简单的 schema。注意 @key 指令：它指示 Mercurius 查询规划器，如果你指定了 id，就可以获取 User 的特定实例。另外，注意我们 extend 了 Query 类型。

graphql
type User @key(fields: "id") {
  id: ID!
  name: String!
}

extend type Query {
  getUser(id: ID!): User
}

解析器提供了一个名为 resolveReference() 的额外方法。每当 Mercurius Gateway 需要一个 User 实例的相关资源时，就会触发此方法。我们稍后会在文章服务中看到一个示例。请注意，该方法必须使用 @ResolveReference() 装饰器进行注解。

typescript
import { Args, Query, Resolver, ResolveReference } from '@nestjs/graphql';
import { UsersService } from './users.service';

@Resolver('User')
export class UsersResolver {
  constructor(private usersService: UsersService) {}

  @Query()
  getUser(@Args('id') id: string) {
    return this.usersService.findById(id);
  }

  @ResolveReference()
  resolveReference(reference: { __typename: string; id: string }) {
    return this.usersService.findById(reference.id);
  }
}

最后，我们通过在配置对象中传入 MercuriusFederationDriver 驱动来注册 GraphQLModule：

typescript
import {
  MercuriusFederationDriver,
  MercuriusFederationDriverConfig,
} from '@nestjs/mercurius';
import { Module } from '@nestjs/common';
import { GraphQLModule } from '@nestjs/graphql';
import { UsersResolver } from './users.resolver';

@Module({
  imports: [
    GraphQLModule.forRoot<MercuriusFederationDriverConfig>({
      driver: MercuriusFederationDriver,
      typePaths: ['**/*.graphql'],
      federationMetadata: true,
    }),
  ],
  providers: [UsersResolver],
})
export class AppModule {}

代码优先 ​

首先，向 User 实体添加一些额外的装饰器。

ts
import { Directive, Field, ID, ObjectType } from '@nestjs/graphql';

@ObjectType()
@Directive('@key(fields: "id")')
export class User {
  @Field(() => ID)
  id: number;

  @Field()
  name: string;
}

解析器提供了一个名为 resolveReference() 的额外方法。每当 Mercurius Gateway 需要一个 User 实例的相关资源时，就会触发此方法。我们稍后会在文章服务中看到一个示例。请注意，该方法必须使用 @ResolveReference() 装饰器进行注解。

ts
import { Args, Query, Resolver, ResolveReference } from '@nestjs/graphql';
import { User } from './user.entity';
import { UsersService } from './users.service';

@Resolver(() => User)
export class UsersResolver {
  constructor(private usersService: UsersService) {}

  @Query(() => User)
  getUser(@Args('id') id: number): User {
    return this.usersService.findById(id);
  }

  @ResolveReference()
  resolveReference(reference: { __typename: string; id: number }): User {
    return this.usersService.findById(reference.id);
  }
}

最后，我们通过在配置对象中传入 MercuriusFederationDriver 驱动来注册 GraphQLModule：

typescript
import {
  MercuriusFederationDriver,
  MercuriusFederationDriverConfig,
} from '@nestjs/mercurius';
import { Module } from '@nestjs/common';
import { UsersResolver } from './users.resolver';
import { UsersService } from './users.service'; // Not included in this example

@Module({
  imports: [
    GraphQLModule.forRoot<MercuriusFederationDriverConfig>({
      driver: MercuriusFederationDriver,
      autoSchemaFile: true,
      federationMetadata: true,
    }),
  ],
  providers: [UsersResolver, UsersService],
})
export class AppModule {}

联邦示例：文章 ​

文章服务应该通过 getPosts 查询提供聚合的文章，同时还要用 user.posts 字段扩展我们的 User 类型。

Schema 优先 ​

"文章服务"在其 schema 中通过 extend 关键字引用 User 类型。它还在 User 类型上声明了一个额外的属性（posts）。注意用于匹配 User 实例的 @key 指令，以及表示 id 字段在其他地方管理的 @external 指令。

graphql
type Post @key(fields: "id") {
  id: ID!
  title: String!
  body: String!
  user: User
}

extend type User @key(fields: "id") {
  id: ID! @external
  posts: [Post]
}

extend type Query {
  getPosts: [Post]
}

在下面的示例中，PostsResolver 提供了 getUser() 方法，该方法返回一个包含 __typename 和一些你的应用程序可能需要用来解析引用的额外属性的引用，在本例中是 id。__typename 被 GraphQL Gateway 用来定位负责 User 类型的微服务并检索相应的实例。上面描述的"用户服务"将在执行 resolveReference() 方法时被请求。

typescript
import { Query, Resolver, Parent, ResolveField } from '@nestjs/graphql';
import { PostsService } from './posts.service';
import { Post } from './posts.interfaces';

@Resolver('Post')
export class PostsResolver {
  constructor(private postsService: PostsService) {}

  @Query('getPosts')
  getPosts() {
    return this.postsService.findAll();
  }

  @ResolveField('user')
  getUser(@Parent() post: Post) {
    return { __typename: 'User', id: post.userId };
  }
}

最后，我们必须注册 GraphQLModule，类似于我们在"用户服务"部分所做的。

typescript
import {
  MercuriusFederationDriver,
  MercuriusFederationDriverConfig,
} from '@nestjs/mercurius';
import { Module } from '@nestjs/common';
import { GraphQLModule } from '@nestjs/graphql';
import { PostsResolver } from './posts.resolver';

@Module({
  imports: [
    GraphQLModule.forRoot<MercuriusFederationDriverConfig>({
      driver: MercuriusFederationDriver,
      federationMetadata: true,
      typePaths: ['**/*.graphql'],
    }),
  ],
  providers: [PostsResolvers],
})
export class AppModule {}

代码优先 ​

首先，我们需要声明一个表示 User 实体的类。虽然该实体本身存在于另一个服务中，但我们将在这里使用它（扩展其定义）。注意 @extends 和 @external 指令。

ts
import { Directive, ObjectType, Field, ID } from '@nestjs/graphql';
import { Post } from './post.entity';

@ObjectType()
@Directive('@extends')
@Directive('@key(fields: "id")')
export class User {
  @Field(() => ID)
  @Directive('@external')
  id: number;

  @Field(() => [Post])
  posts?: Post[];
}

现在让我们为 User 实体的扩展创建相应的解析器，如下所示：

ts
import { Parent, ResolveField, Resolver } from '@nestjs/graphql';
import { PostsService } from './posts.service';
import { Post } from './post.entity';
import { User } from './user.entity';

@Resolver(() => User)
export class UsersResolver {
  constructor(private readonly postsService: PostsService) {}

  @ResolveField(() => [Post])
  public posts(@Parent() user: User): Post[] {
    return this.postsService.forAuthor(user.id);
  }
}

我们还需要定义 Post 实体类：

ts
import { Directive, Field, ID, Int, ObjectType } from '@nestjs/graphql';
import { User } from './user.entity';

@ObjectType()
@Directive('@key(fields: "id")')
export class Post {
  @Field(() => ID)
  id: number;

  @Field()
  title: string;

  @Field(() => Int)
  authorId: number;

  @Field(() => User)
  user?: User;
}

以及它的解析器：

ts
import { Query, Args, ResolveField, Resolver, Parent } from '@nestjs/graphql';
import { PostsService } from './posts.service';
import { Post } from './post.entity';
import { User } from './user.entity';

@Resolver(() => Post)
export class PostsResolver {
  constructor(private readonly postsService: PostsService) {}

  @Query(() => Post)
  findPost(@Args('id') id: number): Post {
    return this.postsService.findOne(id);
  }

  @Query(() => [Post])
  getPosts(): Post[] {
    return this.postsService.all();
  }

  @ResolveField(() => User)
  user(@Parent() post: Post): any {
    return { __typename: 'User', id: post.authorId };
  }
}

最后，在模块中将它们连接在一起。注意 schema 构建选项，我们在其中指定 User 是一个孤立（外部）类型。

ts
import {
  MercuriusFederationDriver,
  MercuriusFederationDriverConfig,
} from '@nestjs/mercurius';
import { Module } from '@nestjs/common';
import { User } from './user.entity';
import { PostsResolvers } from './posts.resolvers';
import { UsersResolvers } from './users.resolvers';
import { PostsService } from './posts.service'; // Not included in example

@Module({
  imports: [
    GraphQLModule.forRoot<MercuriusFederationDriverConfig>({
      driver: MercuriusFederationDriver,
      autoSchemaFile: true,
      federationMetadata: true,
      buildSchemaOptions: {
        orphanedTypes: [User],
      },
    }),
  ],
  providers: [PostsResolver, UsersResolver, PostsService],
})
export class AppModule {}

联邦示例：网关 ​

网关需要指定端点列表，它将自动发现相应的 schema。因此，网关服务的实现对于代码优先和 schema 优先方式都是相同的。

typescript
import {
  MercuriusGatewayDriver,
  MercuriusGatewayDriverConfig,
} from '@nestjs/mercurius';
import { Module } from '@nestjs/common';
import { GraphQLModule } from '@nestjs/graphql';

@Module({
  imports: [
    GraphQLModule.forRoot<MercuriusGatewayDriverConfig>({
      driver: MercuriusGatewayDriver,
      gateway: {
        services: [
          { name: 'users', url: 'http://user-service/graphql' },
          { name: 'posts', url: 'http://post-service/graphql' },
        ],
      },
    }),
  ],
})
export class AppModule {}

Federation 2 ​

引用 Apollo 文档，Federation 2 改善了原始 Apollo Federation（在本文档中称为 Federation 1）的开发者体验，它与大多数原始超级图向后兼容。

警告

Mercurius 不完全支持 Federation 2。你可以在这里查看支持 Federation 2 的库列表。

在接下来的部分中，我们将把前面的示例升级到 Federation 2。

联邦示例：用户 ​

Federation 2 的一个变化是实体没有原始子图，因此我们不再需要扩展 Query。更多详情请参阅 Apollo Federation 2 文档中的实体主题。

Schema 优先 ​

我们可以简单地从 schema 中删除 extend 关键字。

graphql
type User @key(fields: "id") {
  id: ID!
  name: String!
}

type Query {
  getUser(id: ID!): User
}

代码优先 ​

要使用 Federation 2，我们需要在 autoSchemaFile 选项中指定联邦版本。

ts
import {
  ApolloFederationDriver,
  ApolloFederationDriverConfig,
} from '@nestjs/apollo';
import { Module } from '@nestjs/common';
import { UsersResolver } from './users.resolver';
import { UsersService } from './users.service'; // Not included in this example

@Module({
  imports: [
    GraphQLModule.forRoot<ApolloFederationDriverConfig>({
      driver: ApolloFederationDriver,
      autoSchemaFile: {
        federation: 2,
      },
    }),
  ],
  providers: [UsersResolver, UsersService],
})
export class AppModule {}

联邦示例：文章 ​

出于与上面相同的原因，我们不再需要扩展 User 和 Query。

Schema 优先 ​

我们可以简单地从 schema 中删除 extend 和 external 指令。

graphql
type Post @key(fields: "id") {
  id: ID!
  title: String!
  body: String!
  user: User
}

type User @key(fields: "id") {
  id: ID!
  posts: [Post]
}

type Query {
  getPosts: [Post]
}

代码优先 ​

由于我们不再扩展 User 实体，我们可以简单地从 User 中删除 extends 和 external 指令。

ts
import { Directive, ObjectType, Field, ID } from '@nestjs/graphql';
import { Post } from './post.entity';

@ObjectType()
@Directive('@key(fields: "id")')
export class User {
  @Field(() => ID)
  id: number;

  @Field(() => [Post])
  posts?: Post[];
}

同样，与用户服务类似，我们需要在 GraphQLModule 中指定使用 Federation 2。

ts
import {
  ApolloFederationDriver,
  ApolloFederationDriverConfig,
} from '@nestjs/apollo';
import { Module } from '@nestjs/common';
import { User } from './user.entity';
import { PostsResolvers } from './posts.resolvers';
import { UsersResolvers } from './users.resolvers';
import { PostsService } from './posts.service'; // Not included in example

@Module({
  imports: [
    GraphQLModule.forRoot<ApolloFederationDriverConfig>({
      driver: ApolloFederationDriver,
      autoSchemaFile: {
        federation: 2,
      },
      buildSchemaOptions: {
        orphanedTypes: [User],
      },
    }),
  ],
  providers: [PostsResolver, UsersResolver, PostsService],
})
export class AppModule {}

基于 NestJS 官方文档翻译

Copyright © 2024-present