API 设计 / 系统课时
处理变量校验与参数强制转换
处理变量校验与参数强制转换
GraphQL 变量出错时,问题可能发生在文档校验阶段,也可能发生在执行前的变量强制转换阶段。本篇用同一组查询区分这两个阶段,并说明默认值、空值和输入对象如何最终变成 Resolver 参数。
学习目标
- 区分文档静态校验、变量值强制转换和 Resolver 执行三个阶段
- 理解变量默认值、参数默认值、
null与“未提供”的差异 - 识别
Int、ID、列表和 Input Object 的常见强制转换边界
校验和强制转换不是一回事
GraphQL 先解析查询文档,再检查变量声明能否用于对应参数位置。例如把 $limit: String 传给 Int 参数属于文档本身不合法,服务器在执行 Resolver 之前就能拒绝它。文档通过校验后,服务器才拿实际 variables JSON 按变量声明进行输入强制转换。

这一区分直接决定错误应该在哪一层修:变量类型放错位置要改查询文档;JSON 值类型不符合变量声明要改客户端变量;已经成功进入 Resolver 后的“最大只能查 100 条”等约束,则属于业务校验,而不是 GraphQL 类型强制转换。
默认值与输入强制转换
变量和参数都有可能声明默认值,但它们只在“未提供”时参与计算。若变量定义本身有默认值,变量缺失时先得到该默认值;若参数最终仍未得到值,Schema 上的参数默认值才可能生效。显式传入 null 不等于缺失:对 Non-Null 类型会直接报错,对可空类型则把 null 继续传递。
GraphQL 也不会把所有看起来相似的 JSON 值自动转换。字符串 "5" 不能当作 Int,1 不能当作 Boolean;ID 是少数允许字符串或整数输入的标量,Resolver 通常接收到字符串形式。Input Object 中出现未声明字段会报错,而带默认值的输入字段在缺失时可被补齐。
列表还有一个容易忽略的规则:当期望列表类型而输入的是单个可接受值时,GraphQL 可以把它按单元素列表处理。客户端虽然可以利用这一点,但 API 设计和调用代码最好保持变量形状稳定,避免同一字段一会儿传标量、一会儿传数组。
用同一查询观察四种结果
下面的完整 GraphQL.js 示例同时覆盖正常变量、变量默认值、运行时强制转换失败和静态校验失败。为了让输出不依赖具体库版本的错误文案,示例只输出是否出现错误以及成功时的 data。
import { buildSchema, graphql } from "graphql";
const schema = buildSchema(`
input SearchFilter {
keyword: String!
tags: [String!] = []
}
type SearchResult {
keyword: String!
tags: [String!]!
limit: Int!
}
type Query {
search(filter: SearchFilter!, limit: Int = 20): SearchResult!
}
`);
const rootValue = {
search({ filter, limit }) {
return {
keyword: filter.keyword,
tags: filter.tags,
limit,
};
},
};
const operation = `
query Search($filter: SearchFilter!, $limit: Int = 10) {
search(filter: $filter, limit: $limit) {
keyword
tags
limit
}
}
`;
async function run(label, source, variableValues) {
const result = await graphql({
schema,
source,
rootValue,
variableValues,
});
const normalized = result.errors
? { label, hasErrors: true, data: result.data ?? null }
: { label, hasErrors: false, data: result.data };
console.log(JSON.stringify(normalized));
}
await run("valid", operation, {
filter: { keyword: "graphql", tags: ["api"] },
limit: 5,
});
await run("variable-default", operation, {
filter: { keyword: "graphql" },
});
await run("coercion-error", operation, {
filter: { keyword: "graphql" },
limit: "5",
});
const invalidDocument = `
query Broken($filter: SearchFilter!, $limit: String) {
search(filter: $filter, limit: $limit) {
limit
}
}
`;
await run("validation-error", invalidDocument, {
filter: { keyword: "graphql" },
limit: "5",
});预期输出
{"label":"valid","hasErrors":false,"data":{"search":{"keyword":"graphql","tags":["api"],"limit":5}}}
{"label":"variable-default","hasErrors":false,"data":{"search":{"keyword":"graphql","tags":[],"limit":10}}}
{"label":"coercion-error","hasErrors":true,"data":null}
{"label":"validation-error","hasErrors":true,"data":null}第二次调用没有提供 limit,所以变量定义上的默认值 10 生效;tags 也因 Input Object 字段缺失而得到 Schema 默认值 []。第三次的文档是合法的,但变量 JSON 把 limit 传成字符串,因此在 Resolver 执行前的变量强制转换阶段失败。第四次则连变量类型位置都不兼容,静态校验阶段就会拒绝。
把类型错误留在 Resolver 之外
客户端应在构造 variables JSON 时就发送正确的 JSON 类型,尤其是 HTML 表单通常先得到字符串,不能把 "25" 原样交给声明为 Int 的变量。服务端也不应在 Resolver 里再写一套“字符串转整数”的补救逻辑,否则 Schema 声明和实际接受范围会产生两套规则。
调试变量错误时,先判断查询文档是否能通过静态校验,再检查实际 variables JSON 是否满足声明,最后才进入业务参数校验。按这个顺序定位,可以快速区分“查询写错”“客户端值类型错误”和“业务规则不满足”三类问题。