## 指令 一個指令可以被附加在一個字段或對象片段上，并能按照服務器所希望的任何方式影響查詢語句的執行(參見[此處](https://graphql.org/learn/queries/#directives))。GraphQL 規范中提供了幾個默認的指令： - `@include(if: Boolean)` - 僅在參數為真時，才在結果中包含此字段 - `@skip(if: Boolean)` - 參數為真時，跳過此字段 - `@deprecated(reason: String)` - 標記此字段為已棄用，并附上原因 指令其實就是一個帶有 `@` 符號前綴的標識符，可選項為后面緊跟著的命名參數列表，它可以出現在 GraphQL 查詢和模式語言中的幾乎任何元素之后。 ### 自定義指令 要指示當 Apollo/Mercurius 遇到您的指令時應該發生什么，您可以創建一個轉換器函數。 此函數使用 mapSchema 函數遍歷架構中的位置（字段定義、類型定義等）并執行相應的轉換。 ~~~typescript 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; // Replace the original resolver with a function that *first* calls // the original resolver, then converts its result to upper case 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; } }, }); } ~~~ 現在，使用 `transformSchema` 函數在 `GraphQLModule#forRoot` 方法中應用 `upperDirectiveTransformer` 轉換函數： ~~~typescript GraphQLModule.forRoot({ // ... transformSchema: (schema) => upperDirectiveTransformer(schema, 'upper'), }); ~~~ 一旦注冊，`@upper` 指令就可以在我們的模式中使用。 但是，您應用指令的方式將根據您使用的方法（代碼優先或模式優先）而有所不同。 ### 代碼優先 在代碼優先方式中，使用 `@Directive()` 裝飾器來應用指令。 ```typescript @Directive('@upper') @Field() title: string; ``` > `@Directive()` 裝飾器是從 `@nestjs/graphql` 包里導出的。 指令可以被應用在字段、字段解析器、輸入和對象類型上，同樣也可以應用在查詢、變更和訂閱上。這里有一個將指令應用于查詢處理層的例子： ```typescript @Directive('@deprecated(reason: "This query will be removed in the next version")') @Query(returns => Author, { name: 'author' }) async getAuthor(@Args({ name: 'id', type: () => Int }) id: number) { return this.authorsService.findOneById(id); } ``` 通過 `@Directive()` 裝飾器所應用的指令，將不會被映射在生成的模式定義文件中。 最后，確保在 GraphQLModule 中聲明指令，如下所示： ~~~typescript GraphQLModule.forRoot({ // ..., transformSchema: schema => upperDirectiveTransformer(schema, 'upper'), buildSchemaOptions: { directives: [ new GraphQLDirective({ name: 'upper', locations: [DirectiveLocation.FIELD_DEFINITION], }), ], }, }), ~~~ `GraphQLDirective` 和 `DirectiveLocation` 都是從 `graphql` 包中導出的。 ### 架構優先 在架構優先方式中，直接在 SDL 中應用指令。 ```graphql directive @upper on FIELD_DEFINITION type Post { id: Int! title: String! @upper votes: Int } ```