类型守卫

是什么，为什么存在

TypeScript 的静态类型在程序运行前工作，但 JavaScript 的值仍会在运行时从网络、文件、消息和无类型调用方进入。一个声明为 string | number 的参数也只能安全使用两种成员共有的操作。代码需要提供证据，才能执行只属于其中一种类型的操作。

类型守卫就是这份证据。typeof value === "string" 不只计算一个布尔值；TypeScript 还会在成立分支中把 value 视为 string。这种根据分支、赋值和可达性持续更新「当前可能类型」的过程叫作 控制流收窄（control-flow narrowing） 。

守卫没有给 JavaScript 加入新的运行机制。typeof、instanceof、in、相等比较和属性比较都照常运行，编译器只是理解其中一部分表达式的含义。接口和联合类型会被 类型擦除（type erasure） ，因此外部输入仍然需要真实的运行时检查。

你会在处理 unknown、可空值、联合类型、解析后的 JSON 和回调参数时使用守卫。守卫适合回答「这个值现在是否满足某个类型」；如果失败必须立即终止，则用断言函数表达更清楚。

工作原理

每个变量都有声明类型，也有控制流当前位置的观察类型。声明类型决定以后允许赋入哪些值，观察类型则描述沿当前路径还能到达这里的值。一次检查可以缩小观察类型，但不会改写原来的声明。

编译器识别的证据

TypeScript 能识别常见 JavaScript 检查，也能沿短路表达式和提前返回传播结果。下面的形式覆盖大多数日常守卫；它们检查的运行时事实并不相同。

typeof 最适合区分字符串、数字、布尔值、bigint、symbol、undefined、函数和宽泛对象。对象分支必须单独排除 null；数组应使用 Array.isArray()，类实例可以使用 instanceof。这些检查给出的类型不会比运行时证据更具体。

in 检查属性名是否能在对象上找到，包括原型链上的属性。用于联合类型时，成立分支保留具有必填或可选该属性的成员，不成立分支保留缺少该属性或只把它声明为可选的成员。若输入是 unknown，应先证明它是非空对象，再使用 in。

字面量判别字段通常比零散的属性探测更稳定。若每个联合成员都带有 kind、status 或 type，比较这个字段就能收窄整个对象及其载荷。新增成员时，再配合 never 做穷尽性检查，遗漏分支会变成编译错误。

自定义谓词与断言

内置检查无法为复杂对象命名时，函数可以返回 类型谓词（type predicate） ，例如 value is Shipment。调用方在真分支中得到 Shipment，在假分支中也会排除相应类型。函数体必须承担这份双向含义，编译器只检查谓词类型是否能赋给参数类型，不会替你验证实现逻辑。

断言函数（assertion function） 使用 asserts value is Type 或 asserts condition。它正常返回时，后续代码得到收窄结果；条件不满足时，函数应抛出异常或以其他方式永不返回。它适合不可恢复的配置错误和内部不变量，不适合把普通无效输入变成意外异常。

类型谓词和断言函数都不同于 类型断言（type assertion） 。value as Shipment 只改变检查器的看法，不执行检查，也不转换值。只要数据来自类型系统之外，as 就不能替代边界验证。

示例

下面四个程序由本地 tsx 实际执行，并在 strict 模式下完成类型检查。它们依次展示内置守卫、对象结构验证、数组谓词和断言函数。

原始值与类实例

第一个例子通过提前返回逐步排除联合成员。走到最后一行时，字符串和 Date 已被排除，因此只剩 number。

instanceof Date 检查原型链，所以成立分支可以调用 toISOString()。这个证据适用于代码创建的 Date 实例；JSON 中的日期仍是字符串，必须解析后才能成为 Date。

提前返回让剩余路径自然收窄，比在每个分支里写类型断言更可靠。若以后给 Input 加入新成员，最后的数字操作会促使你重新检查分支是否完整。

验证 JSON 对象

解析 JSON 后先保留 unknown。isRecord() 只证明容器可读取，isShipment() 再检查必填字段、有限数字和允许的状态值。

type Shipment = {
  id: string;
  state: "packed" | "sent";
  weightKg: number;
};

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null;
}

function isShipment(value: unknown): value is Shipment {
  return (
    isRecord(value) &&
    typeof value.id === "string" &&
    (value.state === "packed" || value.state === "sent") &&
    typeof value.weightKg === "number" &&
    Number.isFinite(value.weightKg) &&
    value.weightKg >= 0
  );
}

function decodeShipment(raw: string): Shipment | undefined {
  const value: unknown = JSON.parse(raw);
  return isShipment(value) ? value : undefined;
}

