---

TypeScript 接口详解：定义契约，构建健壮应用

在软件开发的世界里，尤其是构建大型或协作项目时，定义清晰的结构和契约至关重要。这有助于提高代码的可读性、可维护性，并减少潜在的错误。在 TypeScript 中，接口（Interfaces）正是扮演了这样的角色。它们是 TypeScript 中一个核心且强大的特性，用于定义对象的形状（Shape），为变量、函数、类等定义必须遵守的契约。

本文将深入探讨 TypeScript 接口的各个方面，从基本语法到高级用法，并与相关的概念（如类型别名）进行比较，帮助你全面掌握接口的强大能力。

1. 什么是接口？为什么需要接口？

在 JavaScript 中，对象通常是灵活且动态的。你可以随时向一个对象添加或删除属性和方法。这种灵活性是 JavaScript 的一大特点，但也带来了潜在的问题：在代码运行之前，你无法确定一个对象到底有哪些属性，它们的类型是什么。这在大型应用中很容易导致运行时错误。

TypeScript 的核心目标之一就是为 JavaScript 添加静态类型系统，以便在开发阶段就能捕获类型错误。接口就是实现这一目标的关键工具之一。

接口的作用：

1. 定义对象的形状（Shape）： 接口最常见的用途是描述一个拥有某些属性和方法的对象应该是什么样子。它定义了对象必须包含哪些成员，以及这些成员的类型。
2. 建立契约： 接口可以被变量、函数参数、函数返回值、类等“实现”或“遵循”，从而建立一种契约关系。一旦一个变量或类被声明遵循某个接口，TypeScript 编译器就会检查它是否满足接口定义的所有要求。
3. 提高代码可读性和可维护性： 通过接口，你可以清晰地表达代码中期望的数据结构。这使得代码更易于理解，也更容易在未来进行修改和维护。
4. 支持面向对象编程： 接口是面向对象设计中的重要概念，TypeScript 允许类实现接口，从而实现多态性。
5. 描述函数类型： 接口不仅能描述对象，还能描述函数的形状。
6. 描述索引签名类型： 接口可以用来描述那些可以通过索引（数字或字符串）访问其属性的对象，如数组或字典。

简单来说，接口就像一份蓝图或一个模具，规定了符合这个接口的对象必须具备哪些特征。它只关注结构（Structure），不关注具体的实现（Implementation）。

2. 基本语法与对象接口

定义一个接口非常简单，使用 interface 关键字后跟接口名称，然后是花括号 {} 包围的成员列表。

“`typescript
interface Person {
name: string;
age: number;
}

// 使用接口作为变量的类型注解
let user: Person = {
name: “张三”,
age: 30,
};

// 如果对象缺少或多出接口定义的属性，或者属性类型不匹配，TypeScript 会报错
// let invalidUser: Person = { name: “李四” }; // 错误：缺少 age 属性
// let anotherInvalidUser: Person = { name: “王五”, age: 25, gender: “male” }; // 错误：多出 gender 属性（当对象字面量直接赋值给接口类型变量时，会进行额外属性检查）
// let typeMismatchUser: Person = { name: “赵六”, age: “thirty” }; // 错误：age 属性类型不匹配
“`

在上面的例子中，我们定义了一个 Person 接口，它要求任何实现该接口的对象必须有一个 name 属性（类型为 string）和一个 age 属性（类型为 number）。当我们声明一个变量 user 并指定其类型为 Person 时，TypeScript 就会检查赋值给 user 的对象字面量是否符合 Person 接口的形状。

需要注意的是，当直接使用对象字面量赋值给一个接口类型的变量时，TypeScript 会进行严格的属性检查，不允许出现接口中未定义的属性。然而，如果对象是通过变量赋值或函数返回等方式获得的，则只会检查必需的属性是否存在且类型正确。

