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 后即可运行。
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));预期输出:
{
"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 可能足够;如果金额必须同时携带币种,则对象类型通常更清楚:
type Money {
amountMinor: Int!
currency: Currency!
}
enum Currency {
USD
CNY
EUR
}这是 Schema 片段示例,依赖已有的查询或业务对象字段引用 Money。amountMinor 表示最小货币单位,避免二进制浮点数直接表示十进制金额;currency 则保留独立的领域含义和未来扩展空间。
演进时保持值语义稳定
Enum 新增值通常比删除或改名安全,但客户端如果用穷举分支处理枚举,仍要为未来值保留兜底策略。已经发布的枚举值不要复用为新含义,废弃时应先让客户端停止依赖,再从 Schema 移除。
自定义 Scalar 则应把格式契约写进文档并长期保持一致。例如同一个 DateTime 不要一部分接口返回 UTC 字符串,另一部分返回毫秒时间戳。Enum 负责限制“有限集合”,Scalar 负责约束“单个原子值”;只要边界清晰,验证逻辑就能在进入业务层之前完成。