JavaScript：GraphQL Scalars（自定义标量）

graphql-github-io-zh-Hans生态项目与库

GraphQL Scalars

简介

GraphQL Scalars 是一个开源的、用于构建精确且类型安全 GraphQL Schema 的自定义标量类型库。它提供了一系列预定义的标量类型，弥补了 GraphQL 内置标量类型（如 Int、Float、String、Boolean 和 ID）在实际业务场景中的不足。

通过使用该库，开发者可以在 Schema 层直接解析和校验日期、时间、大整数、URL、Email 等复杂格式，而无需在业务代码中反复编写数据校验逻辑。

特性

类型安全：在 GraphQL 执行层直接进行数据校验和序列化/反序列化。
开箱即用：内置数十种常用自定义标量。
跨技术栈：支持 JavaScript/TypeScript、Python、Go、Java 等主流 GraphQL 服务端实现。
与 Apollo Server、Yoga 等无缝集成：可便捷地接入现有 GraphQL 服务。

安装

bash 复制代码

npm install graphql-scalars
# 或使用 yarn
yarn add graphql-scalars

快速上手

下面是一个在 Apollo Server 中使用 DateTimeISO 标量的示例：

typescript 复制代码

import { ApolloServer } from '@apollo/server';
import { DateTimeISOResolver } from 'graphql-scalars';

const typeDefs = `#graphql
  scalar DateTimeISO

  type Event {
    id: ID!
    name: String!
    startAt: DateTimeISO!
    endAt: DateTimeISO
  }

  type Query {
    upcomingEvents(after: DateTimeISO!): [Event!]!
  }
`;

const resolvers = {
  DateTimeISO: DateTimeISOResolver,
};

const server = new ApolloServer({ typeDefs, resolvers });

在 GraphQL Schema 中，你只需要将对应的标量映射到解析器（Resolver），即可在该字段上获得完整的验证逻辑。

常用标量类型

以下为该库中高频使用的一些标量类型：

日期与时间

标量名称	说明
`DateTimeISO`	符合 ISO 8601 格式的日期时间字符串，如 `2025-01-01T12:00:00Z`
`DateTime`	采用 Unix 时间戳（毫秒）表示的日期时间
`Date`	仅包含日期部分（YYYY-MM-DD），不包含时间和时区
`Time`	仅包含时间部分（HH:mm:ss）
`Timestamp`	对应 `Date` 对象支持的时间戳值

数值类型

标量名称	说明
`BigInt`	任意精度的整数，对应 JavaScript 的 `BigInt`
`Byte`	字节类型，接受数字或 Buffer
`SafeInt`	在 JavaScript 安全整数范围内的整数（`-2^53 + 1` 至 `2^53 - 1`）
`UnsignedInt`	非负整数
`NonNegativeFloat`	非负浮点数
`PositiveInt`	正整数

字符串格式

标量名称	说明
`EmailAddress`	电子邮件地址格式校验
`URL`	必须是合法的 URL 地址
`UUID`	RFC 4122 标准的 UUID 字符串
`PhoneNumber`	国际电话号码格式
`IPAddress` / `IPv4` / `IPv6`	IP 地址格式校验
`HexColorCode`	十六进制颜色值（如 `#FFFFFF`）
`HSL` / `HSLA`	色相、饱和度、亮度颜色表示法
`JSONObject`	任意合法的 JSON 对象

业务语义类型

标量名称	说明
`CountryCode`	ISO 3166-1 alpha-2 格式的国家代码
`Currency`	ISO 4217 货币代码
`PostalCode`	邮政编码
`SemVer`	语义化版本号（Semantic Versioning）
`IBAN`	国际银行账号（需配合正则使用）
`ObjectID`	MongoDB 的 ObjectId 格式

完整列表及 API 详情可参考 GitHub 仓库。

自定义标量的扩展

该库还允许你基于其底层工具（例如 GraphQLScalarType）自定义新的标量类型。以下是一个简易的自定义标量示例：

typescript 复制代码

import { GraphQLScalarType, Kind } from 'graphql';

const RGBResolver = new GraphQLScalarType({
  name: 'RGB',
  description: '一个 RGB 颜色元组，形如 (r, g, b)',
  serialize(value) {
    let [r, g, b] = value;
    return `(${r}, ${g}, ${b})`;
  },
  parseValue(value) {
    if (typeof value !== 'string') {
      throw new Error('RGB 值必须是字符串');
    }
    return value.match(/\d+/g).map(Number);
  },
  parseLiteral(ast) {
    if (ast.kind === Kind.STRING) {
      return ast.value.match(/\d+/g).map(Number);
    }
    return null;
  },
});

总结

GraphQL Scalars 通过提供丰富、易用的自定义标量，显著提升了 GraphQL API 的数据准确性、可维护性和前后端协作效率。对于任何生产级别的 GraphQL 项目，它都是一套值得引入的生态组件。

资源链接

GitHub 仓库：https://github.com/Urigo/graphql-scalars
npm 包：https://www.npmjs.com/package/graphql-scalars
所属分类：生态项目与库
适用语言：JavaScript / TypeScript

帮助我们改进文档

发现翻译问题或内容错误？请告诉我们。