“`typescript
interface Person {
name: string;
age: number;
}

let personLiteral = { name: “钱七”, age: 40, city: “北京” };

// 这里不会报错，因为 personLiteral 已经存在，TypeScript 只检查它是否“至少”满足 Person 接口的要求
let validPerson: Person = personLiteral;

// 但如果你直接写对象字面量就会报错
// let anotherPerson: Person = { name: “孙八”, age: 50, occupation: “Engineer” }; // 错误
“`
这种被称为“Excess Property Checks”（额外属性检查）的行为，主要发生在对象字面量直接赋值时，旨在防止输入错误或拼写错误导致的潜在问题。

3. 可选属性（Optional Properties）

有时，接口中的某些属性不是必需的。你可以使用 ? 符号来标记可选属性。

“`typescript
interface Config {
url: string;
method?: “GET” | “POST” | “PUT” | “DELETE”; // method 是可选的
headers?: { [key: string]: string }; // headers 也是可选的，且其值是一个键为字符串、值为字符串的对象
data?: any;
}

function fetchData(config: Config) {
const method = config.method || “GET”; // 如果 method 未提供，则默认为 GET
console.log(Fetching ${config.url} using ${method});
if (config.headers) {
console.log(“Headers:”, config.headers);
}
if (config.data) {
console.log(“Data:”, config.data);
}
// … 实际的网络请求逻辑
}

// 调用时可以只提供必需的 url 属性
fetchData({ url: “/api/users” });

// 也可以提供可选属性
fetchData({
url: “/api/posts”,
method: “POST”,
data: { title: “New Post”, content: “…” },
});
“`

可选属性使得接口更加灵活，可以描述那些可能存在或不存在特定属性的对象。

4. 只读属性（Readonly Properties）

如果你希望对象的一些属性在创建后不能被修改，可以使用 readonly 关键字将其标记为只读属性。

“`typescript
interface Point {
readonly x: number;
readonly y: number;
}

let p1: Point = { x: 10, y: 20 };

// p1.x = 5; // 错误：无法分配到 “x” ，因为它是只读属性

// 但是，如果你有一个包含只读属性的对象，你可以将其完全替换
p1 = { x: 30, y: 40 }; // 允许

// 注意：readonly 只确保属性本身不能被重新赋值。如果属性的值是对象或数组，该对象/数组内部的内容仍然是可变的，除非其内部也被标记为只读或使用 Readonly 工具类型。
interface Settings {
readonly options: string[]; // options 属性本身不能被重新赋值为新的数组
}

let settings: Settings = { options: [“a”, “b”] };
// settings.options = [“c”]; // 错误
settings.options.push(“c”); // 允许！因为 push 修改的是数组的内容，而不是 options 属性本身
“`

readonly 适用于希望确保对象的某些部分在初始化后保持不变的场景，例如配置对象、坐标点等。

与 readonly 属性相关的还有一个内置的工具类型 Readonly<T>。它会创建一个新类型，将 T 中的所有属性都标记为只读。

“`typescript
interface Todo {
title: string;
completed: boolean;
}

type ReadonlyTodo = Readonly;

let todo: ReadonlyTodo = {
title: “Learn TypeScript”,
completed: false,
};

// todo.title = “Learn Interfaces”; // 错误：无法分配到 “title” ，因为它是只读属性
“`

readonly 关键字用于接口或类型别名中的单个属性，而 Readonly<T> 工具类型用于快速将一个现有类型的所有属性变为只读。

5. 函数类型接口

接口不仅能描述普通对象，还能描述函数的形状。一个函数类型接口包含一个调用签名（Call Signature），指定了函数的参数列表和返回值类型。

“`typescript
interface SearchFunc {
(source: string, subString: string): boolean;
}

// 实现这个接口的函数必须接受两个字符串参数，并返回一个布尔值
let mySearch: SearchFunc;

mySearch = function (src: string, sub: string): boolean {
const result = src.search(sub);
return result > -1;
};

// 如果参数或返回值类型不匹配，会报错
// mySearch = function(src: string, sub: number): boolean { // 错误：参数类型不匹配
// const result = src.search(sub.toString());
// return result > -1;
// };

// 参数名可以不同，只要类型对应即可
let anotherSearch: SearchFunc;
anotherSearch = function (sourceString: string, searchString: string): boolean {
return sourceString.includes(searchString);
};
“`

