Graffle 默认输出行为指南：零配置 GraphQL 客户端如何直接返回查询数据

• 后端

导读

本文基于 Graffle（Simple GraphQL Client for JavaScript）官方示例 output_default.ts，深入讲解客户端在不做任何输出配置时的默认行为：查询结果以纯 JavaScript 数据直接返回，既没有{ data, errors }信封包装，也没有错误吞并。读完本文，你将掌握Graffle.create()的零配置用法、默认输出配置项的源码级含义，以及如何通过output配置切换到信封（envelope）、错误返回（return-error）等其他输出形态。

一、示例全貌：默认输出的最小可运行代码

官方示例文档 website/content/examples/20_output/default.md 与代码片段 website/content/_snippets/examples/output/default.md 展示的完整代码如下：

import { Graffle } from './graffle/_.js' const pokemon = Graffle.create() const pokemons = await pokemon.query.pokemons({ name: true }) console.log(pokemons)

实际可运行的示例源码位于 examples/20_output/output_default.ts，它与文档片段几乎一致，仅将console.log替换为项目中统一的show()辅助函数：

import { Graffle } from '../$/graffle/_.js' import { show } from '../$/helpers.js' const pokemon = Graffle.create() const pokemons = await pokemon.query.pokemons({ name: true }) show(pokemons)

两段代码的要点完全一致，值得逐一拆解：

1. Graffle.create()不传任何参数——这是本示例与 output_envelope、output_return-error 等其他输出示例最本质的区别。它意味着客户端使用全部默认配置，包括默认输出配置。
2. pokemon.query.pokemons({ name: true })采用 Graffle 的类型安全选择集语法：query是查询入口，pokemons是查询根字段，{ name: true }表示只选择每个 pokemon 的name字段。对象字面量形式的字段选择会自动获得 TypeScript 类型推导与校验。
3. await之后直接得到数据本身——默认输出下，返回值就是查询结果数据，可以直接console.log或赋值给变量继续处理。

二、运行结果：纯数据数组，无任何包装

示例在真实 schema 上执行后，控制台输出如下（示例输出文件 可验证）：

[ { name: 'Pikachu' }, { name: 'Charizard' }, { name: 'Squirtle' }, { name: 'Bulbasaur' }, { name: 'Caterpie' }, { name: 'Weedle' } ]

这份输出直观地揭示了默认输出模式的三个特征：

• 直接返回数据本体：pokemons就是一个由对象组成的数组，与 GraphQL 响应中的data.pokemons完全对应；
• 无信封结构：结果中看不到{ data: ..., errors: [...] }这样的传统 GraphQL 信封包装，也没有result、envelope之类的中间层；
• 字段严格按选择集返回：由于只选择了name，每个对象仅包含name一个键，多余的字段（如id、type）不会出现在结果中。

三、源码视角：默认输出配置的精确含义

默认输出行为并非巧合，而是由 Graffle 的output配置模块的默认值决定的。核心实现位于 src/context/fragments/configuration/output/configuration.ts，其default_对象定义了所有输出相关的默认值：

const default_ = { defaults: { errorChannel: `throw`, }, envelope: { enabled: false, errors: { execution: true, other: false, }, }, errors: { execution: `default`, other: `default`, }, } satisfies Partial<Normalized>

逐项解读：

类型层面，Input接口还完整定义了用户可传入的配置项形态（configuration.ts）：

• defaults.errorChannel：可选'throw' | 'return'；
• envelope：可传布尔值，也可传长写形式{ enabled?: boolean, errors?: { execution?: boolean, other?: boolean } }；
• errors.execution/errors.other：取值'throw' | 'return' | 'default'，其中'default'表示跟随defaults.errorChannel。

inputResolver（configuration.ts）负责把用户输入与默认值合并：例如传入envelope: true会被规范化为{ enabled: true, ...input.envelope }，即开启信封但错误槽位仍沿用默认值。

四、错误处理通道：默认输出下的异常语义

默认输出模式并不等于"隐藏错误"。从defaults.errorChannel: 'throw'可以看出，默认配置下：

• 执行错误（execution）：指传统 GraphQL 执行结果中errors字段里的错误，默认通过抛异常的方式暴露；
• 其他错误（other）：包括 HTTP transport 下fetch抛出的网络错误、扩展抛出的错误等，同样默认抛出。

这种"数据裸返回 + 错误即抛出"的组合，是 Graffle 最轻量的使用形态：业务代码里await查询，成功则直接拿到数据，失败则被异常打断，无需任何结果结构判断。这也与readErrorCategoryOutputChannel（configuration.ts）的实现相印证——当某类错误配置为'default'时，直接返回output.defaults.errorChannel对应的通道（默认'throw'）。

五、与其他输出形态的对比：何时该改默认值

理解了默认值，就自然理解了其他输出示例存在的意义。output配置通过Graffle.create({ output: {...} })或链式.with({ output: {...} })注入（client.ts 中的with方法），典型场景包括：

• 传统 GraphQL 信封：output: { envelope: true }，结果包装为{ data, errors }，对应示例 output_envelope；
• 执行错误返回而非抛出：output: { errors: { execution: 'return' } }，对应示例 output_return-error，便于在结果中携带错误继续处理；
• 标准 GraphQL 兼容输出：standard-graphqlpreset 提供{ envelope: true, errors: { execution: 'return' } }等组合（output_preset__standard-graphql 输出）。

从源码看，traditionalGraphqlOutput（configuration.ts）就是信封 + 执行错误进信封 + 其他错误不进信封的经典组合，可作为自定义配置的参考基准。

六、小结

本示例虽短，却精确刻画了 Graffle 的"最小默认"哲学：Graffle.create()零配置即可查询并直接拿到干净的数据数组；错误默认抛出；一切输出包装（信封、错误返回）都需显式开启。理解这份默认配置（configuration.ts）的每个字段，是掌握 Graffle 全部输出形态——envelope、return-error、standard-graphql——的起点，也是在实际项目中按需定制输出策略的第一步。

• 后端