Tận dụng sức mạnh của TypeScript & GraphQL

GraphQL là một ngôn ngữ truy vấn (query language) mạnh mẽ cho API và là một runtime để thực thi các truy vấn đó dựa trên dữ liệu sẵn có của bạn. Đây là một cách tiếp cận thanh thoát, giải quyết được nhiều vấn đề thường gặp với REST API. Để có thêm bối cảnh, bạn nên đọc bài so sánh này giữa GraphQL và REST. GraphQL kết hợp với TypeScript giúp bạn phát triển với type safety tốt hơn cho các GraphQL query, mang lại kiểm tra kiểu dữ liệu xuyên suốt từ đầu đến cuối (end-to-end typing).

Trong chương này, chúng ta giả định bạn đã hiểu cơ bản về GraphQL, và tập trung vào cách làm việc với module @nestjs/graphql có sẵn. GraphQLModule có thể được cấu hình để dùng Apollo server (thông qua driver @nestjs/apollo) hoặc Mercurius (thông qua @nestjs/mercurius). Chúng tôi cung cấp tích hợp chính thức cho các package GraphQL đã được kiểm chứng này để bạn dùng GraphQL với Nest một cách đơn giản (xem thêm các tích hợp khác tại đây).

Bạn cũng có thể tự xây dựng driver riêng cho mình (đọc thêm tại đây).

Cài đặt

Bắt đầu bằng việc cài các package cần thiết:

# Dành cho Express và Apollo (mặc định)
$ npm i @nestjs/graphql @nestjs/apollo @apollo/server @as-integrations/express5 graphql

# Dành cho Fastify và Apollo
# npm i @nestjs/graphql @nestjs/apollo @apollo/server @as-integrations/fastify graphql

# Dành cho Fastify và Mercurius
# npm i @nestjs/graphql @nestjs/mercurius graphql mercurius

Tổng quan

Nest cung cấp hai cách để xây dựng ứng dụng GraphQL: code first và schema first. Bạn nên chọn cách phù hợp nhất với mình. Hầu hết các chương trong phần GraphQL này đều chia làm hai phần chính: một phần dành cho ai theo code first, phần còn lại dành cho ai theo schema first.

Trong cách tiếp cận code first, bạn dùng decorator và class TypeScript để tạo ra schema GraphQL tương ứng. Cách này hữu ích nếu bạn muốn làm việc hoàn toàn với TypeScript và tránh phải chuyển đổi qua lại giữa các cú pháp ngôn ngữ khác nhau.

Trong cách tiếp cận schema first, nguồn chân lý (source of truth) là các file GraphQL SDL (Schema Definition Language). SDL là một cách viết schema độc lập với ngôn ngữ, dùng để chia sẻ file schema giữa các nền tảng khác nhau. Nest sẽ tự động sinh ra các định nghĩa TypeScript (dùng class hoặc interface) dựa trên schema GraphQL để giảm bớt việc phải viết code khung (boilerplate) trùng lặp.

Bắt đầu với GraphQL & TypeScript

Sau khi cài xong các package, chúng ta có thể import GraphQLModule và cấu hình nó bằng static method forRoot().

import { Module } from '@nestjs/common';
import { GraphQLModule } from '@nestjs/graphql';
import { ApolloDriver, ApolloDriverConfig } from '@nestjs/apollo';

@Module({
  imports: [
    GraphQLModule.forRoot<ApolloDriverConfig>({
      driver: ApolloDriver,
    }),
  ],
})
export class AppModule {}

Method forRoot() nhận một object options làm tham số. Các option này được truyền thẳng xuống instance driver bên dưới (đọc thêm về các cấu hình khả dụng tại đây: Apollo và Mercurius). Ví dụ, nếu bạn muốn tắt GraphQL IDE, truyền các option sau:

import { Module } from '@nestjs/common';
import { GraphQLModule } from '@nestjs/graphql';
import { ApolloDriver, ApolloDriverConfig } from '@nestjs/apollo';

@Module({
  imports: [
    GraphQLModule.forRoot<ApolloDriverConfig>({
      driver: ApolloDriver,
      graphiql: false,
    }),
  ],
})
export class AppModule {}

Trong trường hợp này, các option sẽ được chuyển tiếp đến constructor của ApolloServer.

Truy cập đối tượng request và response

Một option driver đáng chú ý là context, một factory dùng để xây dựng ngữ cảnh thực thi (execution context) GraphQL cho mỗi request. Dùng option này để đưa các đối tượng request và response gốc vào resolver:

GraphQLModule.forRoot<ApolloDriverConfig>({
  driver: ApolloDriver,
  context: ({ req, res }) => ({ req, res }),
}),

