JavaScript / TypeScript / 系统课时

校验对象结构

校验对象结构

直接给对象添加类型注解,可能会丢失属性的精确推断;使用类型断言又可能绕过必要检查。satisfies 能验证对象是否满足目标类型,同时保留对象本身推断出的具体键名和值类型。

学习目标

  • 使用 satisfies 检查对象结构和属性值
  • 理解它与类型注解、类型断言的差异
  • 在配置映射中保留精确的键名推断

satisfies 的基本规则

satisfies 写在表达式后面,右侧提供需要满足的目标类型。编译器会检查缺失属性、多余属性和不兼容值,但变量最终仍采用表达式自身的推断类型。

ts
const value = expression satisfies TargetType;

它不会转换运行时数据,也不会把变量强制改成 TargetType。生成的 JavaScript 中不包含 satisfies,所有作用都发生在编译阶段。

校验配置并保留精确类型

下面定义一组支付通道配置。目标结构要求每个通道都包含 enabled 和 timeout,同时只允许规定的通道名称。

ts
type ChannelName = 'card' | 'wechat' | 'alipay';

type ChannelConfig = {
  enabled: boolean;
  timeout: number;
};

const channels = {
  card: { enabled: true, timeout: 5000 },
  wechat: { enabled: true, timeout: 3000 },
  alipay: { enabled: false, timeout: 4000 }
} satisfies Record<ChannelName, ChannelConfig>;

function printTimeout(name: keyof typeof channels): void {
  const config = channels[name];
  console.log(`${name}: ${config.timeout}ms`);
}

printTimeout('wechat');
console.log(channels.alipay.enabled);

// @ts-expect-error: unionpay 不是已配置的精确键名
printTimeout('unionpay');

预期输出:

text
wechat: 3000ms
false

channels 通过了 Record<ChannelName, ChannelConfig> 校验,同时 keyof typeof channels 仍是 'card' | 'wechat' | 'alipay'。编辑器因此能够提供精确的键名补全,而不是只把变量视为普通字符串索引对象。

与类型注解的区别

类型注解会直接把变量声明为目标类型。这样便于统一接口,但读取属性时通常只能获得目标类型中定义的宽泛结果。

ts
const annotated: Record<string, string | number> = {
  mode: 'production',
  port: 8080
};

const checked = {
  mode: 'production',
  port: 8080
} satisfies Record<string, string | number>;

// annotated.mode 的类型是 string | number
// checked.mode 的类型是 string,checked.port 的类型是 number
console.log(checked.mode.toUpperCase(), checked.port.toFixed(0));

预期输出:

text
PRODUCTION 8080

当后续代码需要依赖每个属性的具体类型时,satisfies 通常比直接添加宽泛注解更合适。

与类型断言的区别

as TargetType 表示开发者要求编译器把某个值当作目标类型处理。断言主要用于补充编译器无法获知的信息,不适合代替结构校验,因为不恰当的断言可能掩盖真实错误。

satisfies 不会强制改变表达式类型。对象缺少必填属性、属性类型不兼容或出现非法键名时,编译器会直接报告问题,因此更适合编写路由表、主题配置、权限映射和功能开关。

使用边界

satisfies 只检查类型,不会补充默认值,也不会验证接口返回、用户输入或 JSON 文件中的运行时数据。外部数据仍需要校验库或手动检查。

它也不会自动让对象变成只读。需要同时保留字面量值并禁止修改时,可以组合使用 as const satisfies TargetType,先通过 const 断言固化表达式,再检查其是否满足目标结构。

本课总结

  • satisfies 会检查表达式是否满足目标类型,但保留表达式自身的精确推断
  • 与宽泛类型注解相比,它更有利于保留具体键名和属性类型
  • 它属于编译期检查,不能替代运行时数据校验

下一课预告

下一课将继续组合字面量、索引访问类型和映射类型,把常量数据转换为可复用的类型工具。

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

目录与阅读设置

阅读设置

17

记录一个想法

校验对象结构

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

登录哪都通