logologo
文档仓库
文档仓库
logologo
开始

概述

第一步
控制器
提供者
模块
中间件
异常过滤器
管道
守卫
拦截器
自定义装饰器

基础

自定义提供程序
异步提供者
动态模块
注入作用域
循环依赖
模块引用
懒加载模块
执行上下文
生命周期事件
发现服务
平台无关
单元测试

技术

配置
SQL
Mongo
验证
缓存
序列化
版本控制
任务调度
队列
日志
Cookies
事件
压缩
文件上传
文件流
HTTP 模块
Session
MVC
性能(Fastify)
SSE

安全

认证
授权
加密与哈希
Helmet
CORS
CSRF
速率限制

GraphQL

快速开始
解析器
变更
订阅
标量
指令
接口
联合与枚举
字段中间件
类型映射
插件
复杂度
扩展
CLI 插件
生成SDL
共享模型
其他功能
联邦

WebSocket

网关
异常过滤器
管道
守卫
拦截器
适配器

微服务

基础
Redis
MQTT
NATS
RabbitMQ
Kafka
gRPC
自定义传输
异常过滤器
管道
守卫
拦截器
部署
独立应用程序

CLI

概述
工作区
库
用法
脚本

OpenAPI

介绍
装饰器
类型映射
操作
其他特性
安全
类型与参数
CLI 插件

实用示例

REPL
CRUD生成器
SWC
Passport(认证)
热重载
MikroORM
TypeORM
Mongoose
Sequelize
路由模块
Swagger
健康检查
CQRS
Compodoc
Prisma
Sentry
静态资源
Commander
异步本地存储
Necord
套件(原Automock)

常见问题

Serverless
HTTP 适配器
长连接
全局前缀
原始请求体
混合应用
HTTPS & 多服务器
请求生命周期
错误

开发工具

概述
CI/CD
迁移指南
API参考(官方)

生态与案例

谁在用
精彩资源

支持

支持

社区

贡献者

最后更新于: 2025/11/18 02:11:37

上一页标量
下一页接口

#指令

指令可以附加在字段或片段包含上,能够以服务器所需的任何方式影响查询的执行(了解更多此处 )。GraphQL 规范提供了几个默认指令:

  • @include(if: Boolean) - 仅当参数为 true 时,在结果中包含此字段
  • @skip(if: Boolean) - 当参数为 true 时跳过此字段
  • @deprecated(reason: String) - 通过消息将字段标记为已弃用

指令是一个以 @ 字符开头的标识符,后面可以跟随一组命名参数,它可以出现在 GraphQL 查询和模式语言中几乎任何元素之后。

#自定义指令

要指定当 Apollo/Mercurius 遇到您的指令时应执行的操作,您可以创建一个转换器函数。该函数使用 mapSchema 函数遍历模式中的位置(字段定义、类型定义等)并执行相应的转换。

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;
      }
    },
  });
}

现在,在 GraphQLModule#forRoot 方法中使用 transformSchema 函数应用 upperDirectiveTransformer 转换函数:

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

注册后,@upper 指令就可以在我们的模式中使用。不过,应用指令的方式会根据你采用的方法(代码优先或模式优先)而有所不同。

#代码优先

在代码优先方法中,使用 @Directive() 装饰器来应用指令。

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

@Directive() 装饰器是从 @nestjs/graphql 包中导出的。

指令可以应用于字段、字段解析器、输入和对象类型,以及查询、变更和订阅操作。以下是将指令应用于查询处理器层级的示例:

@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);
}
警告

通过 @Directive() 装饰器应用的指令不会反映在生成的模式定义文件中。

最后,请确保在 GraphQLModule 中声明指令,如下所示:

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

GraphQLDirective 和 DirectiveLocation 均从 graphql 包中导出。

#模式优先

在模式优先方法中,直接在 SDL 中应用指令。

directive @upper on FIELD_DEFINITION

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