API 设计 / 系统课时

设计 Enum 与自定义 Scalar

设计 Enum 与自定义 Scalar

Schema 的边界应该尽早拒绝无效值,而不是把任意字符串传进业务代码后再猜含义。本课用 Enum 固定有限状态,用自定义 Scalar 约束日期格式,并说明金额这类值什么时候不应只做成一个标量。

学习目标

  • 用 Enum 表达封闭且可枚举的业务状态
  • 为自定义 Scalar 明确序列化、变量输入和字面量输入规则
  • 判断日期、金额等领域值应该使用 Scalar 还是对象类型

Enum 用来收紧有限状态

当一个字段只能取少量稳定状态时,使用 String 会让拼写错误和未知值延迟到运行时。Enum 把允许值写入 Schema,客户端可以通过 introspection 获得候选项,GraphQL 也会在进入 resolver 前拒绝非法枚举值。

例如订单状态适合定义为 PENDING、PAID、CANCELLED。枚举值最好表达领域含义,而不是把数据库中的数字码直接暴露给 API;内部存储如何变化,不应迫使客户端一起修改。

自定义 Scalar 要守住序列化边界

内置 Scalar 只有 Int、Float、String、Boolean 和 ID。日期时间虽然能用字符串承载,但如果 API 约定“只接受 UTC ISO-8601”,就可以创建 DateTime Scalar,把格式校验集中在 GraphQL 边界。

下面是完整的 GraphQL.js 示例。项目中需要已安装 graphql 包,脚本保存为 index.mjs 后即可运行。

js
import {
  GraphQLEnumType,
  GraphQLID,
  GraphQLNonNull,
  GraphQLObjectType,
  GraphQLScalarType,
  GraphQLSchema,
  Kind,
  graphql
} from "graphql";

const OrderStatus = new GraphQLEnumType({
  name: "OrderStatus",
  values: {
    PENDING: { value: "PENDING" },
    PAID: { value: "PAID" },
    CANCELLED: { value: "CANCELLED" }
  }
});

const utcIsoPattern =
  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;

function parseDateTime(value) {
  if (typeof value !== "string" || !utcIsoPattern.test(value)) {
    throw new TypeError("DateTime must use YYYY-MM-DDTHH:mm:ss.sssZ");
  }

  const date = new Date(value);
  if (Number.isNaN(date.getTime()) || date.toISOString() !== value) {
    throw new TypeError("DateTime contains an invalid calendar value");
  }
  return date;
}

const DateTime = new GraphQLScalarType({
  name: "DateTime",
  serialize(value) {
    if (!(value instanceof Date) || Number.isNaN(value.getTime())) {
      throw new TypeError("DateTime can only serialize valid Date values");
    }
    return value.toISOString();
  },
  parseValue: parseDateTime,
  parseLiteral(ast) {
    if (ast.kind !== Kind.STRING) {
      throw new TypeError("DateTime literal must be a string");
    }
    return parseDateTime(ast.value);
  }
});

const OrderType = new GraphQLObjectType({
  name: "Order",
  fields: {
    id: { type: new GraphQLNonNull(GraphQLID) },
    status: { type: new GraphQLNonNull(OrderStatus) },
    createdAt: { type: new GraphQLNonNull(DateTime) }
  }
});

const QueryType = new GraphQLObjectType({
  name: "Query",
  fields: {
    order: {
      type: OrderType,
      resolve: () => ({
        id: "o1",
        status: "PAID",
        createdAt: new Date("2026-08-24T12:00:00.000Z")
      })
    },
    echoDate: {
      type: new GraphQLNonNull(DateTime),
      args: { at: { type: new GraphQLNonNull(DateTime) } },
      resolve: (_source, { at }) => at
    }
  }
});

const schema = new GraphQLSchema({ query: QueryType });
const result = await graphql({
  schema,
  source: `
    query ($at: DateTime!) {
      order { id status createdAt }
      echoDate(at: $at)
    }
  `,
  variableValues: { at: "2026-08-24T13:30:00.000Z" }
});

console.log(JSON.stringify(result, null, 2));

预期输出:

json
{
  "data": {
    "order": {
      "id": "o1",
      "status": "PAID",
      "createdAt": "2026-08-24T12:00:00.000Z"
    },
    "echoDate": "2026-08-24T13:30:00.000Z"
  }
}

serialize 约束服务端输出,parseValue 处理变量传入的值,parseLiteral 处理查询文本中直接写出的字面量。只实现其中一部分,常会出现“查询能返回,但 mutation 输入行为不一致”的问题。

Scalar 不是领域对象的缩写

自定义 Scalar 最适合“客户端把它当作一个原子值处理,但服务端需要额外校验”的数据,例如 UUID、UTC 时间戳或固定格式的十进制字符串。它的内部结构对客户端不可见,因此不要把需要单独查询、筛选或演进的多个语义塞进一个 Scalar。

金额就是典型边界。如果 API 只传某一种固定货币的最小单位整数,Int 或受约束的 Scalar 可能足够;如果金额必须同时携带币种,则对象类型通常更清楚:

graphql
type Money {
  amountMinor: Int!
  currency: Currency!
}

enum Currency {
  USD
  CNY
  EUR
}

这是 Schema 片段示例,依赖已有的查询或业务对象字段引用 Money。amountMinor 表示最小货币单位,避免二进制浮点数直接表示十进制金额;currency 则保留独立的领域含义和未来扩展空间。

演进时保持值语义稳定

Enum 新增值通常比删除或改名安全,但客户端如果用穷举分支处理枚举,仍要为未来值保留兜底策略。已经发布的枚举值不要复用为新含义,废弃时应先让客户端停止依赖,再从 Schema 移除。

自定义 Scalar 则应把格式契约写进文档并长期保持一致。例如同一个 DateTime 不要一部分接口返回 UTC 字符串,另一部分返回毫秒时间戳。Enum 负责限制“有限集合”,Scalar 负责约束“单个原子值”;只要边界清晰,验证逻辑就能在进入业务层之前完成。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

设计 Enum 与自定义 Scalar

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通