Graffle 文档构建器(Document Builder)别名(Alias)指南:三种语法与类型安全实战
Graffle 文档构建器(Document Builder)别名(Alias)指南:三种语法与类型安全实战
本篇指南聚焦 Graffle 的 Document Builder 扩展中如何为 GraphQL 字段编写别名(Alias)。你将学会在 TypeScript 接口中使用的三种别名语法(完整数组、短数组、纯字符串)各自的适用场景与等价关系,并结合 $batch 批处理在真实 Pokemon Schema 上同时为带参数的根字段与标量字段设置别名,掌握别名如何影响返回结果的键名与类型推断。
为什么在 TypeScript 接口里需要别名
在原生 GraphQL 中,别名(Alias)允许你在同一个查询里用另一个名字引用字段,从而避免命名冲突或对同一字段做多次选择。GraphQL 规范要求别名必须是字符串,且会在返回结果中作为该字段的键名出现。
在 Graffle 的 Document Builder 接口中,别名被提升为类型系统的一等公民:你既可以在选择集的键(字段名)上写别名,也可以让同一个字段携带多个别名。所有别名语法都由 Document Builder 的选择解析器(Selection Parser)统一处理,最终被规范化为标准的 GraphQL 别名并写入文档 AST。
三种别名语法速览
根据文档 alias.md 的说明,Document Builder 支持三种别名写法:
| 语法 | 形式 | 适用字段 | 等价写法 |
|---|---|---|---|
| 完整数组(Full syntax) | ["aliasName", selectionSet] |
所有字段 | 无 |
| 短数组(Short array) | ["aliasName"] |
无必填参数、非标量选择之外的标量字段 | ["aliasName", true] |
| 纯字符串(String only) | "aliasName" |
无必填参数的标量字段 | ["aliasName", true] |
三种语法的语义规则如下:
- 完整数组语法
["aliasName", selectionSet]:适用于所有字段,也是唯一能够表达“带参数的字段”或“非标量(对象)选择”的写法——当字段带有必填参数或需要嵌套选择集时,必须使用该形式。 - 短数组语法
["aliasName"]:仅适用于没有必填参数的标量字段,等价于["aliasName", true],即“选择该字段并使用给定别名”。 - 纯字符串语法
"aliasName":同样只适用于没有必填参数的标量字段,等价于["aliasName", true],是三种语法中最简洁的选项。
别名语法的源码实现
从源码层面看,这三种写法在 SelectAlias.ts 中被明确定义:
SelectAliasOne:readonly [alias: string, selectionSet],即完整数组语法;SelectAliasShort:readonly [alias: string],即短数组语法;SelectAliasString:string,即纯字符串语法;SelectAliasMultiple:readonly SelectAliasOne[],支持给同一字段绑定多个别名。
其中的归一化函数 normalizeSelectAlias 会把三种语法统一收敛为内部表示 [["aliasName", <selectionSet>]] 的形式:
- 纯字符串
"x"→[["x", true]](true是“选择该字段”的指示符); - 短数组
["x"]→[["x", true]]; - 完整数组
["x", <selectionSet>]→[["x", <selectionSet>]]。
这与文档中“短数组与纯字符串等价于 ["aliasName", true]”的说明完全一致,也印证了三种语法在类型与运行时层面的统一性。
解析器在 parseSelection.ts 中按如下顺序识别别名(第 L152-L168 行):
- 先判断字符串值——由于字符串永远是标量字段的别名,所以优先于对象检查处理;
- 再判断数组值——调用
isSelectAlias识别["x"]、["x", <selectionSet>]以及多别名嵌套数组三种形态; - 两者都会被标记为
ParsedSelectionAlias,并携带归一化后的aliases列表,后续由 to-ast 阶段转换为真正的 GraphQL 别名节点。
需要留意的是数组别名的解析顺序:内联片段(Inline Fragment)与数组别名都可能使用数组值,因此解析器依靠不同的键名约定来区分两者(见 parseSelection.ts)。
完整实战示例:在 $batch 中为根字段与标量字段写别名
官方示例 document-builder_alias.ts 将三种别名语法组合在同一个 $batch 批处理查询中,是学习别名最直接的教材。
先导入生成模块并创建客户端:
import { Graffle } from './graffle/_.js'
const pokemon = Graffle.create()
准备两个时间边界,分别代表“100 年前”与“1 年前”,用于按生日过滤:
const day = 1000 * 60 * 60 * 24
const year = day * 365.25
const yearsAgo100 = new Date(Date.now() - year * 100)
const yearsAgo1 = new Date(Date.now() - year)
接着通过 pokemon.query.$batch({ ... }) 一次性选择两个根字段,并为它们及子字段分别起别名:
const pokemons = await pokemon.query.$batch({
pokemons: [
// 完整数组语法 —— 字段带参数/复杂选择时必须使用
[`elderPokemons`, {
$: { filter: { birthday: { lte: yearsAgo100 } } },
name: true,
id: `elderId`, // 纯字符串语法(最简洁)
hp: [`elderHp`], // 短数组语法
}],
[`babyPokemons`, {
$: { filter: { birthday: { gte: yearsAgo1 } } },
name: `babyName`, // 纯字符串语法(最简洁)
}],
],
})
代码要点解析:
- 根字段
pokemons的值是一个数组,数组第一项elderPokemons/babyPokemons就是根字段的别名(完整数组语法)。因为这两个根字段都带有必填的filter参数(通过$传入),所以必须使用完整数组形式; - 在
elderPokemons的选择集内部,id: 'elderId'与hp: ['elderHp']分别演示了纯字符串语法与短数组语法——它们都是无参标量字段,因此无需携带选择集; name: true则是不写别名的普通选择,用于对照。
$batch 本身是 Document Builder 提供的根级方法,用于一次写入多个根字段(详见 batch.md 与根字段示例 root-field.md);其运行时的执行入口可在 requestMethods.ts 中看到:$batch 方法接收选择集后,会检查是否包含手动提升(manual hoisting)标记来决定直接执行还是返回文档运行器。
运行结果:别名如何重塑返回结构
上述代码执行后,返回的 JSON 结构如下(来源:document-builder_alias.output.txt):
{
"elderPokemons": [
{
"name": "Pikachu",
"elderId": "1",
"elderHp": 35
},
{
"name": "Squirtle",
"elderId": "3",
"elderHp": 44
}
],
"babyPokemons": [
{
"babyName": "Charizard"
}
]
}
可以看到别名对返回结构的三个直接影响:
- 根字段名被替换为别名:请求里根字段
pokemons被分成了elderPokemons与babyPokemons两个键,这样一次$batch就能用不同参数查询同一根字段两次,结果互不覆盖; - 标量字段名被替换为别名:
id→elderId,hp→elderHp,name→babyName,返回对象的键名全部使用别名; - 类型推断同步更新:由于 Graffle 的结果类型由选择集推导,别名会直接进入推导出的 TypeScript 类型——你可以用类型断言验证这一点。在 requestMethods.test-d.ts 的类型测试中可以看到,
$batch配合别名["obj1", { id: true }]、["obj2", { id: true }]时,推导出的结果类型精确为{ obj1: { id: string | null } | null; obj2: { id: string | null } | null } | null,键名与别名一一对应。
给同一字段绑定多个别名
除了给单个字段写一个别名,Graffle 的 Document Builder 还支持多别名:同一个字段可以携带一组别名,以 [["alias1", <selectionSet>], ["alias2", <selectionSet>], ...] 的形式书写。这在需要“同一字段按不同参数或不同子选择同时出现”的场景下尤其有用,例如一次查询里同时取一个对象的两个不同时间窗口的数据。
多别名在类型层面由 SelectAliasMultiple 表示,其运行时识别同样发生在 parseSelection.ts 的 isSelectAlias 分支中(见 SelectAlias.ts 对嵌套数组的递归判断)。
别名适用边界与注意事项
- 带必填参数的字段必须使用完整数组语法:短数组与纯字符串语法等价于
["aliasName", true],无法表达参数与嵌套选择,因此仅限无必填参数的标量字段使用(见 alias.md); - 对象字段必须使用完整数组语法:非标量字段需要携带选择集,同样只能使用
["aliasName", selectionSet]; - 字符串值始终被当作别名解析:解析器在 parseSelection.ts 中于对象检查之前先处理字符串值,因此给标量字段传字符串时请牢记它代表的是别名而非其他含义;
- 数组值需要与内联片段区分:数组形态的别名与内联片段共享数组值形态,解析器依靠键名约定区分,书写时应保持各语法形态清晰一致。
参考链接
- 官方示例源码:document-builder_alias.ts
- 示例运行输出:document-builder_alias.output.txt
- 别名类型与归一化实现:SelectAlias.ts
- 选择解析器(含别名识别顺序):parseSelection.ts
$batch与别名的类型测试:requestMethods.test-d.ts$batch运行时入口:requestMethods.ts- 批处理根字段示例:batch.md