JavaScript / TypeScript / 系统课时

自定义类型谓词

自定义类型谓词

内置检查无法覆盖所有业务规则时,可以把判断逻辑封装成可复用的类型保护函数。本课将使用 参数名 is 类型 声明类型谓词,让编译器在条件分支和数组过滤后保留准确类型。

学习目标

  • 编写返回类型谓词的保护函数
  • 使用类型谓词收窄 unknown
  • 理解错误谓词会带来的类型风险

定义类型谓词

类型谓词写在函数返回类型位置,例如 value is User。当函数返回 true 时,TypeScript 会在当前控制流中把参数视为目标类型。

ts
// 外部值从 unknown 开始逐项检查
type User = {
  id: number;
  name: string;
};

function isUser(value: unknown): value is User {
  if (typeof value !== "object" || value === null) {
    return false;
  }

  return (
    "id" in value &&
    typeof value.id === "number" &&
    "name" in value &&
    typeof value.name === "string"
  );
}

const values: unknown[] = [
  { id: 1, name: "Ada" },
  { id: "2", name: "Bob" },
  null,
  { id: 3, name: "Lin" }
];

const users = values.filter(isUser);

for (const user of users) {
  console.log(`${user.id}: ${user.name.toUpperCase()}`);
}

预期输出:

text
1: ADA
3: LIN

经过 filter(isUser) 后,users 的类型是 User[],因此循环中可以安全调用字符串方法。

谓词必须真实可靠

TypeScript 只相信函数签名,不会证明函数体是否真的完成了检查。若谓词错误地返回 true,后续代码可能在运行时访问不存在的字段。

检查外部数据时,应从 unknown 开始,并逐项验证对象、空值、属性存在性和属性类型。不要仅用类型断言把值强制转换为目标类型。

适用场景

自定义类型谓词常用于接口响应校验、数组过滤、事件对象区分和兼容旧数据。判断规则较复杂时,可以把基础字段检查拆成多个小函数,但最终谓词仍应保持单一职责。

验证正例与反例

本例 id 只检查 typeof 为 number,因此 NaN 和 Infinity 也能通过,这与“必须是正整数用户编号”的业务规则不同。若业务要求正整数,应增加 Number.isInteger 和大于零判断,并对边界编号做回归;不要把基础结构校验夸大为业务合法性验证。

分别测试 null、字符串、缺 name 的对象以及 id 为字符串的对象,应全部返回 false;合法用户应返回 true。过滤结果应仍可访问 User 的字段,这同时验证运行行为与编译期收窄。错误地把函数写成始终返回 true,编译器不会代替你发现逻辑漏洞。

属性检查会读取对象属性,带访问器或 Proxy 的对象可能执行代码甚至抛错;这个简单校验适合普通解析数据,不能作为恶意 JavaScript 对象的沙箱。复杂接口建议集中维护可测试的校验器,并明确未知字段、空字符串和数组元素的策略,不要在每个调用点复制稍有差异的谓词。

独立验证

使用 TypeScript 5.9.3 和 Node.js 22 检查本节。过滤后应只剩 Ada 与 Lin。额外输入 null、字符串、缺字段对象和字符串编号,谓词应返回 false;再尝试把 users 中的 name 赋给 number,确认编译器拒绝。把主示例保存为独立目录的 main.ts,执行 npx tsc main.ts --strict --target ES2022 --module commonjs --outDir dist,预期退出码为 0;再执行 node dist/main.js 核对上述结果。说明性片段按其上下文编译,练习目录保持 CommonJS 模块约定。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

自定义类型谓词

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通