标量 Scalars

导读

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，请将buildSchemaOptions对象的dateScalarMode设置为'timestamp'，如下所示：

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

同样，默认情况下使用 GraphQLFloat 来表示 number 类型。要改用 GraphQLInt，请将 buildSchemaOptions 对象的 numberScalarMode 设置为 'integer'，如下所示：

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

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

覆盖默认标量

要为 Date 标量创建自定义实现，只需创建一个新类。

ts
import { CustomScalar, Scalar } 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注册为提供程序。

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

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

ts
@Field()
creationDate: Date;

导入自定义标量

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

首先安装包：

bash
$ npm i --save graphql-type-json

安装包后，我们将自定义解析器传递给 forRoot() 方法：

ts
import GraphQLJSON from 'graphql-type-json'

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

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

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

有关一组有用的标量，请查看 graphql-scalars 包。

创建自定义标量

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

ts
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() 方法：

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

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

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

Schema 优先

要定义自定义标量（在此处阅读有关标量的更多信息），请创建类型定义和专用解析器。在这里（如官方文档中所述），我们将使用 graphql-type-json 包进行演示。此 npm 包定义了 JSON GraphQL 标量类型。

首先安装包：

bash
$ npm i --save graphql-type-json

安装包后，我们将自定义解析器传递给 forRoot() 方法：

ts
import GraphQLJSON from 'graphql-type-json'

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

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

graphql
scalar JSON

type Foo {
  field: JSON
}

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

ts
import { CustomScalar, Scalar } 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注册为提供程序。

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

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

graphql
scalar Date

默认情况下，为所有标量生成的 TypeScript 定义都是any——这不是特别类型安全的。 但是，当您指定如何生成类型时，您可以配置 Nest 如何为自定义标量生成类型：

ts
import { join } from 'node:path'
import { GraphQLDefinitionsFactory } from '@nestjs/graphql'

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）的 name 属性来生成 TS 定义。注意：需要为非内置类型（自定义类型）添加 import 语句。

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

graphql
标量 DateTime
标量 BigNumber
标量 Payload

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

ts
import _BigNumber from 'bignumber.js'

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

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

提示

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