NestJS 9 GraphQL 中文文档(五) - 标量

飞柳
338 阅读4分钟

GraphQL对象类型有名称和字段，但在某些时候这些字段必须解析为一些具体数据。这就是标量类型的用武之地：它们代表查询树的叶子（在此了解更多）。GraphQL包含以下默认的类型：Int、Float、String、Boolean以及ID。除了这些内置的类型，你可能还需要支持自定义原子数据类型（例如：Date）。

代码优先

代码优先方式附带五个标量，其中三个是现有GraphQL类型的简单别名。

  • ID（GraphQLID的别名）- 代表一个唯一标识，通常用来重新获取对象或作为缓存的键
  • Int（GraphQLInt的别名）- 有符号的32位整数
  • Float（GraphQLFloat的别名）- 有符号的双精度浮点数
  • GraphQLISODateTime - UTC的日期时间字符串（默认用于表示Date类型）
  • GraphQLTimestamp - 一个带有符号的整数，表示日期和时间为从UNIX纪元开始算起的毫秒数

GraphQLISODateTime（例如：2019-12-03T09:54:33Z）被默认用于表示Date类型。要用GraphQLTimestamp替代，可以像下面这样设置buildSchemaOpitons对象中的dataScalarMode为 'timestamp'：

GraphQLModule.forRoot({
  buildSchemaOptions: {
    dateScalarMode: 'timestamp',
  }
}),

同样的，GraphQLFloat被默认用于表示number类型。要使用GraphQLInt替代，可以像下面这样设置buildSchemaOptions中的numberScalarMode为 'integer'：

GraphQLModule.forRoot({
  buildSchemaOptions: {
    numberScalarMode: 'integer',
  }
}),

此外，你可以创建自定义标量。

覆盖默认标量

要为Date类型创建自定义实现，只需创建一个新类即可。

import { Scalar, CustomScalar } from '@nestjs/graphql';
import { Kind, ValueNode } from 'graphql';

@Scalar('Date', (type) => Date)
export class DateScalar implements CustomScalar<number, Date> {
  description = 'Date custom scalar type';

  parseValue(value: number): Date {
    return new Date(value); // value from the client
  }

  serialize(value: Date): number {
    return value.getTime(); // value sent to the client
  }

  parseLiteral(ast: ValueNode): Date {
    if (ast.kind === Kind.INT) {
      return new Date(ast.value);
    }
    return null;
  }
}

有了这个之后，再将DateScalar注册为提供者。

@Module({
  providers: [DateScalar],
})
export class CommonModule {}

现在我们可以在类中使用Date类型了。

@Field()
creationDate: Date;

导入自定义标量

要使用自定义标量，必须导入并注册为一个解析器。我们将使用graphql-type-json包进行演示。这个npm包定义了一个JSON GraphQL 标量类型。

从安装包开始：

$ npm i --save graphql-type-json

一旦包被安装好，我们就把自定义解析器传给forRoot() 方法：

import GraphQLJSON from 'graphql-type-json';

@Module({
  imports: [
    GraphQLModule.forRoot({
      resolvers: { JSON: GraphQLJSON },
    }),
  ],
})
export class AppModule {}

现在我们可以在类中使用JSON类型了。

@Field((type) => GraphQLJSON)
info: JSON;

这里有一套有用的标量，可以查看graphql-scalars包。

创建自定义标量

要定义自定义标量，需创建一个新的GraphQLScalarType 实例。接下来，我们将创建一个自定义UUID标量。

const regex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

function validate(uuid: unknown): string | never {
  if (typeof uuid !== "string" || !regex.test(uuid)) {
    throw new Error("invalid uuid");
  }
  return uuid;
}

export const CustomUuidScalar = new GraphQLScalarType({
  name: 'UUID',
  description: 'A simple UUID parser',
  serialize: (value) => validate(value),
  parseValue: (value) => validate(value),
  parseLiteral: (ast) => validate(ast.value)
})

然后我们把自定义解析器传给forRoot() 方法：

