跳到正文
小佑Blog 站点标识小佑Bloglordblog.cn

TypeScript 类型收窄:把 38 处 any 压到 2 处

语言基础更新 2026-11-12类型收窄

2026 年 2 月,一个 2.4 万行的前端仓库里有 38 处 any,其中 21 处集中在接口返回值的解析层。这一期用 5 种收窄手段把这 38 处压到 2 处,编译时间从 8.4 秒降到 7.9 秒。

这一期要解的问题

any 的可怕之处不在它本身,而在它会传染。一个接口函数返回 any,调用它的三个组件全部失去类型检查,再往外传两层,整条数据链路都变成裸奔。等到线上出现“某个字段是 undefined”,编译器一句都帮不上。

收窄的关键不是加 as,而是把“我不知道返回什么”变成“我知道有哪几种可能”。这一期先处理接口层:把 21 处 any 换成可判别的联合类型,再用类型守卫把分支写清楚。剩下的 17 处散在组件 props、事件回调、第三方 SDK 的声明文件里,逐类处理。

五种收窄手段与章节顺序

  • 第 1 章 先统计:用 tsc --noEmit 加一条脚本,把 38 处 any 按文件、按行标出来
  • 第 2 章 typeof 与 instanceof:处理基本类型与类实例的 11 处
  • 第 3 章 可判别联合:把接口返回的 21 处 any 改成带 kind 字段的联合类型
  • 第 4 章 自定义类型守卫:is 关键字在 6 个校验函数里的写法与陷阱
  • 第 5 章 泛型约束:把 4 个工具的返回值从 any 拉到受约束的 T
  • 第 6 章 断言函数 asserts:给 3 个前置校验写 asserts 签名,让后续代码自动收窄
  • 第 7 章 声明文件:给两个没有类型的 SDK 补 d.ts,只写用到的 9 个成员
  • 第 8 章 回归:把 strict 开到最高三档,逐个处理新冒出的 41 条报错
// 第 3 章示例:把 any 换成可判别联合,报错从运行时挪到编译期
type Result =
  | { kind: 'ok'; data: Row[] }
  | { kind: 'empty' }
  | { kind: 'error'; code: number; message: string };

function render(r: Result) {
  switch (r.kind) {
    case 'ok': return paint(r.data);
    case 'empty': return blank();
    case 'error': return warn(r.code, r.message);
  }
}

参数与交付

项目内容
难度中等,需写过 TS 业务代码
章节8 章,含 5 种收窄手段与 41 条报错的处理记录
实测时长9 小时(读 5 小时 + 改造 4 小时)
验证环境TypeScript 6.0.2 / Node 26.1 / VS Code 1.10x
前置知识知道 interface、泛型、联合类型的基本写法
配套资源改造前后两版仓库、tsc 统计脚本、报错清单
更新节奏随 TS 大版本每年同步一次
阅读授权单账号,可读 24 个月

三个会用到它的场合

接口层没人敢动

后端字段增删频繁,前端为了不炸全部写 any。第 3 章的可判别联合能把 21 处集中改造,改造后新增字段漏接会在编译期报错,而不是等到页面上显示 undefined。

多人协作的组件库

组件 props 写 any,等于把调用方的错误留到运行时。把 4 个基础组件的 props 用泛型约束住之后,调用处会立刻出现 30 多条红线,这些红线里有一半是真实的传值错误。

第三方 SDK 没有类型

第 7 章的做法是只补用到的成员,不追求完整声明。一个 9 个成员的 d.ts 文件,20 分钟能写出来,比等官方发类型定义快得多。

和常见讲法差在哪

  • 给了改造前后的两版仓库,diff 能逐行看。多数教程只讲“用 is 收窄”,不给你一个 2.4 万行的仓库去练。
  • 把 strict 开到最高三档后的 41 条报错单独列了一章,逐条给处理方式。这一步才是真正卡人的地方。
  • 编译时间前后都记了:8.4 秒到 7.9 秒。类型体操写得再花,编译慢 3 秒也不划算,这个取舍在文中写明了。

交付周期与阅读节奏

付款后 10 分钟开通,仓库 24 小时内邀请。8 章建议两天读完,第一天读 1—4 章并在自己项目里试一个文件,第二天读 5—8 章做整体改造。改造部分建议单独开分支,按 214 份结课记录,中位改造耗时 4 小时。

服务条款

14 天内可退。tsc 统计脚本随仓库长期可拉取,可直接放进自己项目的 scripts 目录。若 TypeScript 升到大版本导致示例报错,会在 20 个工作日内补丁;大版本改动较大的章节会单独发修订说明。

选型建议

仓库里 any 少于 10 处,或者团队还没开 strict,这一期可以往后放。真正值得投入的是接口层 any 集中、且改一次字段就要回归一轮的项目。另一种情况是准备开 strict:先把 any 清掉再开 strict,报错量能少一半,这一期正好是清 any 的路径。

读完常见的问题

用 JavaScript 的项目能读吗?
不建议。这一期默认你有 TS 基础,第 2 章起就直接用类型语法,没有 JS 版对照。
必须升到 TypeScript 6.0 吗?
不必。收窄语法在 4.9 以上都可用,仓库另附一份 5.x 的 tsconfig,差异只在小部分配置项。
会不会讲类型体操?
几乎不讲。全文只在第 5 章用了 3 个条件类型,目的是约束返回值,不是为了炫技。

同方向的其他两期