Glimmer 预处理器三阶段管道深度解析:Ember.js 中模板从 AST 到 Wire Format 的完整旅程
Glimmer 预处理器三阶段管道深度解析:Ember.js 中模板从 AST 到 Wire Format 的完整旅程
Glimmer 预处理器(Preprocessor)是 Ember.js 模板编译管线的核心组件,负责把开发者书写的 Handlebars 风格模板转化为紧凑、可传输的 Wire Format 字节表示。本文以 PASSES.md 为骨架,结合 @glimmer/compiler 包的源码实现,系统讲解 Normalization、Symbol Allocation、Encoding 三个阶段的职责边界、底层原理与调用链。读完本文,你将能够理解一条 {{#each}} 模板语句是如何从字符串逐步变成 <a href="https://link.gitcode.com/i/298bc4a78e37df81f08c01f61945dd66" target="_blank">statements, symbols, upvars] 三元组序列化块的,也能掌握在 [@glimmer/compiler/lib/passes 目录下扩展新编译器 pass 的挂载点。
预处理器在整个编译管线中的位置
Glimmer 预处理器是模板编译链路的第一个主要环节。它的职责单一而明确:接收模板,将其转换为 Wire Format。用 PASSES.md 原文来说:
The Glimmer preprocessor is responsible for taking templates and converting them into the Wire Format.
预处理器的输入是 AST(抽象语法树)。AST 是模板字符串经由 @glimmer/syntax 解析后的产物,具体而言是 AST v2(@glimmer/syntax 包中的 README 有更详细的说明)。这一层级关系可以从编译入口 compiler.ts 得到印证:
export function precompileJSON(
string: Nullable<string>,
options: PrecompileOptions | PrecompileOptionsWithLexicalScope = defaultOptions
): [block: SerializedTemplateBlock, usedLocals: string[]] {
const source = new src.Source(string ?? '', options.meta?.moduleName);
const [ast, locals] = normalize(source, { lexicalScope: () => false, ...options });
const block = pass0(source, ast, options.strictMode ?? false).mapOk((pass2In) => {
return pass2(pass2In);
});
// ...
}
从源码结构可以清晰看出整条流水线:normalize(来自 @glimmer/syntax/lib/v2/normalize)先把模板字符串解析为 AST v2,然后依次执行两个编译器 pass——pass0(./passes/1-normalization/index)与 pass2(./passes/2-encoding/index)。precompile 则在 precompileJSON 的基础上进一步把序列化块包装成带 id、scope、isStrictMode 等元信息的模板 JavaScript 字符串(见 compiler.ts)。
三阶段架构总览
PASSES.md 将预处理过程划分为三个概念性的 pass:
| 阶段 | 输入 → 输出 | 核心职责 |
|---|---|---|
| Normalization | AST → HIR | 把 AST 中所有 block、curly、表达式统一看待的形态,规整为带有关键词专用指令(如 #in-element、{{yield}}、(has-block))的高层 IR |
| Symbol Allocation | HIR → MIR | 用唯一符号(symbol)取代字符串形式的变量绑定与引用,消除解析变量位置时对作用域栈的依赖 |
| Encoding | MIR → Wire Format | 把 MIR 编码为适合线缆传输的紧凑 wire format,并在此阶段执行优化 |
其中 MIR 的定位值得特别注意,文档原文特别强调:
The MIR is a representation of the encoded wire format before serializing the instructions, and with source offsets still attached to each instruction.
也就是说,MIR 是尚未序列化的 wire format 的"内存态",每条指令仍挂着源偏移(source offsets),方便后续调试与错误定位。MIR 的全部节点类型定义在 passes/2-encoding/mir.ts 中,例如 SimpleElement、Component、Yield、Each、InvokeComponent、SplatAttr 等,它们共同组成了编码阶段的输入语言。
需要说明的是:PASSES.md 从概念上把 Symbol Allocation 描述为独立阶段,而从当前仓库的源码结构看,符号分配实际上是内嵌在 Normalization pass 中完成的(见下文第四节),这与文档的阶段性描述并不冲突——文档阐述的是设计意图,代码展示的是当前实现形态。
Pass 1:Normalization —— AST 到 HIR
Normalization pass 的目标是把语法树"理顺",产出对后续 pass 友好的高层 IR(HIR)。它的实现入口是 passes/1-normalization/index.ts 中的 normalize 函数,其 JSDoc 注释对其职责做了非常直白的概括:
-
关键词识别与分离:把
(has-block)、{{#in-element}}、{{yield}}等关键词从用户空间调用中剥离出来,翻译为 HIR 中的专用指令节点。在 MIR 节点表中可以看到对应产物:InElement、Yield、HasBlock、HasBlockParams、WithDynamicVars、GetDynamicVar、Log等(见 mir.ts)。 -
HTML 标签分类:把元素标签区分为四种语义类别:
- 普通 HTML 元素(
<div>)→SimpleElement - 带组件特性的 HTML 元素(有 modifier 或 splattributes)→ 归入
Component - 组件调用(
<CapCase />) - 动态组件调用(
<f.input />) - 命名块(
<:NamedBlock>)→NamedBlock
分类逻辑集中在 passes/1-normalization/visitors/element 目录(
classified.ts、component.ts、simple-element.ts),而元素标签字符串也会被规整为表达式——例如<this.x />被归一化为 head 为this、tail 为<a href="https://link.gitcode.com/i/fe5acdb96f6d9cab422c2e8135bcee4b" target="_blank">"x"]的路径表达式(见 [index.ts 的注释示例)。 - 普通 HTML 元素(
-
清理 Handlebars AST 中不利于后续处理的方面:例如种类繁多的字面量节点被统一为
hir.Literal。
源位置归一化
AST v2 的每个节点都带 SourceLocation(由 line + column 组成的起止位置对)。Pass 0 会把这些位置统一为 SourceOffsets(简单的字节偏移)。在 HashPair 的 key、位置参数列表这类没有天然父节点的 AST 片段上,Pass 0 会尽可能补上 SourceOffsets 标注(详见 passes/1-normalization/README.md)。
表达式的归一化规则
passes/1-normalization/README.md 用伪算法记录了表达式与语句的归一化规则,摘要如下:
- Process-Expression:按
expr.type分派——AST.Literal归一化为hir.Literal;AST.SubExpression若命中关键词则做语法检查并翻译为hir.Expr,否则翻译 callee 与参数;AST.PathExpression依据 head 种类分派:this→hir.GetThis,@arg→hir.GetArg,裸词在 loose 模式 →hir.GetVar,在 strict 模式 →hir.StrictGetVar。 - Process-Statement:
PartialStatement(Handlebars 的>语法)直接报错不支持;MustacheCommentStatement忽略;TextNode→hir.AppendTextNode;CommentStatement→hir.AppendComment;BlockStatement若为关键词则翻译为hir.Statement,否则构造NamedBlock列表并翻译块头表达式。 - Process Positional / Named Arguments:位置参数映射为
hir.Params,具名参数(hash pairs)映射为hir.Hash/hir.HashPair。
Normalization 的可变状态
Normalization 过程中依赖一个可变状态对象 NormalizationState(见 passes/1-normalization/context.ts),它维护了当前作用域符号表 _currentScope(SymbolTable),并通过 visitBlock 在进入/离开块时切换作用域;此外还提供 generateUniqueCursor() 生成 %cursor:N% 形式的唯一游标,用于需要临时变量的场合。
Pass 2:Symbol Allocation —— 用符号取代字符串
Symbol Allocation 阶段的核心动机非常工程化:HIR 指令用字符串标识变量绑定与引用,而 MIR 为每个绑定和引用分配唯一的符号(symbol)。这样一来,后续阶段解析一个变量引用的位置时,不再需要理解当前的作用域栈——符号本身就是定位信息。
除为块参数引入的作用域内绑定(in-scope bindings)分配符号外,该 pass 还为以下三类实体分配符号:
@arg引用:模板中@foo形式的参数引用;- 经由
{{yield}}、(has-block)、(has-block-params)关键词引用的块:在 MIR 中体现为Yield节点的to字段(数字符号)以及HasBlock/HasBlockParams节点的symbol字段(见 mir.ts); - 同时负责识别
{{debugger}}关键词——它需要运行时符号映射(runtime symbol maps),对应 MIR 中的Debugger节点(fields<{ scope: SymbolTable }>)。
符号分配在源码中的实际落点
从当前源码结构看,符号分配并非独立文件,而是通过 SymbolTable.allocate* 系列方法在 Normalization pass 执行期间内联完成的。例如:
- passes/1-normalization/keywords/append.ts 中
{{yield}}翻译时调用state.scope.allocateBlock(target.chars); - passes/1-normalization/keywords/utils/has-block.ts 中
(has-block)/(has-block-params)翻译时调用scope.allocateBlock(target.chars); - passes/1-normalization/visitors/element/classified.ts 中 splattributes 处理时调用
this.state.scope.allocateBlock('attrs')。
符号表(SymbolTable)由 @glimmer/syntax 提供(@glimmer/syntax/lib/symbol-table),它最终会产出两类数据:symbols(块参数等局部符号列表)与 upvars(模板引用的自由变量列表)——这两者正是编码阶段输出块的重要组成部分。
Pass 3:Encoding —— MIR 到 Wire Format
Encoding pass 把 MIR 编码为 wire format——一种适合传输的紧凑二进制表示。当前实现硬编码输出 @glimmer/wire-format 中文档化的格式(PASSES.md 第 19 行)。这也是执行优化的阶段,例如**擦除尾部 null(erasing trailing nulls)**及其他简单的打包优化。
编码入口是 passes/2-encoding/index.ts 的 visit 函数,实现非常精简:
export function visit(template: mir.Template): WireFormat.SerializedTemplateBlock {
let statements = CONTENT.list(template.body);
let scope = template.scope;
let block: WireFormat.SerializedTemplateBlock = [statements, scope.symbols, scope.upvars];
return block;
}
可见最终产出的 SerializedTemplateBlock 是一个三元组 [statements, symbols, upvars]:
- statements:编码后的指令序列(由
CONTENT.list递归编码模板 body 得到,具体编码逻辑见 passes/2-encoding/content.ts); - symbols:局部符号列表(块参数);
- upvars:自由变量(upvar)列表,即模板中引用、但需由外部作用域提供的变量名。
该目录下的 passes/2-encoding/README.md 也印证了这一阶段定位:它被命名为 "Pass 3: Encoding Preparation",负责把 MIR 编码为 wire format。
Wire Format 的紧凑编码细节
Wire format 的完整字节级规范记录在 packages/@glimmer/compiler/lib/wire-encoding.md(以及 @glimmer/wire-format 包中)。其核心设计是:整个 wire format 只使用 JSON 字符串中合法的字符(0-9、A-Z、a-z 与少量标点),每个字符默认编码 6 个比特位(0x00–0x3F),剩余字符(0x40–0x5A)用于表示 0–90 的独立数值及高位标志。
值得注意的编码策略包括:
- 字符串:以
"结尾的原始字符序列;若字符串是 interned(出现在 interned strings 区),则用一个位置号引用,位置 < 90 时用单个字面数字编码; - 数字:0–90 用单个字符直接编码;更大的数字按 6 位一组切分、以
0x5A(~)终止。例如数字 1000 编码为xFe~,123456789 编码为x7MyqL~(比原始十进制数字符串还短); - 程序结构:
<flags> | <offset> | <strings> | <offset> | <symbols> | (upvars) | <statements>,其中 flags 的第 4 位指示是否存在 upvars 区; - 表达式:首个字节携带 6 个布尔标志,
flag0为1表示 primitive(布尔/字符串/数字/null/undefined),为0表示 tuple 型表达式(GetSymbol、GetFreeWithContext、GetPath、Concat、Call等); - 语句列表:以
111000(即字符u)作为终止符。
wire-encoding.md 还给出了一个完整的端到端示例——Glimmer Playground 的按钮模板经过编码后,upvars 区收集到 ["count", "action", "increment"],整个模板最终编码为一串 2qcount"qaction"qincrement"Iqh1"8q... 形式的紧凑文本,与 precompile 产出的 SerializedTemplateBlock 三元组结构一一对应。
严格模式(Strict Mode)与未来演进
PASSES.md 明确指出当前实现的两个边界:
- 严格模式下的 upvars 绑定尚未实现。文档原文:In strict mode, encoded templates will need to be emitted into a JavaScript file containing variable bindings that correspond to each of the upvars. This is not yet implemented. 即:在严格模式下,编码后的模板未来需要被发射为包含与各 upvar 对应的变量绑定的 JavaScript 文件。尽管如此,严格模式相关的管道已经部分就绪——例如 Normalization 阶段在
isStrict为真时会额外执行StrictModeValidationPass.validate(template)(见 passes/1-normalization/index.ts),precompileJSON也会把strictMode选项一路透传(见 compiler.ts)。 - 编码器可替换性。文档原文:In the future, it will be possible to replace the encoder with an arbitrary encoding pass, provided that you supply a runtime decoder. 即未来允许用任意编码 pass 替换当前硬编码的编码器,前提是配套提供对应的运行时解码器。这一设计意图与当前代码结构是吻合的:
precompileJSON中pass0与pass2通过Result组合子(mapOk)串接,pass 之间以明确的 IR 类型为契约(见 compiler.ts),替换任意一环都不影响整条管线的骨架。
延伸阅读指引
如果想进一步深入这条编译管线,仓库内以下文件是推荐的切入点:
- packages/@glimmer/compiler/lib/compiler.ts:
precompile/precompileJSON入口,展示整条管线的串联方式; - packages/@glimmer/compiler/lib/passes/1-normalization/README.md:Pass 0 的完整伪算法(表达式、语句、参数、hash pair 的归一化规则);
- packages/@glimmer/compiler/lib/passes/2-encoding/mir.ts:MIR 全部节点类型定义,是理解"编码前的 wire format"的最佳索引;
- packages/@glimmer/compiler/lib/wire-encoding.md:wire format 的字节级编码规范与完整示例;
- packages/@glimmer/compiler/lib/passes/1-normalization/visitors/statements.ts 与 passes/1-normalization/keywords:语句访问器与关键词翻译的具体实现。
小结
Glimmer 预处理器通过 Normalization → Symbol Allocation → Encoding 三个阶段,将 @glimmer/syntax 产出的 AST v2 逐级降维为 Wire Format:先归整语法形态并分离关键词(AST → HIR),再用唯一符号取代字符串绑定以摆脱作用域栈(HIR → MIR),最后把带源偏移的 MIR 指令紧凑打包为可传输的序列化块(MIR → Wire Format)。在当前代码中,这三个概念阶段以 1-normalization 与 2-encoding 两个实际 pass 呈现,符号分配内嵌于 Normalization 过程,最终由 precompile / precompileJSON 组装为带元信息(id、moduleName、scope、isStrictMode)的模板 JavaScript。理解这条管道,是深入 Ember.js 模板编译、调试模板产物乃至未来扩展自定义编码器的前提。