@Module({
  imports: [
    GraphQLModule.forRoot({
      resolvers: { UUID: CustomUuidScalar },
    }),
  ],
})
export class AppModule {}

现在我们就可以在类中使用UUID类型了。

@Field((type) => CustomUuidScalar)
uuid: string;

模式优先

要定义自定义标量（在此阅读更多关于标量的信息），需创建一个类型声明和一个特定的解析器。在这里（和官方文档一样），我们将使用graphql-type-json包来演示。这个npm包定义了一个JSON GraphQL 标量类型。

从安装包开始：

$ npm i --save graphql-type-json

一旦包被安装好，我们就把自定义解析器传给forRoot() 方法：

import GraphQLJSON from 'graphql-type-json';

@Module({
  imports: [
    GraphQLModule.forRoot({
      typePaths: ['./**/*.graphql'],
      resolvers: { JSON: GraphQLJSON },
    }),
  ],
})
export class AppModule {}

现在我们可以在类型定义中使用JSON标量了。

scalar JSON

type Foo {
  field: JSON
}

另一种定义标量类型的方法是创建一个简单的类。假设我们想要用Date类型增强我们的 schema。

import { Scalar, CustomScalar } from '@nestjs/graphql';
import { Kind, ValueNode } from 'graphql';

@Scalar('Date')
export class DateScalar implements CustomScalar<number, Date> {
  description = 'Date custom scalar type';

  parseValue(value: number): Date {
    return new Date(value); // value from the client
  }

  serialize(value: Date): number {
    return value.getTime(); // value sent to the client
  }

  parseLiteral(ast: ValueNode): Date {
    if (ast.kind === Kind.INT) {
      return new Date(ast.value);
    }
    return null;
  }
}

有了这些之后，我们就可以把DateScalar注册为一个提供者了。

@Module({
  providers: [DateScalar],
})
export class CommonModule {}

现在，我们就可以在类型定义中使用Date标量了。

scalar Date

默认情况下，所有标量生成的TypeScript定义是any - 这样不是特别安全的类型。但是，当你指定了如何生成类型时，你可以配置Nest按照你指定的方式为自定义标量生成类型：

import { GraphQLDefinitionsFactory } from '@nestjs/graphql';
import { join } from 'path';

const definitionsFactory = new GraphQLDefinitionsFactory();

definitionsFactory.generate({
  typePaths: ['./src/**/*.graphql'],
  path: join(process.cwd(), 'src/graphql.ts'),
  outputAs: 'class',
  defaultScalarType: 'unknown',
  customScalarTypeMapping: {
    DateTime: 'Date',
    BigNumber: '_BigNumber',
  },
  additionalHeader: "import _BigNumber from 'bignumber.js'",
});

提示
或者，你可以使用类型引用来替代，例如：DateTime: Date。在这个例子中，GraphQLDefinitionsFactory 将提取指定类型（Date.name）的属性名来生成 TS 定义。注意：需要为非内置类型（自定义类型）添加导入语句。

现在，给定以下GraphQL自定义标量类型：

scalar DateTime
scalar BigNumber
scalar Payload

我们将在src/graphql.ts中看到以下生成的TypeScript定义：

import _BigNumber from 'bignumber.js';

export type DateTime = Date;
export type BigNumber = _BigNumber;
export type Payload = unknown;

在这里，我们使用了customScalarTypeMapping属性，来提供我们希望为自定义标量声明的类型的映射。我们还提供了一个additionalHeader 属性，以便我们可以添加这些类型定义所需的任何导入。最后，我们添加了一个值为 'unkonwn' 的defaultScalarType 属性，以便任何没有在customScalarTypeMapping中指定的自定义标量都将被赋予别名 unknown 而不是 any（TypeScript从3.0开始推荐使用它来增加类型安全性）。

提示
注意我们导入的 _BigNumber 是从bignumber.js中导入的；这是为了避免循环类型引用。

avatar
文章
阅读
粉丝