graphQL 自定义指令（Directives）

GraphQL 内置指令

GraphQL 中内置了两款逻辑指令，指令跟在字段名后使用。

@include

当条件成立时，查询此字段

query {
    search {
        actors @include(if: $queryActor) {
            name
        }
    }
}

@skip

当条件成立时，不查询此字段

query {
    search {
        comments @skip(if: $noComments) {
            from
        }
    }
}

今天要给大家介绍的是如何自定义指令（Directives）
实际用起来会像是下图所示

directive @isAuthenticated on FIELD_DEFINITION | OBJECT
directive @length(max: Int) on FIELD_DEFINITION | INPUT_FIELD_DEFINITION
directive @date(defaultFormat: String = "yyyy--MM-dd ") on FIELD_DEFINITION

type ExampleType @isAuthenticated {
  newField: String
  oldField: String @deprecated(reason: "use newField.")
  mobilePhoneNumber: String @length(max: 11)
  date: String @date
}

Directives 帮你实现TypeSystem做不到的细节
Directives 可视为GraphQL 的一种语法蜜糖(sugar syntax)，通常用于调整query 及schema 的行为，不同场景下可以有以下功能：

影响query原有行为，如@include, @skip为query增加条件判断
为Schema加上描述性标签，如@deprecated可以用于废除schema的某field又避免breaking change
为Schema 添加新功能，例如参数检查、简单计算、权限检查、错误处理等等。不过这部分较为复杂，需自行定义

Directives 可以用在Client Side 的query 也可以用于Server Side 的Schema Definition ，不过通常比较多用于Schema Definition 中，一方面比较好维护，另一方面也减轻Client 的计算负担。

冷知识：通常在query使用的使用的Directives称为Executable Directive (或称Query Directive) ，在Schema中使用的称为Type System Directive (Schema Directive)。

1. 客户端 query + directives

GraphQL 在query side 原生支援的Executable Directive 有两个，分别为：

@include (if: Boolean!): 用于判断是否显示此field，若if 为true 则显示。可用于field 及fragment 展开。
@skip (if: Boolean!): 用于判断是否忽略此field，若if 为false 则显示。可用于field 及fragment 展开。

2. 服务端 schema definition + directives

前面提到Directives 可以为Schema 添加描述性标签或是添加新功能(或是两者兼具)，所以我们先从添加描述性标签开始，介绍一下同样也是GraphQL 原生支持的Type System Directive @deprecated(reason: String = "No longer supported")

2.1 使用Type System Directives 标示Deprecated 范例

今天公司觉得某些男性/女性使用者并不喜欢透露自己的体重，所以决定废除这个栏位，但直接拿掉又怕系统出现问题，所以决定先dreprecate 掉，所以让我们修改Schema:

type User {
  ...
  "体重"
  weight(unit: WeightUnit = KILOGRAM): Float @deprecated (reason: "It's secret")
}

不过需注意，deprecated不代表说Client Side不能query，而是Client Side在阅读documentation时，会发现此field已经deprecated ，进而减少使用或修正目前的使用
如图所示，只要Server的Schema与Resolver并未移除掉该field ，User.weight仍然能取得值，只是在documentation中会将User.weight归类为Deprecated

image.png

3 服务端 schema definition + 自定义 Directives

举一个简单的例子，实作一个@uppper的Directives让回传的String都以大写形式呈现，我们需要做的有：

引入外部套件

const { SchemaDirectiveVistor } = require('apollo-server');
const { defaultFieldResolver } = require('graphql');

新增一个继承SchemaDirectiveVistor的class UpperCaseDirective来实作此Directive (可视为Directive的Resolver) ，再来通过override SchemaDirectiveVistor里的相关function来做出想要的效果。

这边@upper只针对栏位，因此只需要实作visitFieldDefinition。

将步骤2新增的class放入ApolloServer初始化的参数列在option添加新栏位schemaDirectives来将以上两者连接。
在Schema中( gqltag里)定义新的Directivesdirective @upper on FIELD_DEFINITION

代码如下：

// 1. 引入外部套件
const { ApolloServer, gql, SchemaDirectiveVisitor } = require('apollo-server');
const { defaultFieldResolver } = require('graphql');

