TypeScript 类型守卫：检查对象的类型

类型守卫是 TypeScript 能看懂的运行时检查，因此它会在通过检查的分支里收窄类型。typeof、instanceof 和 in 是内置的守卫；其他情况就写一个返回类型为类型谓词 value is Type 的函数。

interface User {
  name: string;
  age: number;
}

function isUser(value: unknown): value is User {
  return (
    typeof value === "object" && value !== null &&
    "name" in value && typeof value.name === "string" &&
    "age" in value && typeof value.age === "number"
  );
}

const inputs: unknown[] = [{ name: "Ada", age: 36 }, { name: "Bob" }, "Ada", null];

for (const input of inputs) {
  if (isUser(input)) {
    console.log(`${input.name} is ${input.age}`); // input: User
  } else {
    console.log("not a user:", input);
  }
}

isUser 在运行时返回的只是普通的布尔值。返回类型 value is User 告诉编译器结果为 true 时能证明什么，之后每个 if (isUser(x)) 都会把 x 收窄为 User。

内置类型守卫

下面这些检查不需要任何辅助函数就能收窄类型：

它们都作为普通的 JavaScript 运行。TypeScript 额外做的是收窄：它读懂检查，并调整每个分支里的类型。全部收窄形式见类型收窄页面。自定义守卫适用于一个表达式写不下、或者需要复用的检查。

编写类型谓词

类型谓词的形式是 parameterName is Type，用来代替返回类型 boolean。收窄在两个方向上都生效：true 收窄为 Type，false 则从联合类型中去掉 Type。

type Cat = { kind: "cat"; meow: () => string };
type Dog = { kind: "dog"; bark: () => string };
type Pet = Cat | Dog;

function isCat(pet: Pet): pet is Cat {
  return pet.kind === "cat";
}

function speak(pet: Pet): string {
  if (isCat(pet)) {
    return pet.meow(); // pet: Cat
  }
  return pet.bark();   // pet: Dog (Cat was ruled out)
}

const pets: Pet[] = [
  { kind: "cat", meow: () => "meow" },
  { kind: "dog", bark: () => "woof" },
];

console.log(pets.map(speak));             // [ 'meow', 'woof' ]
console.log(pets.filter(isCat).length);   // 1 (and the result is typed Cat[])

把守卫传给 filter，得到的数组类型就是正确的。从 TypeScript 5.5 开始，编译器还会从简单的箭头函数推断出谓词，所以 pets.filter((p) => p.kind === "cat") 不用具名守卫也会返回 Cat[]。

谓词中的类型必须能赋值给参数的类型：function f(x: string): x is number 会报错 TS2677，A type predicate's type must be assignable to its parameter's type.

编译器信任你的守卫

TypeScript 会检查守卫是否返回布尔值，但不会检查这个布尔值对不对。一个对错误的值返回 true 的守卫会让类型“说谎”，程序在运行时出错，而编译时没有任何错误。

interface Product {
  title: string;
  price: number;
}

// Wrong: only checks title, never price
function isProduct(value: unknown): value is Product {
  return typeof value === "object" && value !== null && "title" in value;
}

const data: unknown = { title: "Lamp" };

if (isProduct(data)) {
  console.log(data.title); // Lamp
  try {
    console.log(data.price.toFixed(2)); // compiles, but throws at run time
  } catch (e) {
    console.log(e instanceof Error ? e.message : e);
    // Cannot read properties of undefined (reading 'toFixed')
  }
}

data.price.toFixed(2) 在运行时抛出 TypeError: Cannot read properties of undefined (reading 'toFixed')。编译器之所以把 data.price 当作 number，是因为守卫这么说了。后续代码依赖的每个属性都要检查，并让守卫保持短小、经过测试，并放在它所描述的类型旁边。

检查对象是否属于某个类型

大多数自定义守卫都是为了回答这个问题：数据以 unknown 的形式到来（来自 JSON.parse、fetch、localStorage 或一条消息），你需要知道它是否符合你的接口。做法如下：

1. typeof value === "object" && value !== null（是对象，而不是 null）。
2. 对每个必需属性用 "prop" in value。在 unknown 上，in 会把该属性以 unknown 类型加到类型里。
3. 对每个属性的类型用 typeof value.prop === "..."（或嵌套的守卫）。
4. 数组用 Array.isArray(value.items) && value.items.every(isItem)。

interface Order {
  id: string;
  lines: { sku: string; qty: number }[];
}

function isLine(v: unknown): v is Order["lines"][number] {
  return typeof v === "object" && v !== null &&
    "sku" in v && typeof v.sku === "string" &&
    "qty" in v && typeof v.qty === "number" && Number.isInteger(v.qty);
}

function isOrder(v: unknown): v is Order {
  return typeof v === "object" && v !== null &&
    "id" in v && typeof v.id === "string" &&
    "lines" in v && Array.isArray(v.lines) && v.lines.every(isLine);
}

const good: unknown = JSON.parse('{"id":"A1","lines":[{"sku":"pen","qty":2}]}');
const bad: unknown = JSON.parse('{"id":"A2","lines":[{"sku":"pen","qty":"2"}]}');

console.log(isOrder(good), isOrder(bad)); // true false
if (isOrder(good)) console.log(good.lines[0].qty * 3); // 6

结构较大或嵌套较深时，手写这些检查很繁琐。Zod、Valibot 这类 schema 库让你只描述一次结构，就能同时得到运行时检查和 TypeScript 类型。

断言函数：asserts value is Type

断言函数在检查失败时抛出异常，否则正常返回。它的返回类型是 asserts value is Type（或 asserts condition），调用之后的所有代码都会被收窄，不需要 if。

function assertIsString(value: unknown, name: string): asserts value is string {
  if (typeof value !== "string") {
    throw new TypeError(`${name} must be a string, got ${typeof value}`);
  }
}

function assert(condition: unknown, message: string): asserts condition {
  if (!condition) throw new Error(message);
}

function greet(input: unknown, count: number | null): string {
  assertIsString(input, "input");
  assert(count !== null, "count is required");
  // input: string, count: number
  return input.toUpperCase().repeat(count);
}

console.log(greet("hi", 2)); // HIHI

try {
  greet(42, 1);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // input must be a string, got number
}

有一条规则经常让人栽跟头：断言函数必须通过带有显式类型的名字来调用。没有注解的 const 箭头函数，比如 const check = (v: unknown): asserts v is string => {...}，会在调用处报错 TS2775，Assertions require every name in the call target to be declared with an explicit type annotation. 请改用 function 声明，或者给常量加上函数类型注解。

守卫、断言与类型断言对比

类型断言（as）只改变类型，不做任何检查。在数据来自外部的边界上，守卫或断言函数才是同一想法的安全版本。

类中基于 this 的守卫

方法可以用 this is Type 收窄调用它的对象，这在类的继承层次中很方便：

class FileNode {
  constructor(public name: string) {}
  isDirectory(): this is DirectoryNode {
    return this instanceof DirectoryNode;
  }
}

class DirectoryNode extends FileNode {
  children: FileNode[] = [];
}

function count(node: FileNode): number {
  return node.isDirectory() ? node.children.length : 0; // node: DirectoryNode in the true branch
}