我所理解的 TypeScript 最佳实践(15):先校验外部数据,再使用收窄后的类型
- 为什么选择 TypeScript
- 严格模式
- 使用常量枚举来管理状态
- 按运行环境处理 TypeScript 代码
- 类型检查、Lint 与测试
- TypeScript 7 升级与工具链兼容
- 用 satisfies 检查类型并保留推断
- 用 import type 区分类型依赖和运行时依赖
- 用对象类型表达字段约束
- 用联合类型表达备选,用交集类型叠加约束
- 用元组描述位置固定的数据
- 用泛型保留类型关系,用 extends 写约束和条件
- 按目标类型判断赋值是否成立
- 按输入和输出设计泛型的协变与逆变
- 先校验外部数据,再使用收窄后的类型(当前)
- 让局部实现保留推断,用注解约束公开接口
- 从一份定义派生配置、命令和事件的类型
- 用判别联合排除互斥的状态组合
- 用 never 表示没有值的类型
- 用逆向映射推断还原字段类型
读取旧版草稿时,文件里可能把字号存成字符串 "18"。如果读文件的函数用 as EditorPreferences 告诉 TypeScript 字号是数字,后面调用 .toFixed() 仍然会在运行时失败。外部数据进应用时,可以先用 unknown 接住,再检查业务实际要用的字段。通过检查之后,TypeScript 才有依据收窄类型。
先确认 JSON 能解析,再检查字段和值
JSON.parse() 能确认一段文本符合 JSON 语法。它也能成功读出 null、数组或字段类型错误的对象。下面的草稿设置要求字号在 12 到 36 之间,且大纲开关是布尔值。读取函数只把检查通过的字段交给应用。
type EditorPreferences = {
fontSize: number;
showOutline: boolean;
};
function readEditorPreferences(text: string): EditorPreferences | undefined {
let raw: unknown;
try {
raw = JSON.parse(text);
} catch {
return undefined;
}
if (typeof raw !== 'object' || raw === null) {
return undefined;
}
if (!('fontSize' in raw) || !('showOutline' in raw)) {
return undefined;
}
const { fontSize, showOutline } = raw;
if (typeof fontSize === 'number' && fontSize >= 12 && fontSize <= 36 && typeof showOutline === 'boolean') {
return { fontSize, showOutline };
}
return undefined;
}
const valid = readEditorPreferences('{"fontSize":18,"showOutline":false}'); // 有效,保留 false
const invalid = readEditorPreferences('{"fontSize":"18","showOutline":false}'); // undefined
const incomplete = readEditorPreferences('{"fontSize":18}'); // undefined
const malformed = readEditorPreferences('{"fontSize":18,}'); // undefined
通过第一组检查后,raw 是非空对象。通过 in 检查后,TypeScript 允许读取对应字段,但字段值还是未知的。最后一组 typeof 检查让 TypeScript 得到 number 和 boolean,范围检查则拒绝字号超出约定的数据。返回的新对象只包含这次验证过的两个字段。这里用 undefined 表示无法恢复设置,调用方可以使用默认值。如果界面需要区分语法错误、字段缺失和范围错误,可以返回带错误原因的判别联合。类型沿分支变化的过程见 TypeScript 手册的控制流分析。
类型守卫的真假两条分支都需要成立
同一项类型检查会在多处使用时,可以提取成类型守卫。下面的函数识别 HTML 输入元素,调用者可以在通过的分支读取 .value。
function isInputElement(target: EventTarget | null): target is HTMLInputElement {
return target instanceof HTMLInputElement;
}
function readInputValue(event: Event) {
if (isInputElement(event.target)) {
return event.target.value;
}
return undefined;
}
target is HTMLInputElement 对两个分支都作了承诺。返回 true 表示输入元素已经确认,返回 false 让 TypeScript 从候选类型中排除它。额外的业务筛选可能打破这项承诺。比如 typeof value === 'number' && value > 0 返回 false 时,value 仍可能是数字 0。若将其标为 value is number,对于 string | number,调用方就可能在假分支把 0 当成字符串处理。可以先用 typeof 收窄为数字,再检查它是否为正数。两条分支的承诺见 TypeScript 5.5 的类型谓词说明。
同样的差别也出现在 .filter() 里。下面只想去掉缺失值,因此明确检查 undefined。TypeScript 5.5 起能为这条回调推断类型谓词。
const offsets: (number | undefined)[] = [0, undefined, 12];
const knownOffsets = offsets.filter(offset => offset !== undefined); // number[],保留 0
const nonZeroOffsets = offsets.filter(Boolean); // 运行时只剩 12
同一份 Schema 可以校验数据并提供类型
外部数据只有几个字段时,上面的手写检查足够直观。遇到嵌套对象、数组、多个输入入口,或界面需要显示具体错误字段时,可以考虑用 Schema 集中描述约束。以 Zod 为例,safeParse() 返回成功或失败的结果,z.infer 直接从同一份 Schema 得到输出类型。
import { z } from 'zod';
const editorPreferencesSchema = z.object({
fontSize: z.number().min(12).max(36),
showOutline: z.boolean(),
});
type EditorPreferences = z.infer<typeof editorPreferencesSchema>;
function readEditorPreferences(raw: unknown): EditorPreferences | undefined {
const result = editorPreferencesSchema.safeParse(raw);
return result.success ? result.data : undefined;
}
读取文件时仍然要先解析 JSON,再把解析结果传给 Schema。需要向用户说明具体失败原因时,可以在失败分支读取 result.error.issues。如果 Schema 还会转换数据,例如把字符串转换成日期,z.input 和 z.output 可以分别表示转换前后的类型。用法见 Zod 的校验结果和类型推断文档。
输入校验适合放在文件读取、HTTP 响应、IPC 或 Worker 消息进入应用的位置。下游的渲染、保存和计算函数直接接收校验后的类型。这样修改字段约定时,可以从数据入口检查旧值会怎样处理,再用类型检查找出依赖这一字段的代码。