TypeScript 的接口interface是我在实际项目中使用频率最高的类型定义工具。跟很多刚入门的朋友聊过之后我发现大家普遍把接口理解成了给对象标个类型等到真要在工程里维护几千行类型定义时才意识到接口设计的功力直接影响项目长期的可维护性。这篇文章就想把自己这些年在接口定义上积累的经验完整讲一遍包括基础语法细节、继承与泛型组合、前后端联调时的类型设计以及一些面试常问的坑。不管你是刚接触 TS 的新手还是写了两三年还在纠结 interface 和 type 怎么选的老兵应该都能找到一些有用的参考。1. 接口在 TypeScript 里到底解决了什么问题1.1 从结构类型检查说起在 JavaScript 时代我们传递一个对象参数时全凭自觉。函数接收的到底是{ a: 1 }还是{ b: hello }没有任何机制约束。一旦属性名拼错IDE 也不会给任何提示大概率要等到运行时才发现异常。TypeScript 接口就是来解决这件事的它给对象画了一张图纸规定了这个东西该有哪些属性、每个属性是什么类型编译器在编译期就能把大部分低级错误拦下来。这里有个关键概念值得展开讲TypeScript 的接口检查属于结构类型系统Structural Typing。意思是一个对象只要形状上满足接口定义就可以直接赋值给这个接口类型不需要显式声明 implements 或者 extends。比如定义一个{ name: string }接口那么任何一个{ name: Tom }对象都能直接传进去即使这个对象的类型叫Person还是Student都不重要。生活中做个类比你招聘一个会写代码的人你不会管他是哪个学校毕业的只要他确实会写代码就行。这种灵活性是 TypeScript 接口区别于 Java、C# 接口的最大特点。我见过不少项目后端数据一回来就直接as any接口定义形同虚设。这样做短期写起来爽但长期来看等于把 TypeScript 的类型防线全部拆了。代码里所有的字段访问都回到 JavaScript 那种裸奔状态等你重构的时候编译器帮不上一点忙所有错误都得靠运行时反馈。所以接口这件事其实是在投资项目的可维护性。1.2 接口和类型别名什么时候选哪个这个问题大概是面试里出现频率最高的一道 TypeScript 题。interface 和 type 都能用来描述对象结构但侧重点不同。interface 的核心优势是扩展友好可以声明合并declaration merging。同一个接口可以在不同文件中重复声明TS 会自动合并它们。这在扩展第三方库类型时非常好用。更贴近对象形状的表达语义清晰。继承多个接口更直观直接用 extends 即可。type 的核心优势是组合能力强支持联合类型string | number、交叉类型A B、条件类型。可以为原始类型string、number定义别名。可以定义元组等特殊结构。我的使用习惯是描述对象、类的契约首选 interface需要组合复杂类型联合、交叉、条件类型时再用 type。有一些项目团队会规定能用 interface 就不用 type这在我看来有点极端但方向是合理的因为 interface 的可扩展性更强未来改动成本更低。有人会问那 type 也能实现类似extends的效果啊用交叉类型type A Base Extra。确实可以但交叉类型在处理同名属性冲突时的行为比较隐晦不如 interface 的继承规则直观。在团队协作中interface 的报错信息通常也更清晰。2. 接口定义的核心语法与实用细节2.1 基础字段、可选属性与只读属性接口最基本的形态是字段声明interface User { id: number; name: string; email: string; createdAt: Date; }实际项目里大多数字段并不是一开始就有值。比如用户的邮箱可能要等用户激活之后才存在。这时候用?标识可选属性interface User { id: number; name: string; email?: string; createdAt: Date; }这里有一个经常被忽略的细节email?: string和email: string | undefined并不等价。前者表示这个键可以不存在后者表示键必须存在但值可能是 undefined。差别在实际代码中非常明显——如果你用email in user来判断字段是否存在前者为 false 时很正常后者理论上永远为 true。做 JSON 序列化时也一样可选属性不存在序列化结果里就没有这个键而string | undefined的字段序列化结果里键还在值是 null或 undefined取决于序列化器配置。只读属性用 readonly 关键字interface User { readonly id: number; name: string; }一旦一个字段标记为 readonly在对象创建之后就不能再被重新赋值。这里要注意和 const 的区别const 限制的是变量本身不能重新赋值readonly 限制的是对象内部的属性不能重新赋值。还有一个重要提醒readonly 只在编译期生效运行时的 JS 对象该改还是能改。它不是一个运行时保护机制更像是一个开发期的防呆设计。2.2 函数类型接口与调用签名接口不止能描述对象还能描述函数的形状。定义一个函数类型接口interface SearchFunc { (source: string, subString: string): boolean; } const search: SearchFunc (src, sub) src.includes(sub);这样做的价值在于当你有一个事件分发器、一个回调注册表希望所有回调都满足同一个签名时直接定义一个函数接口所有注册处都强制套用错误会在编译期暴露。比如我写过一个简单的发布订阅模块所有订阅者函数都必须是(payload: EventPayload) void格式但凡有人想往回调里塞额外参数立刻报错比运行时才发现强太多。除了调用签名接口里还有构造签名interface PointConstructor { new (x: number, y: number): Point; }构造签名主要用在工厂函数、依赖注入容器这类场景。比如你要实现一类能够创建特定对象的工厂类但不知道具体是哪个类只要求它满足这个构造签名那后续替换实现就非常方便。2.3 索引签名与字典类型索引签名用来描述可以被数字或字符串索引访问的类型。典型场景是字典对象interface StringDictionary { [key: string]: string; } const dict: StringDictionary { apple: 苹果, banana: 香蕉, };索引签名有一个非常容易踩的坑接口里所有属性都必须兼容索引签名规定的类型。比如下面这段代码会报错interface Dict { [key: string]: number; name: string; // 报错类型 string 与 number 不兼容 }因为name最终会被当作Dict[name]来读而索引签名规定它是 number两者冲突。解决办法有两个把索引签名类型放宽成number | string或者用Recordstring, number单独定义不掺固定字段。实际项目中我一般把 API 响应的扩展数据统一用Recordstring, unknown处理固定字段单独列出来这样既保留了扩展性又不至于让类型失去约束。3. 接口的继承、实现与泛型组合3.1 extends 扩展与多继承接口之间通过 extends 实现继承类似类的继承关系interface BaseUser { id: number; name: string; } interface AdminUser extends BaseUser { role: admin; permissions: string[]; }继承最直接的好处是拆分层级。你会发现很多项目里的接口定义是一大坨所有字段全部平铺在一个接口里。这种写法在字段少时还能忍一旦超过十几个字段每次改动都要翻半天。把公共字段提取到基接口不同业务实体再各自继承维护体验完全不一样。TS 的接口支持一次继承多个接口interface Loggable { log(): void; } interface Serializable { serialize(): string; } interface LogRecord extends Loggable, Serializable { timestamp: number; }这在做模块化设计时非常好用。比如一个日志系统一条日志记录既需要能输出也需要能序列化就分别定义这两个能力接口再组合成一个总接口。组件依赖抽象接口不依赖具体实现替换成本低。注意一个细节子接口可以覆盖父接口的字段但覆盖后的类型必须是原类型的子类型。比如父接口字段是status: string子接口可以收窄成status: success | failure但不能改成status: number。这个规则保证子类对象可以当作父类来用的类型安全前提。3.2 类实现接口implements 的约束类可以通过 implements 实现接口interface Runnable { run(): void; speed: number; } class Car implements Runnable { speed 120; run() { console.log(running...); } }一个很容易被忽视的点是implements 只检查类的实例部分静态属性和构造函数签名不会被检查。你想约束传入的类必须能通过某组参数构造出实例接口是管不了的需要借助泛型和构造签名interface PointConstructor { new (x: number, y: number): Point; } function createPoint(Ctor: PointConstructor, x: number, y: number): Point { return new Ctor(x, y); }这个模式在写依赖注入、工厂函数时很常用。理解了这一点面试被问implements 会不会检查静态部分时就不会掉坑。在实际编码中我推荐面向接口编程方法的入参尽量定义成接口类型而不是具体类。比如参数接收Runnable而非Car那么任何实现了Runnable的对象都能传入不需要为每一种实现单独写重载。这就是依赖倒置原则在 TS 类型层面的落地。3.3 泛型接口让接口更通用接口配上泛型之后表达能力会强很多。最常见的场景是分页响应interface PaginatedResultT { list: T[]; total: number; page: number; pageSize: number; }这样一个通用接口可以同时包裹用户列表、订单列表、日志列表不需要为每个业务类型重复定义外层结构。我在公司项目里专门有一个api/types.ts文件把所有通用结构分页、响应包裹、排序参数定义好业务类型只关心自己的T部分。泛型接口还可以设置默认值interface ApiResponseT unknown { code: number; message: string; data: T; }默认值设成unknown而不是any是一个关键细节。unknown要求先收窄再使用any直接放弃检查。用 unknown 作为兜底调用方拿到的数据如果没做类型断言编译器会强制你先判断类型再操作字段这在大型团队里能避免很多运行时才发现字段不存在的问题。4. 实操过程前后端联调中的接口设计4.1 从接口文档到 TypeScript 类型的转换前端联调时拿到一份接口文档我的习惯是先把请求参数和响应类型定义好再写业务代码。别小看这一步做与不做在大型项目里效率差距很大。以登录接口为例interface LoginRequest { username: string; password: string; } interface LoginResponse { token: string; expiresIn: number; userInfo: User; }然后封装请求函数async function login(req: LoginRequest): PromiseLoginResponse { const res await http.post(/api/login, req); return res.data; }这样做最直观的好处是当后端调整字段比如把 expiresIn 改成 expireAt只要改接口定义中的一行所有引用了这个字段的地方都会在编译期报错。你可以立刻知道哪些地方需要同步调整而不是等用户反馈线上 bug 再排查。还有一个实战经验给后端字段命名做一次前端化映射。后端返回的是user_name前端代码里更习惯userName。这时可以定义一个 DTO 类型在 API 层做字段转换interface UserDTO { user_name: string; user_age: number; } interface User { userName: string; userAge: number; }把转换逻辑收敛在 API 层业务组件永远面对的是符合前端习惯的类型结构。4.2 失败与成功结构不同的处理方案接口文档并不总是规整的。有些接口成功时返回 data失败时返回 message两者结构完全不同。这种情况最忌讳把所有字段都堆进一个接口再用一堆可选属性撑场面。用可辨识联合类型来处理type ApiResultT | { code: 0; data: T } | { code: number; message: string };在运行时通过 code 字段收窄function handle(result: ApiResultLoginResponse) { if (result.code 0) { // TS 知道这里有 data console.log(result.data.token); } else { // TS 知道这里有 message console.warn(result.message); } }这种方式让我在编写业务代码时能清楚地意识到当前处于失败分支提醒自己去处理错误提示。比所有字段混在一起、用res.data?.token反复判空要清爽得多。可辨识联合在代码评审时也更直观reviewer 一眼就能看到正常路径和异常路径。4.3 用字面量联合约束固定取值接口字段经常需要约束为固定取值。比如用户角色只有tourist | user | admin三种。比起枚举enum我更倾向用字符串字面量联合类型type UserRole tourist | user | admin; interface User { id: number; role: UserRole; }为什么不用 enum第一个原因TS 的 enum 编译产物是运行时对象如果你只需要类型约束用字面量联合不产生额外代码bundle 更小。第二个原因后端返回给前端的往往是普通字符串用 enum 还需要做映射而字面量联合天然匹配。在 IDE 里悬停查看类型时字面量联合能直接看到所有可选值非常直观。当然字面量联合也有代价如果后端新增了一种角色前端必须同步更新类型定义。所以建议把这些常量集中放在一个roles.ts文件里统一导出方便维护。5. 常见问题与排查技巧实录5.1 接口相关报错与排查这里记录几类我实际生产环境中遇到的报错每类都附排查思路。报错一属性不存在Property xxx does not exist on type User.通常原因User 接口里没有这个字段。可能是后端新增字段没同步也可能是对象实际来自一个更具体的子类型但声明类型是父接口。先确认接口定义再判断是否需要收窄类型。报错二类型不兼容Type string is not assignable to type number.排查思路接口定义的字段类型写错了或者赋值对象来自一个联合类型变量。不要在方法调用处用as number强行绕过先找到类型不一致的根源修正接口定义。报错三索引签名缺失Index signature for type string is missing in type {}排查思路常见于把普通对象字面量赋给带有索引签名的接口。给对象声明具体的Recordstring, ...类型或者把接口索引签名补全。报错四可选属性访问没有收窄Object is possibly undefined.排查思路开启 strictNullChecks 后可选属性在访问前必须做存在性判断。要么判断if (user.email)要么用可选链user.email?.toLowerCase()不要直接访问。5.2 面试常问的接口相关题目我把面试中遇到过的接口题目整理成速查interface 和 type 的核心区别是什么—— 一个可声明合并、侧重对象形状一个可组合联合/交叉/条件类型。可选属性与string | undefined有什么区别—— 前者键可不存在后者键必须存在。接口能描述函数和数组吗—— 能。函数用调用签名数组/字典用索引签名。readonly 和 const 的区别—— const 针对变量绑定readonly 针对对象属性。implements 会不会检查静态成员—— 不会只检查实例部分。泛型接口默认值为什么用 unknown 不用 any—— 前者强制收窄后者放弃检查。声明合并有什么实际用途—— 扩展第三方库类型、给全局对象补充字段。每个问题其实都对应一个真实项目中的坑。把这些题目弄清楚接口这个知识点的掌握程度基本就过关了。5.3 如何避免到处 any很多人一遇到类型报错第一反应是as any直接绕过。这个习惯在小型 demo 里问题不大在大型项目里会逐渐腐蚀类型系统。我自己的处理原则是第一能收窄就不绕过。先用unknown接住运行时数据再通过 typeof、in、Array.isArray 等手段收窄到具体类型。实在无法精确推断时才用 as 断言到明确类型。第二as 的范围尽量小。不要const res: any await request()这样整段代码都失守了。正确做法const raw: unknown await request(); const data raw as LoginResponse;即便 later 类型有变化定位也会方便很多。第三遇到第三方库类型定义缺失时优先查 DefinitelyTyped 是否有 types 包。没有的话再考虑在项目里用声明合并补全而不是一把梭 any。5.4 接口设计上的最佳实践最后分享几条我在实际项目里反复检验过的接口设计建议命名尽量简洁。TS 社区已经不流行 IUser 这种前缀命名了直接叫 User 或者 Role 更干净。接口名用名词或名词短语表达这是一种什么类型。接口保持短小。一个接口超过 10 个字段就要考虑拆分。拆成子接口再 extends 组合职责更清晰。慎用可选属性。可选属性用多了消费方到处要判空。能用联合类型把不同场景拆开就不打 ?。API 类型集中管理。单独建一个 types 目录按模块划分文件。业务组件不直接在内部手写接口返回类型。大项目可以考虑自动生成类型。有 OpenAPI/Swagger 文档时用 openapi-typescript 这类工具自动生成 TS 类型至少保证字段名和真实接口一致避免手写脱节。另外tsconfig 里几个和接口相关的选项也值得注意strict: true一定要开否则 strictNullChecks 不生效可选属性和空值判断的语义就变了。noUncheckedIndexedAccess建议打开虽然会多写一些判断代码但能防止字典和数组越界访问。如果看到 baseurl is deprecated 这类编译警告趁早按照新规范调整路径别名配置别拖到升级 TS 7.0 时再处理。我个人在接口设计上踩过几次坑之后最大的体会是接口不是写给编译器看的也不是写给后端看的而是写给六个月后重新打开这个项目的自己看的。类型定义写得好重构时编译器的报错就是在帮你精确定位所有需要修改的地方写不好类型系统形同虚设最后全项目里飘着 any所有类型保障化为泡影。所以我现在的习惯是新需求排期时把接口定义的时间也算进去提交 PR 前把新增类型单独 review 一遍看有没有多余的字段、可合并的结构、命名不清晰的接口。看起来很琐碎但长期下来整个代码库的类型质量会稳定在一个很高的水位线上。