Với cấu hình này, bạn có thể đọc chúng trong resolver thông qua decorator @Context():

@Query(() => String)
userAgent(@Context('req') req: Request): string {
  return req.headers['user-agent'] ?? '';
}

GraphQL IDE

GraphiQL là IDE GraphQL đồ họa, tương tác, chạy ngay trên trình duyệt, được phục vụ mặc định trên cùng URL với GraphQL server. Để truy cập, bạn cần có một GraphQL server cơ bản đã được cấu hình và đang chạy. Để xem ngay, bạn có thể cài đặt và build ví dụ mẫu tại đây. Ngoài ra, nếu bạn đang theo các ví dụ code trong tài liệu này, sau khi hoàn thành các bước ở chương Resolver, bạn có thể truy cập GraphiQL.

Khi đã có cấu hình trên, và ứng dụng của bạn đang chạy nền, bạn có thể mở trình duyệt và truy cập http://localhost:3000/graphql (host và port có thể khác tùy cấu hình của bạn). Bạn sẽ thấy GraphiQL như hình dưới đây.

Bật và tắt GraphiQL

Kể từ @nestjs/graphql v14, GraphiQL là IDE GraphQL duy nhất — graphql-playground cũ đã bị loại bỏ hoàn toàn. GraphiQL được tự động bật bất cứ khi nào NODE_ENV khác production, nên trong môi trường development bạn có nó mà không cần cấu hình gì thêm, còn trong production thì landing page mặc định bị tắt.

Để kiểm soát rõ ràng, dùng option graphiql:

GraphQLModule.forRoot<ApolloDriverConfig>({
  driver: ApolloDriver,
  graphiql: true, // ép bật, kể cả trong production
}),

GraphQLModule.forRoot<ApolloDriverConfig>({
  driver: ApolloDriver,
  graphiql: false, // tắt hoàn toàn landing page
}),

Cấu hình GraphiQL

Truyền một object thay vì boolean để vừa bật GraphiQL vừa cấu hình nó:

GraphQLModule.forRoot<ApolloDriverConfig>({
  driver: ApolloDriver,
  graphiql: {
    url: '/graphql',
    headers: {
      authorization: 'Bearer <token>',
    },
    shouldPersistHeaders: true,
    isHeadersEditorEnabled: true,
    inputValueDeprecation: false,
  },
}),

Các option khả dụng gồm:

Subscription trong IDE

Nếu ứng dụng của bạn dùng subscription, hãy dùng graphql-ws. Việc hỗ trợ subscriptions-transport-ws đã bị loại bỏ — nó không còn được chấp nhận như một key subscriptions và package này cũng không còn là dependency nữa:

GraphQLModule.forRoot<ApolloDriverConfig>({
  driver: ApolloDriver,
  subscriptions: {
    'graphql-ws': true,
  },
}),

Với cấu hình này, GraphiQL có thể thực thi trực tiếp các operation subscription lên server của bạn.

Code first

Trong cách tiếp cận code first, bạn dùng decorator và class TypeScript để tạo ra schema GraphQL tương ứng.

Để dùng cách tiếp cận code first, bắt đầu bằng cách thêm property autoSchemaFile vào object options:

GraphQLModule.forRoot<ApolloDriverConfig>({
  driver: ApolloDriver,
  autoSchemaFile: join(process.cwd(), 'src/schema.gql'),
}),

Giá trị của property autoSchemaFile là đường dẫn nơi schema tự động sinh ra sẽ được tạo. Ngoài ra, schema cũng có thể được sinh ngay trong bộ nhớ (in memory). Để bật tính năng này, set property autoSchemaFile thành true:

GraphQLModule.forRoot<ApolloDriverConfig>({
  driver: ApolloDriver,
  autoSchemaFile: true,
}),

Mặc định, các type trong schema sinh ra sẽ theo đúng thứ tự chúng được định nghĩa trong các module được include. Để sắp xếp schema theo thứ tự bảng chữ cái (lexicographically), set property sortSchema thành true:

GraphQLModule.forRoot<ApolloDriverConfig>({
  driver: ApolloDriver,
  autoSchemaFile: join(process.cwd(), 'src/schema.gql'),
  sortSchema: true,
}),

Ví dụ

Một ví dụ code first đầy đủ có tại đây.

Schema first

Để dùng cách tiếp cận schema first, bắt đầu bằng cách thêm property typePaths vào object options. Property typePaths cho biết GraphQLModule nên tìm các file định nghĩa schema GraphQL SDL mà bạn sẽ viết ở đâu. Các file này sẽ được gộp lại trong bộ nhớ; điều này cho phép bạn chia schema thành nhiều file và đặt chúng gần resolver tương ứng.