函数类型接口在定义回调函数类型、或者描述库中某个函数变量的类型时非常有用，它为函数的输入和输出定义了明确的契约。

6. 索引签名接口（Indexable Types）

有些对象或类型，你并不提前知道它们会有哪些属性名，但你知道它们可以通过索引访问，并且知道通过索引访问时得到的值的类型。这种类型可以通过索引签名来描述。索引签名有两种：字符串索引签名和数字索引签名。

6.1 字符串索引签名

用于描述那些键是字符串的对象，比如字典或哈希表。

“`typescript
interface StringDictionary {
[key: string]: string; // 键是任意字符串，值是字符串
// 可以同时有已知属性，但已知属性的类型必须与索引签名的值类型兼容
name?: string; // 这里的 name 如果存在，它的值必须是 string，这与 [key: string]: string 兼容
// count?: number; // 错误：属性 “count” 的类型 “number” 不能赋给字符串索引类型 “string”。
}

let myDictionary: StringDictionary = {};
myDictionary[“hello”] = “world”;
myDictionary[“greeting”] = “hi”;
// myDictionary[123] = “number as key”; // 允许，因为数字键会被转换为字符串 (“123”)

// 访问时得到的是对应的字符串值
const greeting = myDictionary[“greeting”]; // 类型是 string
// const count = myDictionary[“count”]; // 尽管在接口中定义了 StringDictionary，但实际访问不存在的属性时，类型仍然是 string | undefined，需要进行判断

interface StringOrNumberDictionary {
[key: string]: string | number; // 键是字符串，值可以是字符串或数字
length: number; // 已知属性 length 的值是数字，这与索引签名的值类型 string | number 兼容
name: string; // 已知属性 name 的值是字符串，这与索引签名的值类型 string | number 兼容
}

let data: StringOrNumberDictionary = {
key1: “value1”,
key2: 100,
length: 2,
name: “MyData”
};
// data.key3 = true; // 错误：不能将类型 “boolean” 分配给类型 “string | number”。
“`

字符串索引签名非常适合描述那些其属性名在运行时才能确定的对象，比如来自服务器的响应数据中包含可变字段，或者实现一个简单的键值存储。

6.2 数字索引签名

用于描述那些键是数字的对象，通常用来描述数组或类数组对象。

“`typescript
interface NumberArray {
[index: number]: string; // 键是任意数字，值是字符串
}

let myArray: NumberArray = [“apple”, “banana”, “cherry”]; // 数组是特殊的数字索引类型
// myArray[0] 得到 “apple”，类型是 string
// myArray[1] 得到 “banana”，类型是 string

// 你也可以手动创建符合数字索引签名的对象
let myMap: NumberArray = {};
myMap[0] = “first”;
myMap[10] = “tenth”;

// myMap[“key”] = “value”; // 错误：类型 ‘{ [index: number]: string; }’ 中不存在属性 ‘key’。
“`

6.3 同时使用字符串和数字索引签名

在一个接口中，你可以同时定义字符串索引签名和数字索引签名。但是，如果同时存在，数字索引签名的返回值类型必须是字符串索引签名的返回值类型的子类型（或者说，数字索引器返回的值类型必须能够赋值给字符串索引器返回的值类型）。这是因为在 JavaScript 中，当你使用数字作为属性键时，它会被隐式转换为字符串。例如 obj[0] 实际上访问的是 obj["0"]。因此，通过数字索引访问得到的值，也必须符合通过相应的字符串索引访问时应该得到的类型。