for (const raw of [
  '{"id":"PK-42","state":"sent","weightKg":2.5}',
  '{"id":"PK-43","state":"waiting","weightKg":"2.5"}',
]) {
  const shipment = decodeShipment(raw);
  console.log(shipment ? `${shipment.id}:${shipment.state}` : "rejected");
}

PK-42:sent
rejected

第二条记录同时包含非法状态和字符串重量，所以守卫返回 false。调用方不需要重复字段检查；只有通过同一条边界的值才获得 Shipment 类型。

typeof value.weightKg === "number" 仍会接受 NaN 和无穷大。示例继续使用 Number.isFinite() 并检查非负约束，因为领域类型的承诺应覆盖业务代码实际依赖的条件。

这个守卫允许额外字段，因为它验证的是 Shipment 所需的最小结构。若协议禁止未知字段，应显式比较键集合；不要把「结构足够」和「结构完全相等」混为一谈。

把谓词带入数组过滤

数组方法可以消费类型谓词。显式返回 job is AssignedJob 后，filter() 的结果不再是普通 Job[]，其中每个元素的 owner 都是字符串。

type Job = {
  id: number;
  owner?: string;
};

type AssignedJob = Job & { owner: string };

function hasOwner(job: Job): job is AssignedJob {
  return typeof job.owner === "string" && job.owner.trim().length > 0;
}

const jobs: Job[] = [
  { id: 101, owner: "Mina" },
  { id: 102 },
  { id: 103, owner: "" },
];

const assigned = jobs.filter(hasOwner);

for (const job of assigned) {
  console.log(`${job.id}:${job.owner.toUpperCase()}`);
}

101:MINA

谓词检查的不只是属性存在，还排除了空字符串和纯空白字符串。AssignedJob 把调用方真正获得的保证写进类型，后续无需非空断言。

若回调只返回普通 boolean，某些简单表达式可以由 TypeScript 推断为谓词，但复杂条件未必能推断。公共辅助函数显式写出谓词有助于审查承诺，前提是测试同时覆盖真分支和假分支。

失败即中止的断言函数

端口无效时，调用方无法继续启动服务，因此断言比返回布尔值更贴合控制流。正常返回后，port 被收窄为 number。

function assertPort(value: unknown): asserts value is number {
  if (
    typeof value !== "number" ||
    !Number.isInteger(value) ||
    value < 1 ||
    value > 65_535
  ) {
    throw new TypeError("port must be an integer from 1 to 65535");
  }
}

function startServer(port: unknown): string {
  assertPort(port);
  return `listening:${port}`;
}

for (const candidate of [443, "443", 70_000]) {
  try {
    console.log(startServer(candidate));
  } catch (error) {
    const message = error instanceof Error ? error.message : String(error);
    console.log(`rejected:${message}`);
  }
}

listening:443
rejected:port must be an integer from 1 to 65535
rejected:port must be an integer from 1 to 65535

断言检查了整数和范围，而不只是 number。这说明类型收窄与领域验证是两层工作：静态类型只能表达这里的 number，运行时函数还负责端口约束。

捕获变量默认按 unknown 处理更安全，因为 JavaScript 可以抛出任何值。error instanceof Error 保留标准错误消息，后备分支则处理字符串、对象或其他抛出值。

陷阱

修复： 从 unknown 开始，逐项检查业务代码将读取的字段及其领域约束。给守卫准备有效值、缺字段、错类型、null、数组和边界数字等测试，不要只测试一个成功样例。

修复： 让 x is T 当且仅当 x 属于 T 时成立。只想筛选更小的业务子集时，定义能准确表达该子集的类型，或者返回普通 boolean，不要让假分支排除整个 T。

修复： 把解析结果立即放进 unknown，然后调用守卫、解析器或模式验证器。类型断言只适用于代码已经拥有但编译器无法表达的证据，并且这份证据应能由测试说明。

修复： 按需求检查精确条件，例如先写 value !== null && typeof value === "object"，或用 value !== undefined 只排除缺失值。只有业务规则确实把所有假值视为缺失时，才使用真值检查。

修复： 先确认非空对象，再读取并检查属性值。协议要求自有属性时使用 Object.hasOwn()；属性若有数字范围、字符串格式或联合值限制，也要逐项验证。

修复： 只为真正由同一运行时构造函数创建的实例使用 instanceof。数据传输对象应检查判别字段和结构，并在需要类行为时显式构造领域实例。

延伸阅读

• TypeScript Handbook：Narrowing
• TypeScript Handbook：Using type predicates
• TypeScript Handbook：Discriminated unions