Directives

Một directive có thể được gắn vào một field hoặc một fragment inclusion, và có thể ảnh hưởng đến việc thực thi query theo bất kỳ cách nào mà server mong muốn (đọc thêm tại đây). Đặc tả GraphQL cung cấp sẵn vài directive mặc định:

• @include(if: Boolean) - chỉ đưa field này vào kết quả nếu argument là true
• @skip(if: Boolean) - bỏ qua field này nếu argument là true
• @deprecated(reason: String) - đánh dấu field là deprecated kèm thông điệp giải thích

Một directive là một định danh đứng sau ký tự @, có thể theo sau bởi một danh sách named argument, và có thể xuất hiện sau hầu như bất kỳ phần tử nào trong ngôn ngữ query và schema của GraphQL.

Custom directives

Để chỉ định điều gì sẽ xảy ra khi Apollo/Mercurius gặp directive của bạn, bạn có thể tạo một transformer function. Function này dùng hàm mapSchema để duyệt qua các vị trí trong schema (định nghĩa field, định nghĩa type, v.v.) và thực hiện các phép biến đổi tương ứng.

import { getDirective, MapperKind, mapSchema } from '@graphql-tools/utils';
import { defaultFieldResolver, GraphQLSchema } from 'graphql';

export function upperDirectiveTransformer(
  schema: GraphQLSchema,
  directiveName: string,
) {
  return mapSchema(schema, {
    [MapperKind.OBJECT_FIELD]: (fieldConfig) => {
      const upperDirective = getDirective(
        schema,
        fieldConfig,
        directiveName,
      )?.[0];

      if (upperDirective) {
        const { resolve = defaultFieldResolver } = fieldConfig;

        // Thay thế resolver gốc bằng một function mà *trước tiên* gọi
        // resolver gốc, sau đó chuyển kết quả của nó sang chữ hoa
        fieldConfig.resolve = async function (source, args, context, info) {
          const result = await resolve(source, args, context, info);
          if (typeof result === 'string') {
            return result.toUpperCase();
          }
          return result;
        };
        return fieldConfig;
      }
    },
  });
}

Bây giờ, áp dụng function transform upperDirectiveTransformer trong phương thức GraphQLModule#forRoot bằng hàm transformSchema:

GraphQLModule.forRoot({
  // ...
  transformSchema: (schema) => upperDirectiveTransformer(schema, 'upper'),
});

Sau khi đăng ký, directive @upper có thể được sử dụng trong schema của chúng ta. Tuy nhiên, cách bạn áp dụng directive sẽ khác nhau tùy theo cách tiếp cận bạn dùng (code first hay schema first).

Code first

Trong cách tiếp cận code first, dùng decorator @Directive() để áp dụng directive.

@Directive('@upper')
@Field()
title: string;

Directive có thể được áp dụng trên field, field resolver, input type và object type, cũng như trên query, mutation, và subscription. Dưới đây là ví dụ directive được áp dụng ở cấp query handler:

@Directive('@deprecated(reason: "This query will be removed in the next version")')
@Query(() => Author, { name: 'author' })
async getAuthor(@Args({ name: 'id', type: () => Int }) id: number) {
  return this.authorsService.findOneById(id);
}

Cuối cùng, đảm bảo khai báo các directive trong GraphQLModule, như sau:

GraphQLModule.forRoot({
  // ...,
  transformSchema: schema => upperDirectiveTransformer(schema, 'upper'),
  buildSchemaOptions: {
    directives: [
      new GraphQLDirective({
        name: 'upper',
        locations: [DirectiveLocation.FIELD_DEFINITION],
      }),
    ],
  },
}),

Schema first

Trong cách tiếp cận schema first, áp dụng directive trực tiếp trong SDL.

directive @upper on FIELD_DEFINITION

type Post {
  id: Int!
  title: String! @upper
  votes: Int
}