“`typescript
interface CombinedIndexSignature {
[key: string]: object | string; // 字符串索引可以返回 object 或 string
[index: number]: string; // 数字索引必须返回 string，因为 string 是 object | string 的子类型
}

let mixed: CombinedIndexSignature = {
0: “hello”, // 通过数字索引访问，值必须是 string
1: “world”,
“name”: “mixed object”, // 通过字符串索引访问，值可以是 string
“data”: { id: 1, value: “test” } // 通过字符串索引访问，值可以是 object
};

// let invalidMixed: CombinedIndexSignature = {
// 0: { id: 1 }, // 错误：不能将类型 ‘{ id: number; }’ 分配给类型 ‘string’。数字索引必须是 string。
// “name”: 123 // 错误：不能将类型 ‘number’ 分配给类型 ‘object | string’。字符串索引必须是 object 或 string。
// };
“`

7. 类类型接口（Implementing Interfaces）

接口可以用来约束类的行为。类可以实现（implements）一个或多个接口，承诺提供接口中定义的所有属性和方法。

“`typescript
interface ClockInterface {
currentTime: Date;
setTime(d: Date): void;
}

// 类使用 implements 关键字来实现接口
class DigitalClock implements ClockInterface {
currentTime: Date = new Date(); // 必须实现 currentTime 属性
setTime(d: Date) { // 必须实现 setTime 方法
this.currentTime = d;
}
// 类可以有接口中未定义的其他成员
constructor(h: number, m: number) {
// … constructor logic
}
}

class AnalogClock implements ClockInterface {
currentTime: Date = new Date();
setTime(d: Date) {
this.currentTime = d;
// … additional logic for analog clock
}
// … other analog clock specific methods/properties
}

// 一个实现接口的类的实例，可以被赋值给接口类型的变量
let digital: ClockInterface = new DigitalClock(12, 30);
digital.setTime(new Date());

let analog: ClockInterface = new AnalogClock();
analog.setTime(new Date());
“`

重要限制： 接口只会检查类的实例部分（Instance Side），而不会检查类的静态部分（Static Side）。这意味着你不能使用接口来约束类的静态属性或静态方法。

如果你想约束类的静态部分，你需要分别定义接口和构造函数类型：

“`typescript
interface ClockConstructor {
new (hour: number, minute: number): ClockInterface; // 定义构造函数的形状
}

interface ClockInterface {
currentTime: Date;
setTime(d: Date): void;
}

// 这个函数接受一个符合 ClockConstructor 接口的构造函数，并返回一个 ClockInterface 实例
function createClock(ctor: ClockConstructor, hour: number, minute: number): ClockInterface {
return new ctor(hour, minute);
}

class DigitalClock implements ClockInterface {
constructor(h: number, m: number) {
// …
}
currentTime: Date = new Date();
setTime(d: Date) {
this.currentTime = d;
}
}

// 使用 createClock 函数来创建 DigitalClock 实例
let clock = createClock(DigitalClock, 12, 17);
clock.setTime(new Date());
“`

在这个例子中，ClockConstructor 接口描述了类的构造函数（即类本身作为值的类型），而 ClockInterface 描述了类的实例的类型。这样，我们就可以对类的静态（构造函数）和实例部分都进行类型检查。

8. 继承接口（Extending Interfaces）

接口可以像类一样互相继承。一个接口可以继承一个或多个现有接口，从而继承它们所有的成员。这允许你构建更复杂和有组织的接口体系。

“`typescript
interface Shape {
color: string;
}

interface Square extends Shape { // Square 接口继承了 Shape 接口
sideLength: number;
}

interface Circle extends Shape { // Circle 接口也继承了 Shape 接口
radius: number;
}

interface ColoredSquare extends Square, Circle { // ColoredSquare 继承了 Square 和 Circle
// ColoredSquare 将拥有 color (来自 Shape), sideLength (来自 Square), radius (来自 Circle)
// 如果继承的接口有同名属性但类型不兼容，会报错
// 例如：如果 Circle 也有一个属性是 size: string，而 Square 有 size: number，则 ColoredSquare 无法继承
}

let square: Square = {
color: “blue”,
sideLength: 10,
};

let circle: Circle = {
color: “red”,
radius: 5,
};

let coloredSquare: ColoredSquare = {
color: “purple”,
sideLength: 20,
radius: 8 // 这里的 radius 是从 Circle 继承来的
}
“`