// 2. Directive 實作
class UpperCaseDirective extends SchemaDirectiveVisitor {
  // 2-1. ovveride field Definition 的實作
  visitFieldDefinition(field) {
    const { resolve = defaultFieldResolver } = field;
    // 2-2. 更改 field 的 resolve function
    field.resolve = async function(...args) {
      // 2-3. 取得原先 field resolver 的計算結果 (因為 field resolver 傳回來的有可能是 promise 故使用 await)
      const result = await resolve.apply(this, args);
      // 2-4. 將得到的結果再做預期的計算 (toUpperCase)
      if (typeof result === 'string') {
        return result.toUpperCase();
      }
      // 2-5. 回傳最終值 (給前端)
      return result;
    };
  }
}

// 3. 定義新的 Directive
const typeDefs = gql`
  directive @upper on FIELD_DEFINITION

  type Query {
    hello: String @upper
  }
`;

// Provide resolver functions for your schema fields
const resolvers = {
  Query: {
    hello: (root, args, context) => {
      return 'Hello world!';
    }
  }
};

// 4. Add directive to the ApolloServer constructor
const server = new ApolloServer({
  typeDefs,
  resolvers,
  // 4. 將 schema 的 directive 與實作連接並傳進 ApolloServer。
  schemaDirectives: {
    upper: UpperCaseDirective
  }
});

server.listen().then(({ url }) => {
  console.log(`? Server ready at ${url}`);
});

这边特别解释一下因为UpperCaseDirective在宣告时( directive @upper on FIELD_DEFINITION)只应用于FIELD_DEFINITION，所以我们只需要override visitFieldDefinition一项，若想知道其他Type要override的function的话，可见Apollo官方提供的API如以下程式码：

class SomeDirective extends SchemaDirectiveVisitor {
  visitSchema(schema: GraphQLSchema) {}

  visitObject(object: GraphQLObjectType) {}

  visitFieldDefinition(field: GraphQLField<any, any>) {}

  visitArgumentDefinition(argument: GraphQLArgument) {}

  visitInterface(iface: GraphQLInterfaceType) {}

  visitInputObject(object: GraphQLInputObjectType) {}

  visitInputFieldDefinition(field: GraphQLInputField) {}

  visitScalar(scalar: GraphQLScalarType) {}

  visitUnion(union: GraphQLUnionType) {}

  visitEnum(type: GraphQLEnumType) {}

  visitEnumValue(value: GraphQLEnumValue) {}
}

更多范例可以上Apollo Server 2 - Implementing directives上查询，另外很多directive的实作都可以找到套件只要下载来传入ApolloServer就ok了！

他强大的地方还有可以做ACL (Access Control List)也就是权限管理，比如今天Query的me的资料只能给有登入的使用而不开放给没有登入的guest，或是me.age只能给朋友看到，甚至是只有管理者( Admin可以删除使用者)

type User {
  ...
  @friendOnly
  age
}

Query {
  @isAuthenticated
  me: User
}

type Mutation {
  @auth(requires: "ADMIN")
  deleteUser(id: ID!): User
}

让我们来用之前社交软体的例子来试试看@isAuthenticated吧!

4. @isAuthenticated 实现

一样分为两部分： Schema与Resovler ( IsAuthenticatedDirectiveclass)

4.1 @isAuthenticated- Schema Definition

Schema部分非常简单，而我们目前仅用于FIELD_DEFINITION上~

directive @isAuthenticated on FIELD_DEFINITION

type Query {
  me: User @isAuthenticated
}

4.2 @isAuthenticated- Resolver

class IsAuthenticatedDirective extends SchemaDirectiveVisitor {
  visitFieldDefinition(field) {
    const { resolve = defaultFieldResolver } = field;
    field.resolve = async function(...args) {
      const context = args[2];
      // 检查有沒有 context.me
      if (!context.me) throw new ForbiddenError('Not logged in~.');

      // 确定有 context.me 后才进入 Resolve Function
      const result = await resolve.apply(this, args);
      return result;
    };
  }
}

const resolvers = {
  Query: {
    // 这里被纯做资料存取逻辑
    me: (root, args, { me, userModel }) => userModel.findUserByUserId(me.id),
    ...
  }
}

const server = new ApolloServer({
  typeDefs,
  resolvers,
  schemaDirectives: {
    // 一样要记得放入 ApolloServer 中
    isAuthenticated: IsAuthenticatedDirective
  }
});

虽然Directive 功能强大，但目前Directive 的应用还不算广且还有许多改进空间(实作难度偏高)，所以可以审视自身需求来判断是否真的要新增一个Directive

Reference: