API 设计 / 系统课时

处理变量校验与参数强制转换

处理变量校验与参数强制转换

GraphQL 变量出错时,问题可能发生在文档校验阶段,也可能发生在执行前的变量强制转换阶段。本篇用同一组查询区分这两个阶段,并说明默认值、空值和输入对象如何最终变成 Resolver 参数。

学习目标

  • 区分文档静态校验、变量值强制转换和 Resolver 执行三个阶段
  • 理解变量默认值、参数默认值、null 与“未提供”的差异
  • 识别 Int、ID、列表和 Input Object 的常见强制转换边界

校验和强制转换不是一回事

GraphQL 先解析查询文档,再检查变量声明能否用于对应参数位置。例如把 $limit: String 传给 Int 参数属于文档本身不合法,服务器在执行 Resolver 之前就能拒绝它。文档通过校验后,服务器才拿实际 variables JSON 按变量声明进行输入强制转换。

GraphQL 从文档校验到变量与参数强制转换的执行阶段

这一区分直接决定错误应该在哪一层修:变量类型放错位置要改查询文档;JSON 值类型不符合变量声明要改客户端变量;已经成功进入 Resolver 后的“最大只能查 100 条”等约束,则属于业务校验,而不是 GraphQL 类型强制转换。

默认值与输入强制转换

变量和参数都有可能声明默认值,但它们只在“未提供”时参与计算。若变量定义本身有默认值,变量缺失时先得到该默认值;若参数最终仍未得到值,Schema 上的参数默认值才可能生效。显式传入 null 不等于缺失:对 Non-Null 类型会直接报错,对可空类型则把 null 继续传递。

GraphQL 也不会把所有看起来相似的 JSON 值自动转换。字符串 "5" 不能当作 Int,1 不能当作 Boolean;ID 是少数允许字符串或整数输入的标量,Resolver 通常接收到字符串形式。Input Object 中出现未声明字段会报错,而带默认值的输入字段在缺失时可被补齐。

列表还有一个容易忽略的规则:当期望列表类型而输入的是单个可接受值时,GraphQL 可以把它按单元素列表处理。客户端虽然可以利用这一点,但 API 设计和调用代码最好保持变量形状稳定,避免同一字段一会儿传标量、一会儿传数组。

用同一查询观察四种结果

下面的完整 GraphQL.js 示例同时覆盖正常变量、变量默认值、运行时强制转换失败和静态校验失败。为了让输出不依赖具体库版本的错误文案,示例只输出是否出现错误以及成功时的 data。

js
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",
});

预期输出

text
{"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 是否满足声明,最后才进入业务参数校验。按这个顺序定位,可以快速区分“查询写错”“客户端值类型错误”和“业务规则不满足”三类问题。

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

目录与阅读设置

阅读设置

17

记录一个想法

处理变量校验与参数强制转换

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

登录哪都通