GraphQLModule.forRoot<ApolloDriverConfig>({
  driver: ApolloDriver,
  typePaths: ['./**/*.graphql'],
}),

Thông thường bạn cũng cần có các định nghĩa TypeScript (class và interface) tương ứng với các type trong GraphQL SDL. Việc tự tay viết các định nghĩa TypeScript tương ứng vừa dư thừa vừa tốn công. Nó cũng khiến chúng ta không còn một nguồn chân lý duy nhất – mỗi thay đổi trong SDL đều buộc ta phải chỉnh lại định nghĩa TypeScript. Để giải quyết vấn đề này, package @nestjs/graphql có thể tự động sinh định nghĩa TypeScript từ cây cú pháp trừu tượng (AST). Để bật tính năng này, thêm property options definitions khi cấu hình GraphQLModule.

GraphQLModule.forRoot<ApolloDriverConfig>({
  driver: ApolloDriver,
  typePaths: ['./**/*.graphql'],
  definitions: {
    path: join(process.cwd(), 'src/graphql.ts'),
  },
}),

Property path trong object definitions cho biết nơi lưu output TypeScript được sinh ra. Mặc định, tất cả các type TypeScript được sinh ra đều là interface. Để sinh ra class thay vì interface, chỉ định property outputAs với giá trị 'class'.

GraphQLModule.forRoot<ApolloDriverConfig>({
  driver: ApolloDriver,
  typePaths: ['./**/*.graphql'],
  definitions: {
    path: join(process.cwd(), 'src/graphql.ts'),
    outputAs: 'class',
  },
}),

Cách trên sẽ sinh động (dynamically) các định nghĩa TypeScript mỗi khi ứng dụng khởi động. Ngoài ra, bạn cũng có thể muốn viết một script đơn giản để sinh chúng theo yêu cầu. Ví dụ, giả sử ta tạo script sau với tên generate-typings.ts:

import { GraphQLDefinitionsFactory } from '@nestjs/graphql';
import { join } from 'node:path';

const definitionsFactory = new GraphQLDefinitionsFactory();
definitionsFactory.generate({
  typePaths: ['./src/**/*.graphql'],
  path: join(process.cwd(), 'src/graphql.ts'),
  outputAs: 'class',
});

Giờ bạn có thể chạy script này theo yêu cầu:

$ ts-node generate-typings

Để bật chế độ watch cho script (tự động sinh typings mỗi khi có file .graphql thay đổi), truyền option watch vào method generate().

definitionsFactory.generate({
  typePaths: ['./src/**/*.graphql'],
  path: join(process.cwd(), 'src/graphql.ts'),
  outputAs: 'class',
  watch: true,
});

Để tự động sinh thêm field __typename cho mỗi object type, bật option emitTypenameField:

definitionsFactory.generate({
  // ...
  emitTypenameField: true,
});

Để sinh resolver (query, mutation, subscription) dưới dạng field thuần không có argument, bật option skipResolverArgs:

definitionsFactory.generate({
  // ...
  skipResolverArgs: true,
});

Để sinh enum dưới dạng TypeScript union type thay vì enum TypeScript thông thường, set option enumsAsTypes thành true:

definitionsFactory.generate({
  // ...
  enumsAsTypes: true,
});

Apollo Sandbox

Để dùng Apollo Sandbox thay vì GraphiQL làm IDE GraphQL cho phát triển local, dùng cấu hình sau:

import { ApolloDriver, ApolloDriverConfig } from '@nestjs/apollo';
import { Module } from '@nestjs/common';
import { GraphQLModule } from '@nestjs/graphql';
import { ApolloServerPluginLandingPageLocalDefault } from '@apollo/server/plugin/landingPage/default';

@Module({
  imports: [
    GraphQLModule.forRoot<ApolloDriverConfig>({
      driver: ApolloDriver,
      graphiql: false,
      plugins: [ApolloServerPluginLandingPageLocalDefault()],
    }),
  ],
})
export class AppModule {}

Ví dụ

Một ví dụ schema first đầy đủ có tại đây.

Truy cập schema đã được sinh ra

Trong một số trường hợp (ví dụ như test end-to-end), bạn có thể muốn lấy tham chiếu tới object schema đã được sinh ra. Trong test end-to-end, bạn có thể chạy query bằng object graphql mà không cần dùng bất kỳ HTTP listener nào.

Bạn có thể truy cập schema đã sinh (dù theo cách code first hay schema first), bằng class GraphQLSchemaHost:

const { schema } = app.get(GraphQLSchemaHost);

Cấu hình bất đồng bộ

