先说一个我早年间接手的真实项目。前后端联调时后端返回的字段一会儿叫userId一会儿叫user_id前端某个模块拿到的值是字符串另一个模块却当数字在用。那时候我还在写纯 JavaScript这种问题只能靠人肉 review 和“约法三章”但约法三章这东西在赶工期的时候基本没人记得——谁也没时间边联调边翻接口文档。后来切到 TypeScript第一次用interface约束后端返回的数据结构编译期就把这类问题全拦了下来。那一刻我才意识到接口interface在工程里的价值远不止“给对象加个类型”这么简单它本质上是代码和代码之间的一份契约。这篇文章会从接口要解决的问题讲起拆开最基本的语法、属性修饰符、函数类型接口、可索引接口、类实现接口这些内容最后聊一聊我在真实项目里整理接口的一些习惯。这一篇定位是“基本使用一”所以重点是讲透最常用的部分适合正在学 TypeScript 的初学者也适合写过一段时间但一直靠type走天下的朋友——把接口补上你会发现自己的类型体系清晰不少。1. 接口到底解决了什么问题从一次真实的重构经历说起很多人第一次看 TypeScript 文档上来就是interface User { name: string }看完觉得“哦就是给对象加个类型嘛”然后就划走了。这其实把接口最核心的价值给忽略了——它解决的问题不是“给变量标个类型”而是描述一整套数据结构的形状并且把这个形状变成代码里的公共约定。1.1 JavaScript 的“自由”带来的连锁反应纯 JavaScript 里对象就是键值对的集合爱怎么加字段就怎么加// 一个创建用户的函数没有任何约束 function createUser(name, age) { return { name: name, age: age, // 手一抖把 are 拼成了 aer aer: 18 }; } const user createUser(张三, 25); console.log(user.age); // 25 console.log(user.aer); // 18直到这行才发现拼错了单个拼写错误在 10 行代码里很容易发现但放到真实项目里就不是这回事了。一个用户对象可能有十几个字段分布在七八个模块里被引用某天后端调整了字段名前端所有用到的地方全部静默失败——不是报错而是拿到undefined然后页面某块区域空白排查半天找不到原因。TypeScript 接口解决的就是这种“结构性约束”的缺失。它让你在编译阶段就明确这个对象有哪些字段、字段分别是什么类型、哪些字段必须存在、哪些可选。一旦有人传错了类型、拼错了字段名编译器直接红牌。1.2 接口不是“类型标注”而是“数据契约”我习惯把接口看成一份契约书而不是单纯的技术语法。这份契约约定了三件事结构契约对象必须长什么样——有哪些字段、嵌套层级如何。类型契约每个字段的类型是什么——字符串、数字、还是另一个接口。协作契约前后端联调、多人并行开发时照着同一份接口定义写代码。实际开发里最常见的场景是前后端约定接口返回值。后端返回的 JSON 结构往往有好几层嵌套比如分页数据如果不在前端用接口描述清楚你会发现每个调用方都自己猜返回结构猜错了就地 debuginterface PageResultT { list: T[]; total: number; page: number; pageSize: number; } interface UserInfo { id: number; name: string; email: string; isActive: boolean; } // 一个函数返回分页用户列表 async function fetchUsers(page: number): PromisePageResultUserInfo { const res await fetch(/api/users?page${page}); return res.json(); }看到PromisePageResultUserInfo这个返回类型调用方不用去看接口文档也大概猜到返回结构是“列表 总数 页码 每页条数”每一条又是“id、name、email、isActive”。这就是接口作为“契约”带来的沟通效率——代码本身就在描述数据长什么样。1.3 一个接口定义全局受益接口的另一个厉害之处在于它定义一次可以到处引用。比如一个表单组件接收的值是一个用户对象我可以直接写成function UserForm({ user }: { user: UserInfo }) { // 这里的 user 有完整的类型提示 }组件内部敲user.时编辑器会把所有字段列出来拼错字段名立刻标红。同样的结构在列表页、详情页、编辑页被反复引用只要字段定义改一处所有用到的地方全部同步更新类型检查。这份“单一事实来源”的价值在项目越来越大之后会越发明显。2. 接口的核心语法从最简单的对象约束开始理解了接口是“数据契约”接下来就看它怎么写。这一节我会从最基础的写法讲起逐步加入嵌套结构、数组、组合类型这些实际中马上会用到的东西。别急着一口气把语法全记住后面每个小节都会配上场景。2.1 内联类型标注与接口两种写法的取舍约束一个对象其实有两种常见写法很多新手一开始会把它们混着用。第一种是内联类型标注function printUser(user: { name: string; age: number }): void { console.log(${user.name} is ${user.age} years old); }这种写法适合一次性的简单场景函数只在这个文件里用对象结构也简单没必要单独定义一个类型名字。第二种就是用接口interface User { name: string; age: number; } function printUser(user: User): void { console.log(${user.name} is ${user.age} years old); }区别一眼就能看出来接口给了这个结构一个名字User可以在多个地方重复引用。把接口当成一个“形状模板”你会发现三口五口不需要它真正多人协作的项目里几乎所有被共享的对象结构都应该抽成接口否则同一个结构会在十几个地方被重复内联描述维护成本翻倍。2.2 基础类型、嵌套结构与数组字段接口描述的不只是“字符串字段”它支持所有 TypeScript 类型——基本类型、数组、元组、嵌套接口、联合类型都可以直接往里放。直接看一个更贴近真实业务的例子interface Address { province: string; city: string; detail: string; } interface OrderItem { productId: number; productName: string; price: number; quantity: number; } interface Order { orderId: string; createdAt: Date; customer: { name: string; phone: string; }; items: OrderItem[]; // 数组字段 address: Address; // 嵌套接口 status: pending | paid | shipped | completed; // 字面量联合类型 remark?: string; // 可选字段 }这里有几个值得注意的点嵌套接口address字段本身就是Address接口说明接口之间可以互相引用复杂数据结构可以通过这种方式逐层拆解。数组字段OrderItem[]表示“元素类型为 OrderItem 的数组”这在列表场景里几乎是每天都会遇到的形态。字面量联合类型status字段只能是这四个字符串之一相当于把字段的“合法取值”也定义死了比单纯写string严谨得多。可选字段remark?后面加一个问号表示该字段可以不存在比如订单没有备注时后端就不返回这个字段。可以看到接口描述数据的能力非常强复杂的数据结构经过逐层拆解会变得非常清晰。每次定义接口时我会把顺序固定下来先直接写标量字段再写嵌套对象最后写数组——阅读起来会顺很多。2.3 接口的复用同一形状多处生效接口定义完不只是“装饰”一个函数它可以直接被变量、函数参数、函数返回值、类、泛型等各类场景引用。举个典型的组合示例interface Product { id: number; name: string; price: number; } // 1. 变量标注 const defaultProduct: Product { id: 1, name: 默认商品, price: 0 }; // 2. 函数参数 function getProductName(product: Product): string { return product.name; } // 3. 函数返回值 function createProduct(name: string, price: number): Product { return { id: Date.now(), name, price }; } // 4. 接口数组 const products: Product[] [ { id: 2, name: 苹果, price: 5.5 }, { id: 3, name: 香蕉, price: 3.2 } ];同一个Product接口变量、参数、返回值、数组四处都在用一旦价格字段要改成price: number配合 currency 使用只需要改接口定义编译器就会把所有不符合新结构的地方标出来。这就是接口的杠杆效应——改一处全项目受益漏一个编译器帮你查。3. 属性修饰符可选、只读和那些“明明没错却报错”的时刻接口的基本结构定义了对象长什么样但真实项目里对象的字段不可能永远是“必须存在、可修改”这么简单。于是 TypeScript 提供了几个属性修饰符其中最常碰到的就是可选属性?和只读属性readonly。另外很多人被“额外属性检查”折磨过——对象明明“没问题”编译器却标红这一节我专门讲清楚原因。3.1 可选属性表示“这个字段不一定在”后端接口的数据经常有“有时返回、有时不返回”的字段。比如用户的头像可能在注册时没设置后端就不返回这个字段。这种场景用可选属性表达interface UserProfile { id: number; username: string; // 头像可能没有 avatar?: string; } function showAvatar(user: UserProfile) { // 可选字段使用时必须做存在性检查 if (user.avatar) { return img src${user.avatar} /; } return div暂无头像/div; }这里关键的一点是可选字段的类型其实是“原类型 | undefined”也就是说avatar?: string等价于avatar: string | undefined。所以使用时不能直接当成字符串用必须先判断存在与否。新手容易踩的坑就在这里——以为可选字段是“可以不给给了就是字符串”直接user.avatar.toUpperCase()运行时就会炸。提示可选属性表示的是“字段可以不存在”而不是“字段值可以传 null”。如果后端返回的字段是 null类型得写成avatar?: string | null否则类型检查依然过不去。3.2 readonly定义初始化后不可修改的字段有些字段在业务语义上是“创建后就不变了”比如订单 ID、创建时间、用户 ID。这些字段可以标记为readonly在任何地方尝试重新赋值编译器都会报错interface Article { readonly id: number; title: string; content: string; readonly publishedAt: Date; } const article: Article { id: 1, title: 你好, content: 正文, publishedAt: new Date() }; // 这样写会报错Cannot assign to id because it is a read-only property. // article.id 2; // 普通字段可以修改 article.title 修改后的标题;我最常把readonly用于后端返回数据的领域对象domain model上——前端拿到这份数据只是用来展示不应该去篡改 id 这类关键标识。另一个用法是在构造函数里赋值、之后绝不变化的配置对象。需要注意的是readonly是编译期的约束不是运行时冻结对象它只限制 TypeScript 的类型检查并不会真正阻止 JS 层面的赋值。3.3 额外属性检查为什么对象字面量会被“严格执法”这是新手一定会遇到、而且经常觉得莫名其妙的一个特性。看例子interface User { name: string; age: number; } // 场景 1对象字面量直接赋值 const user: User { name: 张三, age: 25, // 多了这个字段编译器直接报错 email: zhangsanexample.com };明明 JavaScript 里给对象多塞一个字段是再正常不过的操作TypeScript 凭什么报错这就是额外属性检查Excess Property Check。当使用对象字面量直接赋值时TypeScript 会检查“这个字面量是否有目标类型之外的属性”只要发现多余字段就会报错Object literal may only specify known properties, and email does not exist in type User.为什么设计成这样因为对象字面量直接赋值时出现多余字段往往是拼写错误、或用了不该传的数据结构的信号。比如你本意是email但接口字段叫emial编译器帮你抓出来这比运行时炸一句“undefined”要好得多。但这也带来一个常见困惑有时候确实需要传一个“额外的字段”。比如从一个函数返回的复杂对象里挑几个字段传给另一个函数对象变量本身含有接口定义之外的属性。区别在于当这个对象是通过变量引用而不是字面量直接传入时TypeScript 就不会做额外属性检查const userWithEmail { name: 张三, age: 25, email: zhangsanexample.com }; // 变量引用赋值不会报错因为 TypeScript 只检查“包含必需属性” const user2: User userWithEmail;这里userWithEmail含有多余字段email但作为变量整体赋给user2时TypeScript 采用的是结构性类型检查只要这个对象包含User接口要求的name和age字段赋值为User类型就成立。那为什么字面量不行因为编译器想拦住“你可能写错了字段名”这种错误。这是一对看似矛盾、实则互补的设计理解了它的目的你就不会觉得 TypeScript 在“故意找茬”了。4. 接口不只是描述对象函数类型、数组、类实现如果说前两节是接口的“基本款用法”那这一节是接口真正的发力点。接口能描述一切具有“结构形状”的事物——不只是普通对象还有函数本身、数组和字典甚至类。先用生活中例子类比普通对象接口就像一张员工信息表描述了人的名字、年龄、职位但“接口描述函数”就好比规定“所有维修师傅上门时必须先出示工牌、再开始维修”的流程——你关心的是这个函数“长什么样、能怎么被调用”而不是它内部代码怎么写。4.1 函数类型接口给函数本身也定规矩用接口描述函数签名最直接的写法是interface SearchFunc { (source: string, subString: string): boolean; } const search: SearchFunc function(source, subString) { return source.includes(subString); };这里SearchFunc描述了一个接受两个字符串参数、返回布尔值的函数。任何被声明为SearchFunc类型的变量都必须符合这个签名。这个写法最大的好处在于在回调函数、事件处理器这类场景中接口规定了“函数必须长什么样”调用时就能拿到完整的参数提示。实战里我更常用定义回调集合的场景。比如封装一个工具库对外暴露的 API 可以接受不同的回调函数interface Validator { // 参数是一个任意值返回 boolean 表示是否通过校验 (value: unknown): boolean; } const validators: Recordstring, Validator { email: (value) typeof value string value.includes(), phone: (value) typeof value string /^1\d{10}$/.test(value) };validators.email就可以直接被当成返回 boolean 的函数使用参数和返回值都有类型保障——比随便写一个Function类型严谨很多因为Function类型完全不限制参数个数和返回类型。4.2 可索引接口描述数组和字典对象另一种“形状”是可以通过索引访问的数据结构典型的就是数组和字典。可索引接口用[index: string]或[index: number]这类签名描述interface StringArray { [index: number]: string; } const names: StringArray [张三, 李四]; // 数字索引取出来的值一定是字符串 const firstName: string names[0];同样字典对象key-value 结构也可以用可索引接口描述这在描述后端返回的映射数据时特别实用interface ErrorMessages { // 键是字符串值也是字符串 [field: string]: string; } const errors: ErrorMessages { username: 用户名不能为空, email: 邮箱格式不正确 };可索引接口的核心价值在于当数据结构的“形状”不是固定的字段而是一组同类型的键值对时用可索引接口比列出每一个字段更合适。比如后端返回一个Recordstring, number表示各商品的库存数量商品种类随时在变没法预知所有字段名这就是可索引接口的主场。4.3 implements让类遵循接口契约接口用于约束“类的实例该有哪些成员”时用implements关键字interface Animal { name: string; speak(): void; } class Dog implements Animal { name: string; constructor(name: string) { this.name name; } speak(): void { console.log(${this.name} 汪汪叫); } } const dog new Dog(旺财); dog.speak();这里Dog类承诺了Animal接口的结构——必须有name属性和speak方法类里一旦漏写或写错签名编译器马上报错。这在依赖倒置、面向接口编程时很有用多个类实现同一个接口调用方只依赖接口而非具体类就能统一处理不同实现。interface Logger { log(message: string): void; error(message: string): void; } class ConsoleLogger implements Logger { log(message: string): void { console.log([INFO] ${message}); } error(message: string): void { console.error([ERROR] ${message}); } } class FileLogger implements Logger { log(message: string): void { // 写入日志文件 } error(message: string): void { // 写入错误日志文件 } }两个不同的Logger实现对外暴露的方法签名完全一致——这样依赖Logger接口的代码就不用关心具体是控制台还是文件只需要“调用log和error”。这就是接口在类设计层面最重要的用途**解耦”。5. 接口 vs 类型别名动手写代码前先想清楚用哪个TypeScript 里另一个经常混淆的概念是type类型别名。两个都能描述对象结构新手常常问“到底用哪个”。老实说这个问题没有绝对答案但有一个决策框架我在项目里用了挺久基本稳。5.1 两者都能做对象结构先看能力对比先看对比表格这里梳理的是最常见的差异对比点interfacetype描述对象结构支持支持继承/扩展用extends用交叉类型合并声明支持同名合并不支持描述基本类型别名不支持支持描述元组不支持直接描述支持描述联合类型不支持支持性能无显著差异无显著差异举个类型别名做交叉类型和联合类型的例子type ID string | number; // 联合类型 type Point { x: number } { y: number }; // 交叉类型 type DataPair [string, number]; // 元组这些用interface都不容易直接表达。所以当目标不只是“对象结构”而是要定义联合类型、元组、基本类型别名时type是更合适的工具。5.2 我的选型习惯公共契约用 interface复杂计算用 type我的经验可以缩成一句话用来做数据契约、跨文件共享、描述领域模型时优先 interface需要联合类型、元组、工具类型转换时用 type。理由也很简单interface天然适合描述“这个对象有这些字段”语义更清晰extends的继承关系可读性比type的交叉符号好。interface支持声明合并declaration merging也就是同名接口会自动合并。这在扩展第三方库类型、给全局对象补充类型时特别有用type做不到。type在处理联合/交叉/元组时更灵活如果对象结构本身很复杂、需要通过交叉组合多个类型type的表达更直接。举一个综合场景说明决策过程用户可能有个人账号或企业账号两种用联合类型表达比接口更清爽interface PersonalAccount { type: personal; name: string; personalId: string; } interface EnterpriseAccount { type: enterprise; companyName: string; creditCode: string; } // 联合类型账户要么是个人要么是企业 type Account PersonalAccount | EnterpriseAccount; function getAccountLabel(account: Account): string { if (account.type personal) { return 个人账户${account.name}; } return 企业账户${account.companyName}; }这里用type联合两个interface完全没问题因为每个账户类型的“形状”依然由interface描述联合的职责交给type。两者是组合关系不是替代关系。5.3 一个常见坑同名接口的声明合并interface声明合并declaration merging是个隐藏能力同名接口会在同一作用域里自动合并成员。interface WindowConfig { theme: string; } // 在另一个文件里再声明一次同名接口 interface WindowConfig { language: string; } // 最终的 WindowConfig 同时拥有 theme 和 language const config: WindowConfig { theme: dark, language: zh-CN };这个机制在扩展全局类型、第三方库类型时很强大但它也带来隐患误声明同名接口时不会报错而是静默合并。所以在团队规范里我一般会建议不要在图方便时随意给接口重名尤其是在多人协作的全局类型声明文件里——一个变量名多个出处排查起来比较痛苦。6. 我在真实项目里整理接口的三条实战经验语法部分到这里基本覆盖了“基本使用一”的核心内容。最后一节分享三个我在真实项目中总结的经验不是文档里会写的东西但挺实用。6.1 接口命名与文件组织按领域模型聚合别按页面拆很多新手会把接口按“页面”组织HomePageTypes.ts、UserPageTypes.ts……结果同一个用户对象在多个页面重复定义改一处漏一处。我的习惯是按领域模型组织user.ts、order.ts、product.ts。每个文件导出该领域的核心接口页面代码直接订阅这些接口。// src/types/user.ts export interface UserProfile { id: number; username: string; avatar?: string; } export interface UserListParams { page: number; pageSize: number; keyword?: string; } export interface UserListResult { list: UserProfile[]; total: number; }命名规范上接口名不加I前缀IUser这种老 Java 风格已经过时直接叫User、Order、Product。这样做的好处是代码读起来自然且不会和类名混淆。6.2 接口与后端数据结构对齐让后端定义成为唯一事实来源前端接口的类型定义最好严格对齐后端返回的 JSON 结构不要自己“美化”字段名。后端用user_id前端类型里就叫user_id: number而不是翻译成userId——否则后端一变名前端又得全局改一遍。当然更推荐的做法是如果团队有条件直接基于 OpenAPISwagger 自动生成前端接口类型。很多工具能从后端的 API 文档生成 TypeScript 类型定义这样前后端天然共享同一个结构。没有自动化条件的项目至少要保证手工维护的接口定义和后端文档同步建议在代码 review 时把接口定义和后端变更一并核对。6.3 别过度抽象接口也不是越多越好接口虽好也不是非要处处使用。一个只有 20 行代码的工具函数参数只有一个简单对象直接内联类型标注就行不用抽接口一个只在此模块内部使用的临时结构体也可以用type直接定义一个别名。接口是为“共享”而生的如果一个类型只在一个文件的一个函数里用一次那么它不该占用公共接口文件里的位置。判断标准其实很简单这个结构是否会被两个以上地方用到是否用于描述领域模型是否会跟随接口文档变化这三个问题至少两个回答“是”才值得抽成接口。提示我在团队里立了一个不成文的规矩——定义接口先看目录里有没有同领域的类型文件有就往里加没有就新建绝不随手塞进业务页面代码里。前三个月大家觉得麻烦半年后接口类型文件百来行却没有一个人喊乱。这篇先聊到这。接口的继承、泛型接口、面向接口编程的进阶玩法会放在“基本使用二”里继续展开。如果你在项目里有自己的接口整理习惯或者踩到过什么接口相关的坑欢迎在评论里聊聊——写 TypeScript 这事真的是互相换踩坑报告才能进步。