1 / 4概念
Types: Narrowing
TypeScript 的类型只在编译期存在,所以它唯一能做的事是「根据你在源码里写的检查,缩小值的类型范围」。判断标准不是会不会写 interface,而是能否说清一次赋值为什么合法、一次收窄为什么安全。
1 概念
1.1 一句话定义
类型是值的集合,可赋值性就是子集判断。结构类型意味着只看成员形状,不看声明来源。收窄是用运行时检查换来的静态信息,检查一旦不成立,类型就不再可靠。
1.2 它解决什么问题
- 提前发现形状错误:拼写、缺字段、错类型在编辑器里就报出来。
- 让契约可检查:函数签名成为调用方与实现方的合同。
- 重构安全:改字段名时所有使用点一起报错。
- 收窄外部输入:把
unknown逐步变成具体类型,而不是一路as。
1.3 不属于本页的内容
| 主题 | 去哪 |
|---|---|
| 泛型、条件类型、映射类型、工具类型 | Generics and Operators |
声明文件、tsconfig、模块解析、装饰器 | Declarations and Config |
| JavaScript 的值与转换语义 | Values and Syntax |
| 运行时 schema 校验库的用法 | 本页 3.4 只给位置,细节看库文档 |
| 其他语言的类型系统 | 各语言章节 |
1.4 关键术语
| 术语 | 含义 | 容易混淆的点 |
|---|---|---|
| 结构类型 | 看成员形状 | 不是名义类型,不认类名 |
| 可赋值性 | 子集关系 | 与相等不是一回事 |
| 联合 | 取并集 | A | B 的成员都能赋值给它 |
| 交叉 | 取交集 | 冲突属性会变成 never |
| 字面量类型 | 单个值构成的类型 | as const 才保留 |
unknown | 顶端类型 | 用之前必须收窄 |
never | 底端类型 | 可赋值给任何类型,反之不行 |
any | 逃逸检查 | 既是顶端也是底端 |
| 收窄 | 条件成立后的类型缩小 | 条件说谎,类型就错 |
| 判别联合 | 用字面量字段区分成员 | 穷尽检查依赖它 |
| 双变 | 参数既协变又逆变 | strictFunctionTypes 关闭它 |
| 新鲜字面量检查 | 字面量赋值的多余属性报错 | 先赋给变量就绕过 |
2 机制
2.1 心智模型
把类型想成集合。A 能赋给 B,就是 A ⊆ B。收窄就是在一个分支里把集合缩小;if 的条件决定了缩小多少。断言是你告诉编译器集合更小,但没有任何运行时证据。
2.2 机制拆解
- 结构匹配:目标类型需要的成员源类型都有,就能赋值;多出来的成员通常允许。
- 新鲜对象字面量:直接写的字面量会检查多余属性,先赋给变量再传就不会。
- 联合与交叉:联合的每个成员都必须满足;交叉同时满足,冲突时化为
never。 - 三个特殊类型:
unknown只能收窄后使用;never表示不可达;any传染并关闭检查。 - 收窄来源:
typeof、instanceof、in、===、判别字段、类型守卫、断言函数、索引访问检查。 - 判别联合:共同的字面量字段让每个分支的类型确定,
switch加never兜底就是穷尽检查。 - 函数变型:
strictFunctionTypes打开后,参数位逆变、返回值位协变;方法仍按双变处理。
2.3 完整枚举
八种收窄手段,这是完整集合:
| 手段 | 写法 | 收窄到什么 |
|---|---|---|
typeof | typeof x === 'string' | 对应的原始类型 |
instanceof | x instanceof Date | 该类及其子类 |
| 属性存在 | 'id' in x | 含该属性的分支 |
| 相等比较 | x === null | 该字面量类型 |
| 判别字段 | switch (x.kind) | 对应联合成员 |
| 真值判断 | if (x) | 排除 null、undefined、false、0、'' |
| 类型守卫 | function isUser(x): x is User | 守卫声称的类型 |
| 断言函数 | function assertUser(x): asserts x is User | 调用点之后成立 |
特殊类型全表:
| 类型 | 顶端或底端 | 可赋值给谁 | 典型用途 |
|---|---|---|---|
any | 两端 | 任何类型 | 隔离的适配层 |
unknown | 顶端 | 只能赋给 unknown 与 any | 外部输入 |
never | 底端 | 任何类型 | 穷尽检查、永不返回 |
void | — | undefined 可赋给它 | 无返回值的函数 |
object | — | 非原始值 | 泛型约束 |
{} | — | 除 null 与 undefined 外的任何值 | 含义常被误读 |
null | — | 严格模式下只赋给自身 | 显式空值 |
undefined | — | 严格模式下只赋给自身 | 缺失 |
strict 家族的全表,打开 strict 等于打开前九个:
| 选项 | 作用 |
|---|---|
strict | 总开关 |
noImplicitAny | 禁止隐式 any |
strictNullChecks | null 与 undefined 不再属于其他类型 |
strictFunctionTypes | 参数位逆变 |
strictBindCallApply | 收紧 bind、call、apply 的参数 |
strictPropertyInitialization | 类字段必须初始化 |
noImplicitThis | 禁止隐式 this |
alwaysStrict | 输出严格模式 |
useUnknownInCatchVariables | catch 变量为 unknown |
noUncheckedIndexedAccess | 索引访问结果加 undefined |
exactOptionalPropertyTypes | 可选属性不接受显式 undefined |
noImplicitOverride | 覆写必须写 override |
四种「我说了算」的写法,检查强度依次下降:
| 写法 | 是否检查 | 是否改类型 | 典型用途 |
|---|---|---|---|
| 类型守卫 | 运行时检查 | 是 | 解析外部数据 |
satisfies | 检查赋值 | 否,保留字面量类型 | 配置对象 |
类型断言 as | 单向兼容检查 | 是 | 已知比编译器更清楚的边界 |
非空断言 ! | 不检查 | 去掉 null 与 undefined | 极少使用 |
2.4 关键数字与量级
| 指标 | 量级 | 说明 |
|---|---|---|
| 实例化深度上限 | 约五十层 | 超过报 excessively deep |
| 联合成员数量 | 数百个后明显变慢 | 条件类型会按成员展开 |
strictNullChecks 影响 | 全库级 | 打开后错误数量通常翻倍 |
any 传染范围 | 调用链 | 一次 any 会污染返回值 |
| 类型检查耗时 | 与泛型实例数量正相关 | CI 里单独统计 |
3 实践
3.1 最小示例
判别联合加穷尽检查。新增成员时,编译器会在兜底分支报错,这是本页最值得记住的模式。
type Shape =
| {kind: 'circle'; radius: number}
| {kind: 'rect'; width: number; height: number};
function area(shape: Shape): number {
switch (shape.kind) {
case 'circle':
return Math.PI * shape.radius ** 2;
case 'rect':
return shape.width * shape.height;
default:
return assertNever(shape);
}
}
function assertNever(value: never): never {
throw new Error(`unhandled shape: ${JSON.stringify(value)}`);
}
area({kind: 'rect', width: 2, height: 3}); // 6
追踪:shape.kind 是字面量字段,case 'circle' 把类型收窄到第一个成员,shape.radius 合法。加入第三种形状后,default 里的 shape 不再等于 never,assertNever 的参数类型不成立,编译失败。
3.2 常用操作与参数
| 操作 | 写法 | 说明 |
|---|---|---|
| 接外部输入 | const data: unknown = JSON.parse(text) | 先 unknown 再收窄 |
| 收窄对象 | if (isUser(data)) | 守卫内部要做真实检查 |
| 校验配置 | const config = {...} satisfies Config | 保留字面量类型 |
| 固定字面量 | const levels = ['low', 'high'] as const | 元素变成字面量类型 |
| 排除空值 | if (value != null) | 同时排除两者 |
| 索引访问 | 打开 noUncheckedIndexedAccess | 强制处理缺失 |
| 覆写检查 | override 关键字 | 防止拼错父类方法 |
| 异常收窄 | error instanceof Error | catch 变量是 unknown |
3.3 标准流程
- 外部数据先声明
unknown,不要用any接。 - 在边界写守卫或 schema 解析,把
unknown变成领域类型。 - 领域模型用判别联合表达「几种可能之一」。
- 用
satisfies校验配置形状,避免as。 - 穷尽检查兜底,让新增成员在编译期暴露。
- 打开
strict、noUncheckedIndexedAccess与exactOptionalPropertyTypes。
3.4 与相邻技术的组合
- JavaScript 值模型:
typeof null是'object',守卫里要单独判null。 - 泛型:守卫可以写成泛型函数,但只能收窄到声明的类型。
- 运行时校验:zod、valibot 这类库把 schema 变成类型,比手写守卫更可靠。
- 框架:组件 props 是结构类型,多传属性通常不报错。
- API 客户端:响应类型必须与运行时校验一起用,类型不会验证响应体。
3.5 选型维度
| 维度 | 取值 | 影响 |
|---|---|---|
| 表达方式 | type / interface / class | 扩展与合并语义 |
| 逃逸类型 | unknown / any / 断言 | 检查强度 |
| 多态 | 联合 / 泛型 / 重载 | 调用方推断质量 |
| 空值 | 可选属性 / 联合 undefined / 默认值 | 调用方负担 |
| 校验位置 | 编译期 / 运行时 / 两者 | 可靠性 |
3.6 决策规则
- 外部输入一律
unknown,在边界收窄;any只出现在隔离的适配层。 - 对象形状用
type;需要声明合并或供他人扩展时用interface。 - 有限集合用字符串联合,不用
enum制造运行时对象。 - 校验配置用
satisfies,不要用as跳过检查。 - 联合成员超过三个且需要按种类分支时,改用判别联合。
- 断言只写在确实比编译器知道得更多的地方,并且紧邻注释说明理由。
3.7 替代方案对比
| 方案 | 优势 | 代价 | 适用 |
|---|---|---|---|
unknown 加守卫 | 强制检查 | 需要写守卫 | 外部输入 |
any | 立刻通过 | 关闭检查、传染 | 隔离适配层 |
as | 快速 | 没有运行时证据 | 极少数边界 |
satisfies | 检查且保留字面量 | 不能改变类型 | 配置对象 |
| 判别联合 | 分支类型精确 | 需要公共字段 | 状态机、事件 |
enum | 具名常量 | 运行时对象、窄化复杂 | 需要反向映射的旧代码 |
| 字符串联合 | 轻量、可穷举 | 没有运行时成员 | 大多数有限集合 |
3.8 何时不该用
- 不要用类型断言代替运行时校验,
as User不会检查任何字段。 - 不要在业务代码里堆条件类型,可读性会先崩。
- 不要为三个字段的对象写
interface加继承层次。 - 不要用
enum只为拿几个常量,字符串联合更轻。 - 不要打开全部严格选项后靠
!和as压掉报错,那是把检查换成了噪音。
4 边界
4.1 典型故障
| 症状 | 根因 | 处理 |
|---|---|---|
| 运行时字段缺失但编译通过 | 断言绕过了检查 | 补守卫或 schema |
catch 里读 error.message 报错 | 变量是 unknown | instanceof Error 收窄 |
| 数组索引结果没判空 | 未开 noUncheckedIndexedAccess | 打开并处理 undefined |
可选属性传 undefined 报错 | exactOptionalPropertyTypes | 省略键或改类型 |
交叉类型成员全变 never | 属性冲突 | 拆分类型 |
| 多传属性没报错 | 先赋给变量绕过了新鲜检查 | 直接传字面量或加索引签名 |
| 守卫返回真但字段不对 | 守卫里的检查不完整 | 守卫与类型同步维护 |
| 函数参数逆变报错 | strictFunctionTypes | 调整参数类型或改方法写法 |
4.2 反模式
| 做法 | 后果 | 替代 |
|---|---|---|
满屏 any | 检查失效 | unknown 加守卫 |
as unknown as T 双跳 | 完全绕过检查 | 重构类型或解析 |
! 连续使用 | 空值错误推到运行时 | 显式判空 |
守卫里 return true | 类型说谎 | 逐字段检查 |
用 interface 表达联合 | 无法穷尽 | type 加判别字段 |
全局 declare 改内置类型 | 影响所有代码 | 局部包装类型 |
4.3 可观测信号
tsc 错误数按目录分布、any 与 as 的出现次数、断言函数与守卫的数量、strict 开关状态、运行时校验失败率与类型断言处的异常率。
4.4 安全 / 性能 / 一致性边界
- 类型不是安全边界:编译后类型全部消失,不可信输入必须在运行时验证。
- 性能边界:庞大的联合与深层泛型会显著拖慢类型检查,CI 里要盯编译时间。
- 一致性边界:一个领域类型只在一处定义,其他地方派生;否则声明会漂移。
- 兼容边界:结构类型允许「多余的字段」,跨服务传输时要以 schema 为准,不以类型为准。