Khi bạn cần truyền option module một cách bất đồng bộ thay vì tĩnh, dùng method forRootAsync(). Cũng như hầu hết các dynamic module khác, Nest cung cấp nhiều kỹ thuật để xử lý cấu hình bất đồng bộ.

Một kỹ thuật là dùng factory function:

 GraphQLModule.forRootAsync<ApolloDriverConfig>({
  driver: ApolloDriver,
  useFactory: () => ({
    typePaths: ['./**/*.graphql'],
  }),
}),

Cũng như các factory provider khác, factory function của chúng ta có thể là bất đồng bộ (async) và có thể inject dependency thông qua inject.

GraphQLModule.forRootAsync<ApolloDriverConfig>({
  driver: ApolloDriver,
  imports: [ConfigModule],
  useFactory: async (configService: ConfigService) => ({
    typePaths: configService.get<string>('GRAPHQL_TYPE_PATHS'),
  }),
  inject: [ConfigService],
}),

Ngoài ra, bạn cũng có thể cấu hình GraphQLModule bằng một class thay vì factory, như dưới đây:

GraphQLModule.forRootAsync<ApolloDriverConfig>({
  driver: ApolloDriver,
  useClass: GqlConfigService,
}),

Cách viết trên sẽ khởi tạo GqlConfigService bên trong GraphQLModule, dùng nó để tạo ra object options. Lưu ý rằng trong ví dụ này, GqlConfigService phải implement interface GqlOptionsFactory, như dưới đây. GraphQLModule sẽ gọi method createGqlOptions() trên instance của class được cung cấp.

@Injectable()
class GqlConfigService implements GqlOptionsFactory {
  createGqlOptions(): ApolloDriverConfig {
    return {
      typePaths: ['./**/*.graphql'],
    };
  }
}

Nếu bạn muốn tái sử dụng một options provider đã có sẵn thay vì tạo một bản riêng bên trong GraphQLModule, dùng cú pháp useExisting.

GraphQLModule.forRootAsync<ApolloDriverConfig>({
  imports: [ConfigModule],
  useExisting: ConfigService,
}),

Tích hợp Mercurius

Thay vì dùng Apollo, người dùng Fastify (đọc thêm tại đây) có thể dùng driver @nestjs/mercurius thay thế.

import { Module } from '@nestjs/common';
import { GraphQLModule } from '@nestjs/graphql';
import { MercuriusDriver, MercuriusDriverConfig } from '@nestjs/mercurius';

@Module({
  imports: [
    GraphQLModule.forRoot<MercuriusDriverConfig>({
      driver: MercuriusDriver,
      graphiql: true,
    }),
  ],
})
export class AppModule {}

Method forRoot() nhận một object options làm tham số. Các option này được truyền thẳng xuống instance driver bên dưới. Đọc thêm về các cấu hình khả dụng tại đây.

Nhiều endpoint

Một tính năng hữu ích khác của module @nestjs/graphql là khả năng phục vụ nhiều endpoint cùng lúc. Điều này cho phép bạn quyết định module nào sẽ được đưa vào endpoint nào. Mặc định, GraphQL sẽ tìm resolver trên toàn bộ ứng dụng. Để giới hạn việc quét chỉ trong một tập con module, dùng property include.

GraphQLModule.forRoot({
  include: [CatsModule],
}),

Trong cách tiếp cận code first, option include chỉ quyết định module nào được quét để tìm resolver. Các type được decorate bằng @ObjectType(), @InputType(), @InterfaceType(), @ArgsType(), hoặc được đăng ký qua registerEnumType() / createUnionType() vẫn sẽ xuất hiện trong mọi schema được sinh ra. Để giới hạn một type vào một module cụ thể, dùng option registerIn:

@ObjectType({ registerIn: () => CatsModule })
export class Cat {
  @Field()
  name: string;
}

Giờ đây, khi schema được build với include: [CatsModule], chỉ những type được gán cho CatsModule mới trở thành một phần của nó, còn các type được gán cho module khác sẽ bị bỏ qua. Các type không có registerIn vẫn giữ hành vi mặc định và có mặt trong mọi schema có tham chiếu tới chúng.

Option registerIn khả dụng trên @InputType(), @InterfaceType(), và @ArgsType(), cũng như registerEnumType() và createUnionType():

@InputType({ registerIn: () => CatsModule })
export class CreateCatInput {
  @Field()
  name: string;
}

registerEnumType(CatBreed, {
  name: 'CatBreed',
  registerIn: () => CatsModule,
});

export const CatsUnion = createUnionType({
  name: 'CatsUnion',
  types: () => [Lion, Tiger] as const,
  registerIn: () => CatsModule,
});

Tích hợp bên thứ ba

• GraphQL Yoga

Ví dụ

Một ví dụ hoạt động đầy đủ có tại đây.