深入理解 TypeScript 编译器:绑定器(Binder)与符号系统的源码级解析
深入理解 TypeScript 编译器:绑定器(Binder)与符号系统的源码级解析
本篇指南聚焦《TypeScript Deep Dive 中文版》(typescript-book-chinese)编译器中"绑定器(Binder)"一章的核心脉络,系统讲解绑定器如何为检查器搭建 TypeScript 的语义系统:从符号(Symbol)的创建、绑定器关键函数(
bindSourceFile/bind/bindWorker)到容器(Container)、符号表(SymbolTable)与绑定期错误报告,并结合本仓库 docs/compiler 目录下的 概览、AST、检查器、程序 等配套章节交叉印证。读完本文,你将理解Program.getTypeChecker之后发生了什么、符号与声明如何相互连接、容器标志如何决定符号归属,以及为什么绑定期就能提前发现eval/arguments在严格模式下的误用。
为什么需要绑定器:转译器与语义系统的分水岭
大多数 JavaScript 转译器(transpiler)都比 TypeScript 简单,因为它们几乎不提供代码分析的方法。典型的 JavaScript 转换器只有以下流程:
源码 ~~扫描器~~> Tokens ~~解析器~~> AST ~~发射器~~> JavaScript
上述架构对理解"TypeScript 如何生成 JavaScript"有帮助,但它缺失了一个关键功能——TypeScript 的语义系统。为了让(检查器执行的)类型检查得以进行,绑定器把源码的各部分连接成一个相关的类型系统,供检查器使用。绑定器的主要职责是创建符号(Symbols)。
本仓库 编译器概览 中给出了完整处理链,直观地展示了绑定器在整个流水线中的位置:
SourceCode(源码) ~~ 扫描器 ~~> Token 流
Token 流 ~~ 解析器 ~~> AST(抽象语法树)
AST ~~ 绑定器 ~~> Symbols(符号)
AST + 符号 ~~ 检查器 ~~> 类型验证
AST + 检查器 ~~ 发射器 ~~> JavaScript 代码
可以看到,扫描器、解析器负责"语法",而"语义"是从绑定器开始的:符号(Symbol)是 TypeScript 语义系统的主要构造块,符号是绑定的结果。符号将 AST 中的声明节点与相同实体的其他声明相连,之后符号和 AST 一起被检查器用来验证源代码语义。
值得注意的是,本仓库的 概览 有一处译注提醒读者:《TypeScript Deep Dive》使用的源码为 2016 年以前的源码,学习时应对照现有的 TypeScript 源码。因此本文对函数名、调用链的讨论适用于该书所对应的编译器架构,具体实现细节以你所对照的 TypeScript 版本源码为准。
符号(Symbol):语义系统的基本构造块
符号将 AST 中的声明节点与其他声明连接到相同的实体上。例如,一个 var 声明与多个 function 声明可能指向同一个"实体",绑定器会为它们创建/合并同一个符号,后续检查器才能判断它们是否兼容、是否重复声明。
符号的构造器定义在 core.ts(绑定器实际上通过 objectAllocator.getSymbolConstructor 来获取构造器)。objectAllocator 是一个定义为全局单例的变量,本仓库 概览 中列出了它提供的四个构造器获取函数:getNodeConstructor(节点,在解析器/AST 中介绍)、getSymbolConstructor(符号,即本节)、getTypeConstructor(类型,在检查器中介绍)、getSignatureConstructor(签名:索引、调用和构造签名)。下面是符号构造器:
function Symbol(flags: SymbolFlags, name: string) {
this.flags = flags;
this.name = name;
this.declarations = undefined;
}
SymbolFlags 符号标志是个标志枚举,用于识别额外的符号类别,例如变量作用域标志 FunctionScopedVariable 或 BlockScopedVariable 等。正是靠这些标志,同一符号表中 var x 与 let x 才能被区分对待(后文 declareSymbol 与容器章节会看到它们如何影响冲突检测)。
一个符号的典型形态:
| 成员 | 含义 |
|---|---|
flags: SymbolFlags |
符号类别标志,如值/类型/命名空间、作用域类别 |
name: string |
符号名称,如变量名、类名、default 等 |
declarations?: Declaration[] |
声明该符号的 AST 节点列表(一个符号可对应多个声明,例如声明合并) |
members? / exports? |
成员符号表 / 导出符号表(后文符号表一节详述) |
检查器对绑定器的使用:绑定发生在哪里
实际上,绑定器被检查器在内部调用,而检查器又被程序调用。本仓库 检查器 一节展示了完全相同的调用栈,简化的调用栈如下:
program.getTypeChecker ->
ts.createTypeChecker(检查器中)->
initializeTypeChecker(检查器中) ->
for each SourceFile `ts.bindSourceFile`(绑定器中)
// followed by
for each SourceFile `ts.mergeSymbolTable`(检查器中)
要点:
- SourceFile 是绑定器的工作单元,
binder.ts由checker.ts驱动; - 每个源文件先经过
bindSourceFile完成绑定,随后检查器用mergeSymbolTable把各文件的locals合并进全局符号表等更大的表中; - 结合 程序 一章可知,
Program持有SourceFile列表与编译选项,Program.getTypeChecker是这条链路的入口。
这也解释了为什么说"绑定器是检查器内部的一个环节":它并不独立暴露给用户,而是类型检查启动时被自动触发的初始化步骤。
绑定器函数剖析
bindSourceFile 和 mergeSymbolTable 是两个关键入口,但前者是绑定器自己的函数,后者属于检查器。绑定器内部的实际工作由一组本地函数完成。
bindSourceFile
该函数主要是检查 file.locals 是否已定义,如果没有则交给(本地函数)bind 来处理。
注意:
locals定义在节点上,其类型为SymbolTable;SourceFile本身也是一个节点——事实上它是 AST 中的根节点(本仓库 AST 一章确认了SourceFile是SyntaxKind.SourceFile,每棵 AST 的顶级节点)。
提示:TypeScript 编译器大量使用本地函数。本地函数很可能使用来自父函数的变量(通过闭包捕获)。例如 bind 是 bindSourceFile 中的一个本地函数,它或它调用的函数会设置 symbolCount 和 classifiableNames 等状态,然后将其存到返回的 SourceFile 中。
bind
bind 能处理任一节点(不只是 SourceFile),它做的第一件事是分配 node.parent(如果 parent 变量已设置,绑定器在 bindChildren 函数的处理中仍会再次设置),然后交给 bindWorker 做很多重活。最后调用 bindChildren——该函数简单地将绑定器的状态(如 parent)存入函数本地变量中,接着在每个子节点上调用 bind,然后再将状态转存回绑定器中。
bindWorker
该函数依据 node.kind(SyntaxKind 类型)进行切换,并将工作委托给合适的 bindXXX 函数(也定义在 binder.ts 中)。例如:如果该节点是 SourceFile,则(最终且仅当节点是外部文件模块时)调用 bindAnonymousDeclaration。
关于 SyntaxKind:本仓库 AST 一节说明它是一个常量枚举,编译器据此内联数值,便于在 AST 处理中零开销地做 kind 判断——bindWorker 的 switch 正是这种常量枚举的典型消费场景。
bindXXX 函数
bindXXX 系函数有一些通用的模式和工具函数,其中最常用的一个是 createSymbol,全部代码展示如下:
function createSymbol(flags: SymbolFlags, name: string): Symbol {
symbolCount++;
return new Symbol(flags, name);
}
如您所见,它简单地更新 symbolCount(一个 bindSourceFile 的本地变量),并使用指定的参数创建符号。symbolCount 最终被写回 SourceFile,可用于统计与调试。
绑定器声明:把节点和符号链接起来
符号与声明
节点和符号间的链接由几个函数执行。其中一个用于绑定 SourceFile 节点到源文件符号(外部模块的情况下)的函数是 addDeclarationToSymbol。
注意:外部模块源文件的符号设置方式是 flags: SymbolFlags.ValueModule 和 name: '"' + removeFileExtension(file.fileName) + '"'——也就是说,一个外部模块文件在符号表中以带引号的、去掉扩展名的文件名作为名字注册为一个"值模块"。
function addDeclarationToSymbol(symbol: Symbol, node: Declaration, symbolFlags: SymbolFlags) {
symbol.flags |= symbolFlags;
// 创建 AST 节点到 symbol 的连接
node.symbol = symbol;
if (!symbol.declarations) {
symbol.declarations = [];
}
// 将该节点添加为该符号的一个声明
symbol.declarations.push(node);
if (symbolFlags & SymbolFlags.HasExports && !symbol.exports) {
symbol.exports = {};
}
if (symbolFlags & SymbolFlags.HasMembers && !symbol.members) {
symbol.members = {};
}
if (symbolFlags & SymbolFlags.Value && !symbol.valueDeclaration) {
symbol.valueDeclaration = node;
}
}
上述代码主要执行的操作如下:
- 合并符号标志:
symbol.flags |= symbolFlags,把新声明携带的标志并入既有符号; - 创建一个从 AST 节点到符号的链接(
node.symbol); - 将节点添加为该符号的一个声明(
symbol.declarations.push(node)),一个符号可以累积多个声明,这正是声明合并(declaration merging)的数据基础; - 按标志惰性初始化
exports、members符号表,并记录首个valueDeclaration(值声明)。
声明(Declaration)
声明就是一个有可选名字的节点。下面是 types.ts 中的定义:
interface Declaration extends Node {
_declarationBrand: any;
name?: DeclarationName;
}
Declaration 继承自 Node,而 Node 的关键成员在本仓库 AST 一节有专门介绍:TextRange 标识节点在源文件中的起止位置,parent?: Node 指向 AST 中的父节点。绑定器对 node.parent 的赋值正是填充后者的关键路径。
绑定器容器:符号表归属的判定依据
AST 的节点可以被当作容器。这决定了节点及相关符号的 SymbolTables 的类别。容器是个抽象概念(没有相关的数据结构)。该概念由一些东西决定,ContainerFlags 枚举是其中之一。函数 getContainerFlags(位于 binder.ts)驱动此标志,如下所示:
function getContainerFlags(node: Node): ContainerFlags {
switch (node.kind) {
case SyntaxKind.ClassExpression:
case SyntaxKind.ClassDeclaration:
case SyntaxKind.InterfaceDeclaration:
case SyntaxKind.EnumDeclaration:
case SyntaxKind.TypeLiteral:
case SyntaxKind.ObjectLiteralExpression:
return ContainerFlags.IsContainer;
case SyntaxKind.CallSignature:
case SyntaxKind.ConstructSignature:
case SyntaxKind.IndexSignature:
case SyntaxKind.MethodDeclaration:
case SyntaxKind.MethodSignature:
case SyntaxKind.FunctionDeclaration:
case SyntaxKind.Constructor:
case SyntaxKind.GetAccessor:
case SyntaxKind.SetAccessor:
case SyntaxKind.FunctionType:
case SyntaxKind.ConstructorType:
case SyntaxKind.FunctionExpression:
case SyntaxKind.ArrowFunction:
case SyntaxKind.ModuleDeclaration:
case SyntaxKind.SourceFile:
case SyntaxKind.TypeAliasDeclaration:
return ContainerFlags.IsContainerWithLocals;
case SyntaxKind.CatchClause:
case SyntaxKind.ForStatement:
case SyntaxKind.ForInStatement:
case SyntaxKind.ForOfStatement:
case SyntaxKind.CaseBlock:
return ContainerFlags.IsBlockScopedContainer;
case SyntaxKind.Block:
// 不要将函数内部的块直接当做块作用域的容器。
// 本块中的本地变量应当置于函数中,否则下例中的 'x' 不会重新声明为一个块作用域的本地变量:
//
// function foo() {
// var x;
// let x;
// }
//
// 如果将 'var x' 留在函数中,而将 'let x' 放到本块中(函数外),就不会有冲突了。
//
// 如果不在这里创建一个新的块作用域容器,'var x' 和 'let x' 都会进入函数容器本地中,这样就会有碰撞冲突。
return isFunctionLike(node.parent) ? ContainerFlags.None : ContainerFlags.IsBlockScopedContainer;
}
return ContainerFlags.None;
}
这段 switch 蕴含了关键的作用域规则:
IsContainer:类、接口、枚举、类型字面量、对象字面量等形成命名空间级别的容器,其成员进入symbol.members;IsContainerWithLocals:函数、方法、构造函数、getter/setter、箭头函数、模块声明、SourceFile等容器同时拥有本地变量表(locals);IsBlockScopedContainer:catch子句、for系语句、case块等形成块级作用域;Block的特判:函数内部的块不直接作为块级容器,否则var x; let x;会被错误地放到不同容器而漏报冲突;只有非函数直系的块(如if的块)才作为块作用域容器。
getContainerFlags 该函数只在绑定器函数 bindChildren 中调用,会根据运行结果将节点设为 container 和(或)blockScopeContainer。函数 bindChildren 如下所示:
// 所有容器节点都以声明顺序保存在一个链表中。
// 类型检查器中的 getLocalNameOfContainer 函数会使用该链表对容器使用的本地名称的唯一性做验证。
function bindChildren(node: Node) {
// 在递归到子节点之前,我们先要保存父节点,容器和块容器。处理完弹出的子节点后,再将这些值存回原处。
let saveParent = parent;
let saveContainer = container;
let savedBlockScopeContainer = blockScopeContainer;
// 现在要将这个节点设为父节点,我们要递归它的子节点。
parent = node;
// 根据节点的类型,需要对当前容器或块容器进行调整。 如果当前节点是个容器,则自动将其视为当前的块容器。
// 由于我们知道容器可能包含本地变量,因此提前初始化 .locals 字段。
// 这样做是因为很可能需要将一些子(节点)置入 .locals 中(例如:函数参数或变量声明)。
//
// 但是,我们不会主动为块容器创建 .locals,因为通常块容器中不会有块作用域变量。
// 我们不想为遇到的每个块都分配一个对象,大多数情况没有必要。
//
// 最后,如果是个块容器,我们就清理该容器中可能存在的 .locals 对象。这种情况常在增量编译场景中发生。
// 由于我们可以重用上次编译的节点,而该节点可能已经创建了 locals 对象。
// 因此必须清理,以免意外地从上次的编译中移动了过时的数据。
let containerFlags = getContainerFlags(node);
if (containerFlags & ContainerFlags.IsContainer) {
container = blockScopeContainer = node;
if (containerFlags & ContainerFlags.HasLocals) {
container.locals = {};
}
addToContainerChain(container);
} else if (containerFlags & ContainerFlags.IsBlockScopedContainer) {
blockScopeContainer = node;
blockScopeContainer.locals = undefined;
}
forEachChild(node, bind);
container = saveContainer;
parent = saveParent;
blockScopeContainer = savedBlockScopeContainer;
}
三个值得展开的设计细节:
- 状态保存/恢复:
bindChildren在递归前把parent/container/blockScopeContainer存入本地变量,递归结束后恢复,保证兄弟子树互不污染; - 惰性分配
locals:容器节点才初始化locals = {}(因为函数参数、变量声明大概率要放进来),而块容器只清空locals = undefined,避免为每个Block都分配一个对象,这是明显的性能考量; - 容器链表:所有容器节点按声明顺序保存在一个链表中(
addToContainerChain),检查器中的getLocalNameOfContainer会使用该链表验证容器使用的本地名称的唯一性。
您可能还记得:bindChildren 由 bind 函数调用。我们得到这样的递归绑定:bind 调用 bindChildren,而 bindChildren 又通过 forEachChild(本仓库 AST 一节介绍的工具函数,用于访问任一节点的所有子节点)为其每个子节点调用 bind。
绑定器符号表:HashMap 形式的名称到符号映射
符号表(SymbolTable)以简单的 HashMap 实现,下面是其接口(types.ts):
interface SymbolTable {
[index: string]: Symbol;
}
符号表通过绑定进行初始化,以下是编译器使用的一些符号表:
节点上:
locals?: SymbolTable; // 节点相关的本地变量
符号上:
members?: SymbolTable; // 类,接口或字面量实例成员
exports?: SymbolTable; // 模块导出
请注意:bindChildren 基于 ContainerFlags 初始化 locals(为 {})。
结合前文可以画出完整的归属关系:函数参数、局部变量进入容器节点的 locals;类的实例成员进入符号的 members;静态成员与模块导出进入符号的 exports(见下文 declareClassMember)。
符号表填充:declareSymbol
符号表使用符号来填充,主要是通过调用 declareSymbol 来进行,如下所示的是该函数的全部代码:
/**
* 为指定的节点声明一个符号并加入 symbols。标识名冲突时报告错误。
* @param symbolTable - 要将节点加入进的符号表
* @param parent - 指定节点的父节点的声明
* @param node - 要添加到符号表的(节点)声明
* @param includes - SymbolFlags,指定节点额外的声明类型(例如:export, ambient 等)
* @param excludes - 不能在符号表中声明的标志,用于报告禁止的声明
*/
function declareSymbol(
symbolTable: SymbolTable,
parent: Symbol,
node: Declaration,
includes: SymbolFlags,
excludes: SymbolFlags
): Symbol {
Debug.assert(!hasDynamicName(node));
// 默认导出的函数节点或类节点的符号总是"default"
let name = node.flags & NodeFlags.Default && parent ? 'default' : getDeclarationName(node);
let symbol: Symbol;
if (name !== undefined) {
// 检查符号表中是否已有同名的符号。若没有,创建此名称的新符号并加入表中。
// 注意,我们尚未给新符号指定任何标志。这可以确保不会和传入的 excludes 标志起冲突。
//
// 如果已存在的一个符号,查看是否与要创建的新符号冲突。
// 例如:同一符号表中,'var' 符号和 'class' 符号会冲突。
// 如果有冲突,报告该问题给该符号的每个声明,然后为该声明创建一个新符号
//
// 如果我们创建的新符号既没在符号表中重名也没和现有符号冲突,就将该节点添加为新符号的唯一声明。
//
// 否则,就要(将新符号)合并进兼容的现有符号中(例如同一容器中有多个同名的 'var' 时)。这种情况下要把该节点添加到符号的声明列表中。
symbol = hasProperty(symbolTable, name)
? symbolTable[name]
: (symbolTable[name] = createSymbol(SymbolFlags.None, name));
if (name && includes & SymbolFlags.Classifiable) {
classifiableNames[name] = name;
}
if (symbol.flags & excludes) {
if (node.name) {
node.name.parent = node;
}
// 报告每个重复声明的错误位置
// 报告之前遇到的声明错误
let message =
symbol.flags & SymbolFlags.BlockScopedVariable
? Diagnostics.Cannot_redeclare_block_scoped_variable_0
: Diagnostics.Duplicate_identifier_0;
forEach(symbol.declarations, declaration => {
file.bindDiagnostics.push(
createDiagnosticForNode(declaration.name || declaration, message, getDisplayName(declaration))
);
});
file.bindDiagnostics.push(createDiagnosticForNode(node.name || node, message, getDisplayName(node)));
symbol = createSymbol(SymbolFlags.None, name);
}
} else {
symbol = createSymbol(SymbolFlags.None, '__missing');
}
addDeclarationToSymbol(symbol, node, includes);
symbol.parent = parent;
return symbol;
}
declareSymbol 的逻辑可以归纳为四步决策:
- 确定名称:默认导出的函数/类节点符号名恒为
"default",否则取getDeclarationName(node);动态命名(hasDynamicName)在此被断言排除; - 查表或建表:符号表中已有同名符号则复用,否则用
createSymbol(SymbolFlags.None, name)新建(先不设标志,避免与excludes冲突); - 冲突检测:若既有符号的标志命中了
excludes(例如同一符号表中var与class同名),则对既有声明的每一处和当前节点都生成诊断(块级变量报Cannot_redeclare_block_scoped_variable_0,其余报Duplicate_identifier_0),并另建新符号继续后续流程; - 登记声明:调用
addDeclarationToSymbol把节点挂到符号上,并设置symbol.parent。
填充哪个符号表,由 declareSymbol 的第一个参数决定。例如:添加声明到类型为 SyntaxKind.ClassDeclaration 或 SyntaxKind.ClassExpression 的容器时,将会调用下面的函数 declareClassMember:
function declareClassMember(node: Declaration, symbolFlags: SymbolFlags, symbolExcludes: SymbolFlags) {
return node.flags & NodeFlags.Static
? declareSymbol(container.symbol.exports, container.symbol, node, symbolFlags, symbolExcludes)
: declareSymbol(container.symbol.members, container.symbol, node, symbolFlags, symbolExcludes);
}
这里可以看到容器与符号表的配合:静态成员(NodeFlags.Static)进入 container.symbol.exports,普通实例成员进入 container.symbol.members。这与前面符号表一节列出的 members(类/接口/字面量实例成员)和 exports(模块导出)一一对应。
绑定器错误报告:bindDiagnostics 与严格模式检查
绑定错误被添加到源文件的 bindDiagnostics 列表中,这些诊断会在绑定阶段直接产生,先于类型检查。
一个绑定时错误检测的例子是在严格模式下使用 eval 或 arguments 作为变量名。下面展示了相关的全部代码(多个位置都会调用 checkStrictModeEvalOrArguments,调用栈发自 bindWorker,该函数对不同节点的 SyntaxKind 调用不同的检查函数):
function checkStrictModeEvalOrArguments(contextNode: Node, name: Node) {
if (name && name.kind === SyntaxKind.Identifier) {
let identifier = <Identifier>name;
if (isEvalOrArgumentsIdentifier(identifier)) {
// 首先检查名字是否在类声明或者类表达式中,如果是则给出明确消息,否则报告一般性错误
let span = getErrorSpanForNode(file, name);
file.bindDiagnostics.push(
createFileDiagnostic(
file,
span.start,
span.length,
getStrictModeEvalOrArgumentsMessage(contextNode),
identifier.text
)
);
}
}
}
function isEvalOrArgumentsIdentifier(node: Node): boolean {
return (
node.kind === SyntaxKind.Identifier &&
((<Identifier>node).text === 'eval' || (<Identifier>node).text === 'arguments')
);
}
function getStrictModeEvalOrArgumentsMessage(node: Node) {
// 向用户提供特定消息,有助他们理解为何会处于严格模式。
if (getContainingClass(node)) {
return Diagnostics.Invalid_use_of_0_Class_definitions_are_automatically_in_strict_mode;
}
if (file.externalModuleIndicator) {
return Diagnostics.Invalid_use_of_0_Modules_are_automatically_in_strict_mode;
}
return Diagnostics.Invalid_use_of_0_in_strict_mode;
}
这段代码展示了绑定器错误报告的完整链路:
bindWorker依据SyntaxKind分发到相应检查函数;checkStrictModeEvalOrArguments只处理标识符节点,命中eval/arguments后定位错误跨度(getErrorSpanForNode)并把诊断推进file.bindDiagnostics;getStrictModeEvalOrArgumentsMessage依据上下文给出不同提示:位于类定义中(类定义自动处于严格模式)、位于外部模块中(模块自动处于严格模式)分别给出专属文案,否则给一般性的严格模式文案。
这说明绑定器不只是"建符号",它还顺带完成了一批可以脱离类型信息独立判定的静态错误检查,让错误更早、更精准地暴露出来。
从绑定器到检查器:阅读路径小结
绑定器在 TypeScript 编译器流水线中的角色可以一句话概括:把语法树(AST)翻译成语义图(符号及符号表),为检查器提供类型检查所需的数据结构。整个环节由检查器初始化时驱动(ts.bindSourceFile),与检查器自身的 mergeSymbolTable 交替完成全局符号合并;本仓库 检查器 一节对该调用栈有同款记录,可对照阅读。
若想继续沿编译器流水线深入,建议按以下顺序阅读本仓库相关章节:
- 编译器概览:整条扫描 → 解析 → 绑定 → 检查 → 发射的流水线及各工具文件(
core.ts、types.ts、system.ts)的定位; - 扫描器 与 解析器:理解
Tokens与AST如何产生,其中ts.forEachChild、SyntaxKind常量枚举是绑定器代码的基础设施; - AST:
Node、SourceFile、SyntaxKind与子节点遍历 API,是理解绑定器"在节点上递归"的前提; - 程序:
Program、CompilerHost、SourceFile的关系,即绑定发生的宿主环境; - 检查器:消费符号与符号表的下一站,以及
mergeSymbolTable合并全局符号的实现背景。
绑定器的价值在于它把"名字"组织成了"实体":同名声明合并为同一符号、不同作用域分属不同符号表、冲突在绑定期即被标记。理解了这一层,你就掌握了阅读检查器类型推断与错误报告源码的钥匙。