接口继承提供了一种组合和复用接口定义的方式，有助于构建清晰的类型层级结构。

9. 混合类型接口（Hybrid Types）

虽然不常见，但接口可以描述那些同时具有多种类型的对象。例如，一个对象既可以作为函数被调用，又可以拥有属性。

“`typescript
interface Counter {
(start: number): string; // 作为函数被调用时：接受一个数字参数，返回字符串
interval: number; // 具有一个 number 类型的属性
reset(): void; // 具有一个 reset 方法
}

// 创建一个符合 Counter 接口的对象
function getCounter(): Counter {
let counter = (function (start: number) {
// 函数的实现
console.log(Starting counter from ${start});
return “Counter started”;
}) as Counter; // 使用类型断言告诉 TypeScript 这个函数字面量符合 Counter 接口

counter.interval = 123; // 属性的实现
counter.reset = function () {
// reset 方法的实现
console.log(“Counter reset”);
};

return counter;
}

let counter = getCounter();
let result = counter(10); // 调用函数部分
console.log(result); // 输出 “Counter started”
console.log(counter.interval); // 访问属性部分
counter.reset(); // 调用方法部分
“`

这种混合类型接口在描述某些特殊的 JavaScript 库模式时非常有用，比如 JQuery 的 $() 函数既是函数，又拥有很多属性和方法。

10. 接口 vs. 类型别名（Interfaces vs. Type Aliases）

在 TypeScript 中，除了接口 (interface)，我们还可以使用类型别名 (type) 来定义类型的别名。它们在很多方面功能相似，尤其是在描述对象形状时。然而，它们之间存在一些关键的区别。

特性	Interface	Type Alias
定义对象形状	✅ 是主要用途之一	✅ 可以
定义函数类型	✅ 可以 (使用调用签名)	✅ 可以 (使用箭头函数语法 (...) => ...)
定义索引签名类型	✅ 可以 ([key: string]: type, [index: number]: type)	✅ 可以 ({ [key: string]: type }, Array<type> 或 type[])
定义基本类型别名	❌ 不行	✅ 可以 (type MyString = string)
定义联合/交叉类型	❌ 不行 (但可以通过继承模拟交叉)	✅ 可以 (type MyUnion = A | B, type MyIntersection = A & B)
声明合并	✅ 支持 (同名接口会自动合并)	❌ 不支持
类实现	✅ 可以被类 implements	❌ 不可以被类 implements (但类可以实现由类型别名定义的包含调用签名的接口)
扩展	使用 extends 关键字	使用交叉类型 &
可读性/错误消息	通常在描述对象形状时，错误消息更友好	错误消息有时可能不够直观
递归类型	早期有限制，现在大部分情况支持	支持

主要区别总结：

1. 声明合并（Declaration Merging）： 这是接口独有的特性。你可以定义多个同名的接口，TypeScript 编译器会自动将它们合并成一个接口。这对于库作者扩展现有类型或用户模块化定义类型非常有用（例如，在不同的文件里为同一个接口添加属性）。类型别名不能做到这一点，同名的类型别名会导致编译错误。
2. 类实现（Class Implementation）： 只有接口可以被类使用 implements 关键字来实现。虽然类型别名可以定义一个包含调用签名的函数类型，但你不能让一个类去 implements 这个类型别名来约束类的构造函数（如前所述，需要接口来描述实例部分）。
3. 非对象类型： 类型别名可以用于定义任何类型的别名，包括基本类型、联合类型、交叉类型、元组等。接口主要用于定义对象形状或函数类型。
4. 扩展方式： 接口使用 extends 关键字进行继承，可以继承多个接口。类型别名使用交叉类型 (&) 来组合现有类型，达到类似扩展的目的。

选择建议：

