JavaScript / TypeScript / 系统课时
校验外部数据
校验外部数据
TypeScript 只能在编译阶段约束你写出的代码,接口响应、表单值、配置文件和消息队列数据进入运行时后并不会自动变安全。本篇用 unknown 接住边界数据,再做结构校验和转换,保证业务代码拿到的是真正可信的类型。
学习目标
- 解释为什么类型注解不能替代运行时校验
- 用
unknown、类型收窄和解析函数校验外部对象 - 把“校验通过”和“转换为领域类型”放在系统边界完成
类型注解不会检查运行时数据
类型声明会在编译后被擦除,因此把一个值写成 User 并不会检查它是否真的包含正确字段。尤其不要用 as User 把接口结果直接断言成目标类型:断言只是在告诉编译器“相信我”,不会在运行时验证任何内容。
在边界执行校验与安全转换
下面的完整示例同时检查对象形状、字段类型和业务约束,并在通过校验后去除姓名两侧空格。失败时立即返回明确错误,而不是让错误延迟到更深的业务逻辑中。
type User = {
id: number;
name: string;
};
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null;
}
function parseUser(value: unknown): User {
if (!isRecord(value)) {
throw new Error("用户数据必须是对象");
}
const id = value.id;
const name = value.name;
if (typeof id !== "number" || !Number.isInteger(id)) {
throw new Error("id 必须是整数");
}
if (typeof name !== "string" || name.trim() === "") {
throw new Error("name 必须是非空字符串");
}
return { id, name: name.trim() };
}
const samples = [
'{"id":42,"name":" Ada "}',
'{"id":"42","name":"Ada"}'
];
for (const text of samples) {
try {
const raw: unknown = JSON.parse(text);
console.log(parseUser(raw));
} catch (error) {
console.log((error as Error).message);
}
}预期输出:
{ id: 42, name: 'Ada' }
id 必须是整数这段代码把“接收不可信数据”和“生成可信 User”分成两个阶段。内部函数一旦接收到 User,就不必重复检查 id 和 name,校验责任集中在边界,更容易维护。

校验不仅是判断 true 或 false
实际项目中,边界处理通常同时包含三件事:确认结构、约束值域、转换表示形式。例如日期字符串需要转成 Date,数字字符串可能需要先解析,缺省字段可能需要补默认值。只有在转换不会掩盖错误语义时才自动修正;像 "42" 是否能当作数字 42,应由接口契约决定,而不是随意宽松处理。
如果校验规则很多,可以使用专门的运行时 schema 库集中声明规则,但原则不变:外部值先进入运行时校验,成功后再获得静态类型。不要把“编译器没报错”误认为“运行时数据一定正确”。
把错误挡在系统边界
边界校验越靠近数据入口,错误上下文越完整。校验失败时应返回能定位字段的问题,例如“id 必须是整数”,而不是让一个错误值继续传播,最后在模板渲染或业务计算中以空值、NaN 或属性访问异常的形式爆炸。
当内部代码只处理已经验证过的领域对象时,TypeScript 的静态检查才能真正发挥价值:编译期负责约束程序之间的关系,运行时校验负责证明外部数据满足这些关系。