跳到正文

我所理解的 TypeScript 最佳实践(15):先校验外部数据,再使用收窄后的类型

我所理解的 TypeScript 最佳实践

  1. 为什么选择 TypeScript
  2. 严格模式
  3. 使用常量枚举来管理状态
  4. 按运行环境处理 TypeScript 代码
  5. 类型检查、Lint 与测试
  6. TypeScript 7 升级与工具链兼容
  7. 用 satisfies 检查类型并保留推断
  8. 用 import type 区分类型依赖和运行时依赖
  9. 用对象类型表达字段约束
  10. 用联合类型表达备选,用交集类型叠加约束
  11. 用元组描述位置固定的数据
  12. 用泛型保留类型关系,用 extends 写约束和条件
  13. 按目标类型判断赋值是否成立
  14. 按输入和输出设计泛型的协变与逆变
  15. 先校验外部数据,再使用收窄后的类型(当前)
  16. 让局部实现保留推断,用注解约束公开接口
  17. 从一份定义派生配置、命令和事件的类型
  18. 用判别联合排除互斥的状态组合
  19. 用 never 表示没有值的类型
  20. 用逆向映射推断还原字段类型

读取旧版草稿时,文件里可能把字号存成字符串 "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 消息进入应用的位置。下游的渲染、保存和计算函数直接接收校验后的类型。这样修改字段约定时,可以从数据入口检查旧值会怎样处理,再用类型检查找出依赖这一字段的代码。