• 优先使用接口： 当你定义一个对象（或函数）的形状时，通常推荐使用 interface。特别是在以下情况：
  • 你需要利用声明合并的特性（例如，为全局对象 window 添加属性，或者在不同的模块中为同一个类型添加定义）。
  • 你需要让类实现这个类型定义。
• 在其他情况下使用类型别名： 当你需要定义基本类型的别名、联合类型、交叉类型、元组，或者使用更复杂的类型操作时，使用 type。

在许多简单场景下，接口和类型别名是可以互换的。但理解它们之间的区别能帮助你选择最适合的工具，尤其是在构建大型应用或库时。

11. 接口与泛型

接口可以与泛型结合使用，创建可重用的、类型参数化的接口。这使得接口能够描述那些依赖于某个类型参数的对象或函数。

“`typescript
// 定义一个泛型接口，描述一个包含某种类型值的盒子
interface Box {
value: T;
}

// 使用泛型接口创建不同类型的盒子
let stringBox: Box = { value: “hello” };
let numberBox: Box = { value: 123 };
let booleanBox: Box = { value: true };

// 定义一个泛型接口，描述一个泛型函数
interface GenericIdentityFn {
(arg: T): T; // 接受一个类型为 T 的参数，返回一个类型为 T 的值
}

// 实现泛型函数接口
function identity(arg: T): T {
return arg;
}

let myIdentity: GenericIdentityFn = identity; // 这里的 identity 函数必须符合 (arg: number) => number 的形状

let num = myIdentity(42); // num 的类型被推断为 number
// let str = myIdentity(“hello”); // 错误：不能将类型 “string” 的参数分配给类型 “number” 的参数。
“`

泛型接口在描述数据结构（如链表、树、字典等）以及类型参数化的函数时非常有用。

12. 实际应用场景

接口在 TypeScript 项目中无处不在，以下是一些常见的应用场景：

1. 描述 API 响应数据结构： 定义接口来精确描述从后端 API 获取的数据应该是什么形状，提高前端代码的类型安全性。
2. 定义配置对象： 使用接口来约束应用程序的配置对象，确保所有必要的配置项都存在且类型正确。
3. 定义函数参数和返回值： 使用接口（特别是函数类型接口）来明确函数的输入和输出契约。
4. 约束类的行为： 使用接口定义类必须实现的功能，增强代码的可测试性和可替换性。
5. 描述数据库模型或数据实体： 在ORM（对象关系映射）或数据访问层中使用接口来描述数据的结构。
6. 框架或库的类型定义： 接口被广泛用于定义 JavaScript 库（如 React, Vue, Node.js 模块等）的类型，通过 @types 包提供给 TypeScript 用户。
7. 状态管理： 在 Redux, Vuex 等状态管理库中，使用接口来定义应用程序的状态（State）的结构。
8. UI 组件 Props/State： 在 React 或 Vue 等组件库中，使用接口来定义组件的 props（属性）和 state（状态）的类型，增强组件的类型安全性。

13. 接口的优点

• 静态类型检查： 在编译阶段捕获类型错误，减少运行时错误。
• 提高代码可读性： 清晰地表达代码期望的数据结构。
• 增强可维护性： 易于理解和修改代码中的数据结构。
• 支持面向对象设计： 通过 implements 实现多态性。
• 利于协作： 为团队成员提供明确的API或数据结构定义。
• 声明合并： 独特的特性，方便库的类型扩展和模块化定义。

14. 总结

TypeScript 接口是构建健壮、可维护、易于协作的应用程序的基石。它们提供了一种强大的方式来定义对象的形状、函数的契约以及类的行为。从基本的属性定义到可选属性、只读属性、函数类型、索引签名、类实现、接口继承、混合类型，再到与泛型的结合和与类型别名的比较，接口展现了其灵活性和强大功能。

熟练掌握 TypeScript 接口的用法，能够显著提升你的代码质量和开发效率，让你在构建复杂的应用时更加自信和得心应手。在实际开发中，请积极使用接口来定义你的数据结构和契约，享受静态类型带来的便利和保障。

---