Mercurius项目中的GraphQL自定义指令开发指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00070/article/details/148863956

Mercurius项目中的GraphQL自定义指令开发指南

mercurius Implement GraphQL servers and gateways with Fastify 项目地址: https://gitcode.com/gh_mirrors/me/mercurius

什么是GraphQL自定义指令

在GraphQL开发中，自定义指令(Directive)是一种强大的元编程工具，它允许开发者通过声明式的方式修改GraphQL查询的执行行为或Schema定义。Mercurius作为Fastify生态中的GraphQL适配器，提供了完善的自定义指令支持。

自定义指令的核心组成

一个完整的自定义指令实现包含两个关键部分：

Schema定义：在GraphQL Schema中声明指令的签名和使用位置
转换器(Transformer)：实现指令的具体逻辑，修改字段解析行为

实战案例：数据脱敏指令

让我们通过一个实际案例来理解如何创建自定义指令。我们将实现一个@redact指令，用于对敏感信息如电话号码和邮箱进行脱敏处理。

1. Schema定义

首先定义Schema，声明我们的自定义指令：

directive @redact(find: String) on FIELD_DEFINITION

type Document {
  excerpt: String! @redact(find: "email")
  text: String! @redact(find: "phone")
}

type Query {
  documents: [Document] 
}

这里我们：

使用directive关键字定义指令
@redact是指令名称
find是指令参数，用于指定脱敏类型
on FIELD_DEFINITION指定该指令可用于字段定义

2. 实现转换器

转换器是自定义指令的核心，它负责修改字段的解析行为：

const { mapSchema, getDirective, MapperKind } = require("@graphql-tools/utils");

// 定义正则表达式匹配规则
const PHONE_REGEXP = /(?:\+?\d{2}[ -]?\d{3}[ -]?\d{5}|\d{4})/g;
const EMAIL_REGEXP = /([^\s@])+@[^\s@]+\.[^\s@]+/g;

const redactionSchemaTransformer = schema => 
  mapSchema(schema, {
    [MapperKind.FIELD]: fieldConfig => {
      const redactDirective = getDirective(schema, fieldConfig, "redact")?.[0];
      if (redactDirective) {
        const { find } = redactDirective;
        fieldConfig.resolve = async (obj, _args, _ctx, info) => {
          const value = obj[info.fieldName];
          switch (find) {
            case "email":
              return value.replace(EMAIL_REGEXP, "****@*****.***");
            case "phone":
              return value.replace(PHONE_REGEXP, m => "*".repeat(m.length));
            default:
              return value;
          }
        };
      }
    },
  });

关键点解析：

mapSchema函数遍历Schema中的所有字段定义
getDirective检查字段是否应用了指定指令
我们重写了字段的resolve函数，实现自定义解析逻辑
info参数包含当前字段的元信息，如字段名、返回类型等

3. 创建可执行Schema

将自定义指令应用到Schema中：

const executableSchema = makeExecutableSchema({
  typeDefs: schema,
  resolvers,
});

const newSchema = redactionSchemaTransformer(executableSchema);

4. 注册到Mercurius

最后将转换后的Schema注册到Mercurius：

app.register(mercurius, {
  schema: newSchema,
  graphiql: true,
});

联邦架构中的自定义指令

在GraphQL联邦架构中，自定义指令的实现略有不同，因为需要处理联邦特有的语法和指令。

联邦架构实现步骤

构建联邦Schema：使用buildFederationSchema处理联邦特有语法
生成可执行Schema：合并联邦Schema和自定义解析器
应用转换器：通过schemaTransforms选项应用自定义指令

const federationSchema = buildFederationSchema(schema);

const executableSchema = makeExecutableSchema({
  typeDefs: printSchemaWithDirectives(federationSchema),
  resolvers: mergeResolvers([
    getResolversFromSchema(federationSchema),
    resolvers,
  ]),
});

app.register(mercurius, {
  schema: executableSchema,
  schemaTransforms: [uppercaseTransformer],
  graphiql: true,
});