JavaScript / TypeScript / 系统课时
自定义类型谓词
自定义类型谓词
内置检查无法覆盖所有业务规则时,可以把判断逻辑封装成可复用的类型保护函数。本课将使用 参数名 is 类型 声明类型谓词,让编译器在条件分支和数组过滤后保留准确类型。
学习目标
- 编写返回类型谓词的保护函数
- 使用类型谓词收窄
unknown - 理解错误谓词会带来的类型风险
定义类型谓词
类型谓词写在函数返回类型位置,例如 value is User。当函数返回 true 时,TypeScript 会在当前控制流中把参数视为目标类型。
// 外部值从 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()}`);
}预期输出:
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 模块约定。