【TypeScript】 在业务项目中的类型治理

TypeScript 在业务项目中的类型治理重点不是写类型而是少挖坑一、很多团队用了 TypeScript为什么还是经常出问题很多项目上了 TypeScript 之后表面看起来挺规范接口有类型组件参数有类型函数入参也有类型但实际开发里问题还是很多后端字段一变前端一大片报错或者静默出错列表页、详情页、弹窗页各自写一套类型越写越重复为了图省事到处any代码能通过编译但业务逻辑还是容易出错这说明一个问题TypeScript 用了不代表类型治理做好了。真正麻烦的从来不是“会不会写 interface”而是“类型有没有真正管住业务”。二、什么叫类型治理我理解的类型治理不是把项目变成类型体操比赛而是做三件事让关键数据结构有统一出口让错误尽量提前暴露在开发阶段让多人协作时代码更不容易写偏说白了类型治理不是为了看起来高级而是为了减少沟通成本和返工成本。三、业务项目里最常见的类型问题1. 接口类型到处复制这个问题特别常见。比如一个用户模块可能会出现用户列表类型用户详情类型用户编辑类型用户表单类型用户筛选参数类型如果这些类型都是各写各的过一段时间你就会发现同一个字段在不同文件里名字不一样有的地方是可选有的地方是必填后端一改字段改不全2. 把类型写在离业务太远的地方有些项目喜欢把所有类型都堆到一个超大的types.ts里看起来像统一管理实际上很容易失控。因为业务模块多了之后这种文件会越来越难找也很容易出现“改这个类型会影响谁我也不知道”的情况。3.any用着用着就收不回来了最开始大家一般都会说“先用any顶一下后面再补。”现实通常是后面根本没人补。而且any最麻烦的地方不是它本身而是它会让错误一路传染。一个地方放开后面几个函数的约束都可能失效。4. 类型只是“写了”没有参与设计这个问题很隐蔽。比如一个接口返回状态值后端约定只有012但前端直接写成number。这样当然也能跑但类型没有把真实业务边界表达出来后面判断分支还是容易写松。四、我做类型治理时比较看重的 4 个原则1. 先管核心链路不追求一次全覆盖业务项目里最忌讳一上来就想“把所有类型都补齐”。因为工作量大而且收益不平均。更现实的做法是优先治理这些地方接口请求和响应核心业务实体公共组件入参表单模型字典映射和状态枚举这些地方一旦稳定下来很多问题会明显变少。2. 类型要围绕业务模型组织比如用户模块就围绕用户这件事收类型而不是东一块西一块散着放。一个比较实用的思路是按模块拆// user.types.tsexportinterfaceUserItem{id:stringname:stringstatus:UserStatus phone?:string}exportinterfaceUserQueryParams{keyword?:stringstatus?:UserStatus pageNum:numberpageSize:number}exportinterfaceUserFormData{name:stringstatus:UserStatus phone:string}exporttypeUserStatus0|1|2这样做的好处是别人看这个模块时能比较快找到相关类型。3. 类型命名要能直接看懂用途比起写一堆模糊命名我更建议把用途写清楚。例如UserItemUserDetailUserQueryParamsUserFormDataCreateUserRequestUserListResponse这种命名虽然不花哨但最适合协作。4. 严控any但别过度炫技我不赞成项目里大量使用any但也不赞成为了“类型高级”而把代码写得没人看得懂。业务项目里最重要的是类型能表达真实约束团队成员看得懂出问题时好定位如果一个类型技巧写完之后只有写的人自己能维护那它的收益通常没想象中那么高。五、我认为最有价值的治理点1. 把接口层先管住这一层是最值得先做的。因为业务项目里的很多混乱都是从接口字段开始扩散的。比如统一请求返回exportinterfaceApiResponseT{code:numbermessage:stringdata:T}exportinterfacePageResultT{list:T[]total:number}然后接口函数明确返回值exportfunctiongetUserList(params:UserQueryParams){returnrequestApiResponsePageResultUserItem({url:/user/list,method:get,params})}这样列表页拿到的数据结构就更稳定不容易“猜着用”。2. 把状态值、字典值收成明确类型很多 bug 都出在“值是对的但判断写错了”。比如状态字段如果只是number或string那任何值都能进来。更稳的方式是exporttypeUserStatusenabled|disabled或者exportenumUserStatus{Enabledenabled,Disableddisabled}这样不仅代码提示更清楚也能减少魔法值乱飞的问题。3. 让表单类型和接口类型分开这点很多项目容易混。因为接口详情数据和页面表单数据看起来很像但它们经常不是一回事。比如详情接口里有创建时间、更新时间、创建人表单提交根本不需要这些字段某些字段接口返回可能是null但表单里要转成空字符串所以我的建议是UserDetail归接口模型UserFormData归页面交互模型不要为了省一点定义成本把两者硬绑在一起。4. 公共组件的类型要收紧业务项目里很多问题其实是从“组件什么都能传”开始的。比如一个表格组件、弹窗组件、选择器组件如果入参太松调用方就会乱传后面排查很麻烦。所以公共组件一定要尽量做到必填参数明确可选参数边界清楚事件回调签名明确这一步做好团队协作会舒服很多。六、类型治理落地时怎么做更现实第一阶段先禁住最危险的写法例如减少新增any避免接口返回裸Promiseany公共模块禁止随意复制类型这一阶段不用追求多漂亮先把口子收住。第二阶段按业务模块逐步收口比如先从用户模块、订单模块、权限模块这种核心模块开始。做法可以是统一实体类型统一查询参数类型统一接口返回类型统一表单数据类型这样一个模块一个模块推进团队更容易接受。第三阶段把规范变成默认动作到了这一步重点已经不是“补类型”而是让大家自然按照同一套方式写。例如新接口必须补响应类型新页面必须定义查询参数和表单模型公共组件必须补 props 和 emits 类型当这些成为默认动作时类型治理才算真正落地。七、几个很现实的落地建议1. 不要拿类型系统硬套混乱业务如果业务字段本身就混乱比如同一状态值不同接口定义不一致那先解决接口约定问题再谈类型治理。不然只是把混乱用另一种形式写进代码里。2. 类型文件不要贪大而全按模块收比按全局收更稳。因为业务项目后期维护最怕的不是类型少而是类型找不到、改不动、牵一发动全身。3. 先做高频、核心、易出错的部分不是所有地方都值得投入同样精力。把最关键的数据链路先管住收益会比追求 100% 覆盖更高。4. 团队要接受“够用的类型”不是“最炫的类型”业务项目看的是长期维护不是秀技巧。只要能把边界表达清楚、把错误提前暴露出来就已经很有价值了。八、最后总结TypeScript 在业务项目里最核心的作用不是让代码看起来更高级而是帮你减少低级错误、减少沟通歧义、减少后期返工。类型治理真正该做的不是铺天盖地补类型而是把关键链路管住接口层核心业务实体表单模型状态枚举公共组件边界把这些地方做好项目会稳很多。反过来说如果项目里还是到处any类型重复定义接口模型和页面模型混用状态值乱写那就算已经用了 TypeScript最后也只是“看起来有类型实际上还在裸奔”。