JavaScript / TypeScript / 系统课时

编写断言函数

编写断言函数

校验函数常在失败时抛出异常,但普通 void 返回类型无法完整表达这种控制流效果。断言签名使用 asserts 告诉 TypeScript:函数正常返回后,某个条件成立或某个值已经具备确定类型。

学习目标

  • 掌握 asserts condition 与 asserts value is Type 两种签名
  • 编写能收窄未知数据的断言函数
  • 区分断言函数、类型谓词和类型断言

断言签名的两种形式

asserts condition 表示函数正常返回后,传入条件一定为真;asserts value is Type 表示函数正常返回后,参数已被验证为指定类型。

下面是片段示例,两个函数可分别放入现有 TypeScript 模块中使用:

ts
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。

ts
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);
}

预期输出:

text
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 只改变编译器视角

下一课预告

下一课将把多种收窄手段组合到实际代码中,选择适合分支判断、数据过滤和前置校验的类型保护方式。

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

目录与阅读设置

阅读设置

17

记录一个想法

编写断言函数

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

登录哪都通