JavaScript / TypeScript / 系统课时
编写断言函数
编写断言函数
校验函数常在失败时抛出异常,但普通 void 返回类型无法完整表达这种控制流效果。断言签名使用 asserts 告诉 TypeScript:函数正常返回后,某个条件成立或某个值已经具备确定类型。
学习目标
- 掌握
asserts condition与asserts value is Type两种签名 - 编写能收窄未知数据的断言函数
- 区分断言函数、类型谓词和类型断言
断言签名的两种形式
asserts condition 表示函数正常返回后,传入条件一定为真;asserts value is Type 表示函数正常返回后,参数已被验证为指定类型。
下面是片段示例,两个函数可分别放入现有 TypeScript 模块中使用:
function assert(condition: unknown, message: string): asserts condition {
if (!condition) {
throw new Error(message);
}
}
function assertIsString(value: unknown): asserts value is string {
if (typeof value !== "string") {
throw new TypeError("Expected a string");
}
}断言函数通常不返回布尔值。校验失败时必须抛出异常或以其他方式终止当前控制流;只有正常返回,后续代码才会应用断言签名中的类型信息。
校验未知输入并继续使用
下面的完整示例先把外部输入视为 unknown,再通过断言函数验证对象结构。校验成功后,调用方无需写 as User。
interface User {
id: number;
name: string;
}
function assertIsUser(value: unknown): asserts value is User {
if (typeof value !== "object" || value === null) {
throw new TypeError("User must be an object");
}
const candidate = value as Record<string, unknown>;
if (typeof candidate.id !== "number") {
throw new TypeError("User.id must be a number");
}
if (typeof candidate.name !== "string") {
throw new TypeError("User.name must be a string");
}
}
function printUser(raw: unknown): void {
assertIsUser(raw);
console.log(`${raw.id}: ${raw.name.toUpperCase()}`);
}
printUser({ id: 7, name: "Ada" });
try {
printUser({ id: "7", name: "Ada" });
} catch (error) {
console.log((error as Error).message);
}预期输出:
7: ADA
User.id must be a number调用 assertIsUser(raw) 之前,raw 是 unknown;函数正常返回后,控制流分析将其收窄为 User。第二次调用在 id 校验处抛出异常,因此不会进入后续业务逻辑。
选择方式与关键边界
类型谓词返回 boolean,由调用方处理真假分支,适合筛选、条件判断和可选流程。断言函数通常失败即抛错,成功后直接继续执行,适合参数前置校验、配置加载和不满足条件就必须终止的流程。
value as User 只是类型断言,不会生成运行时检查;assertIsUser(value) 则同时执行校验并影响后续类型。处理接口响应、配置文件或用户输入时,应优先使用真实校验,而不是仅靠 as 跳过检查。
断言签名必须与实现行为一致。若函数在校验失败时仍可能正常返回,编译器会错误地信任后续类型。优先使用带显式断言签名的函数声明,并让函数只负责验证和报错;错误信息应指出具体字段,便于定位非法输入。
本课总结
asserts condition保证条件成立,asserts value is Type保证参数具有目标类型- 断言函数失败时应终止控制流,正常返回后才会触发类型收窄
- 断言函数包含真实运行时校验,而
as只改变编译器视角
下一课预告
下一课将把多种收窄手段组合到实际代码中,选择适合分支判断、数据过滤和前置校验的类型保护方式。