TypeScript声明合并详解：接口、命名空间与模块扩展

基础概念

TypeScript 中的声明主要创建三种实体：命名空间、类型或值。理解每种声明创建的实体类型，是掌握声明合并机制的前提：

• 创建命名空间：新建一个命名空间，包含可通过 . 符号访问的名字。
• 创建类型：基于声明的模型创建一个类型并绑定到给定名字上。
• 创建值：在 JavaScript 输出中实际生成的运行时代码。

// 各声明类型对应的实体映射
// Namespace:   命名空间(X), 类型(X)
// Class:       命名空间( ), 类型(X), 值(X)
// Enum:        命名空间( ), 类型(X), 值(X)
// Interface:   命名空间( ), 类型(X)
// Type Alias:  命名空间( ), 类型(X)
// Function:    命名空间( ), 类型( ), 值(X)
// Variable:    命名空间( ), 类型( ), 值(X)

合并接口

接口合并是最常见且最简单的形式。其核心机制是将所有同名接口（interface）的成员放入同一个接口定义中。

第1步：处理非函数成员

同名接口中的非函数成员必须保持一致。若存在多个同名非函数成员，它们的类型必须相同；否则编译器将报错。

interface Box {
    height: number;
    width: number;
}

interface Box {
    scale: number;
}

let box: Box = {height: 5, width: 6, scale: 10}; // 成功合并

第2步：处理函数成员（重载）

同名函数声明会被视为该函数的重载。合并时，后续定义的接口具有更高的优先级，因此其重载签名会排在前面。但在每组内部，声明顺序保持不变。

interface Cloner {
    clone(animal: Animal): Animal;
}

interface Cloner {
    clone(animal: Sheep): Sheep;
}

interface Cloner {
    clone(animal: Dog): Dog;
    clone(animal: Cat): Cat;
}

上述代码合并后的结果为：

interface Cloner {
    clone(animal: Dog): Dog;    // 来自第三个接口
    clone(animal: Cat): Cat;    // 来自第三个接口
    clone(animal: Sheep): Sheep; // 来自第二个接口
    clone(animal: Animal): Animal; // 来自第一个接口
}

第3步：特殊字符串字面量签名优先级

如果函数签名中包含单一的字符串字面量参数（如