satisfies 操作符

校验路由注册表

类型注解适合固定公开契约，但会让每次属性读取都只看到该契约。satisfies 仍检查精确键集合，并保留 health.method 的具体 "GET" 类型。

type Method = "GET" | "POST";
type Route = { path: string; method: Method };

const annotated: Record<string, Route> = {
  health: { path: "/health", method: "GET" },
};

const routes = {
  health: { path: "/health", method: "GET" },
  createUser: { path: "/users", method: "POST" },
} satisfies Record<"health" | "createUser", Route>;

function acceptGet(method: "GET"): string {
  return method;
}

console.log(acceptGet(routes.health.method));
console.log(Object.keys(routes).join(","));
console.log(annotated.health.method);

GET
health,createUser
GET

acceptGet(routes.health.method) 能通过检查，因为目标联合为该属性提供了上下文，而结果类型仍保留已选择的联合成员。annotated.health.method 在运行时也是 GET，但它的静态类型是完整的 Method，所以不能直接传给只接受 "GET" 的函数。

上下文类型会影响推断

类型推断（type inference） 并非只看左侧字面量本身。表达式所在位置提供的预期类型也会影响参数、数组和对象属性的推断，这称为上下文类型推断。satisfies 的右侧就是这样一个上下文来源。

普通声明 const plain = { mode: "safe" } 中，plain.mode 通常拓宽为 string，因为对象属性可被修改。目标为 { mode: "safe" | "fast" } 时，satisfies 提供一个字面量联合上下文，结果可保留 "safe"。目标若只是 { mode: string }，则没有可选择的窄联合成员，结果仍通常是 string。

数组也会利用目标上下文。目标分支包含固定长度元组时，数组字面量可以推断为元组，从而保留长度信息。目标只有 number[] 时，数组仍是普通数组；satisfies 不会自动把所有数组变成元组。

回调参数同样可以从目标取得类型。注册表目标若规定 (event: Event) => void，未显式注解的回调参数会被推断为 Event。最终对象仍拥有每个具体回调的推断签名，但这不意味着函数参数方差规则被关闭。

这个机制解释了为什么“检查但绝不改变类型”容易造成误解。准确说法是：目标参与左侧的上下文推断，检查完成后不会用整个目标类型覆盖推断结果。评审时应查看编译器实际显示的类型，而不是从语法口号猜测。

精确键集合与可赋值性

satisfies 使用普通的可赋值性规则，不会引入新的“精确对象类型”。直接对象字面量面对没有索引签名的目标时会执行多余属性检查，所以 Record<"read" | "write", Handler> 能拒绝 wirte。若先把同一个对象存进变量再检查，结构类型的一般规则可能允许额外成员。

必需键检查来自映射类型本身。Record<"read" | "write", Handler> 展开后需要两个属性，缺少其中任何一个都会失败。Record<string, Handler> 只声明“存在的任意字符串属性都必须是 Handler”，并不要求某个具体键存在。

有限键联合应来自最可靠的数据源。若命令对象是事实来源，就从 keyof typeof commands 派生名称；若协议先定义合法名称，就让 Record<CommandName, Command> 检查对象。不要同时手写对象键、联合和验证数组三份列表。

多余属性检查不是运行时白名单。即使源码对象通过精确键检查，JavaScript 仍可在运行时添加属性，外部 JSON 也可以包含额外字段。需要拒绝未知字段时，运行时解析器必须明确执行这一策略。

可选属性不会被补上

目标中的可选属性表示兼容值可以没有该属性。左侧省略它时，satisfies 会接受对象，但结果类型仍只包含实际声明的属性。这样一来，"cache" in config 与 config.cache 的静态可用性不会被目标虚构出来。

若左侧写出可选属性，它的值必须满足当前编译器选项下的可赋值性规则。启用 exactOptionalPropertyTypes 时，option?: string 表示属性存在时必须是 string，不自动包含 undefined。关闭该选项时，显式 undefined 的兼容范围会更宽。

库和应用应在自己的 tsconfig 下验证示例与声明。satisfies 不会隔离 strictFunctionTypes、noUncheckedIndexedAccess 或 exactOptionalPropertyTypes 等选项的影响。复制生成代码时，必须在目标项目的真实配置中运行 tsc。

需要稍后添加可选属性时，注解通常更符合意图。例如，先声明 const config: Config = defaults，再更新 config.cache，公开契约清楚且允许目标定义的变化。用 satisfies 后再通过断言补属性，只是在抵消原本保留精确结果类型的选择。

as const satisfies 有先后顺序

表达式 value as const satisfies Target 先对字面量应用 const 断言，再检查只读、窄化后的结果能否赋给 Target。因此，对象属性会变为只读，数组会成为只读元组，原始值会尽量保持字面量类型。目标必须接受这种只读性。

顺序适合静态常量表，但不适合所有配置。若下游函数拥有数组并会排序或追加元素，向它传递只读元组应当失败；把目标中的数组改成 readonly 只是准确描述不修改的使用方，不能用来掩盖真实的可变需求。

两个操作符都会从生成的 JavaScript 中消失。运行时值仍是普通对象，引用身份与不带这些类型语法时相同。编译器检查通过只证明受检源码表达式与静态目标兼容，不证明对象之后永远不变。

对外发布的常量还要考虑声明输出。保留极窄的推断类型会让生成的 .d.ts 暴露大量具体属性；这可能是有意设计，也可能把实现细节变成公共 API。库边界需要稳定契约时，应给导出写显式注解，并在内部使用 satisfies 检查更具体的实现表。

根据契约与可变性选择语法

类型注解、satisfies、as const 和类型断言并不是四种风格不同的同义写法。 它们分别控制公开契约、兼容性检查、只读字面量推断和检查器信任，因此选择标准应是代码下一步要做什么。

类型注解固定公开类型

变量需要在多个合法状态之间赋值时，注解通常最直接。 let mode: "safe" | "fast" = "safe" 明确表示后续可以写入另一个联合成员，而不是把初始化值当成永久状态。

导出的函数参数、返回值和对象也常需要注解，因为维护者希望实现变化不能悄悄改变使用方看到的类型。 注解造成的拓宽在这里不是信息损失，而是稳定 API 的有意选择。

satisfies 校验当前表达式

静态表格通常先声明一次，之后从中派生名称、判别值或回调类型。 此时保留当前表达式的成员信息有实际价值，而目标类型负责阻止缺失条目和不兼容值。

目标不应比真实契约更宽。 若调用方只支持两个命令，却用 Record<string, Command> 检查，实现得到的是虚假的开放能力，而不是更灵活的设计。

as const 请求只读精度

as const 适合协议常量、测试向量和不会修改的查找表。 它会递归地把字面量表达式中的属性标记为只读，但不会深度冻结值引用的现有对象。

若只需要某一个判别字段保持窄类型，可以给该字段更具体的上下文，而不必冻结整个对象的静态形状。 这种局部设计通常更容易与需要可变集合的代码协作。

类型断言记录外部证明

类型断言只应出现在开发者掌握了编译器无法表达的证据时。 典型位置是经过运行时检查后的窄小适配器，而不是未验证数据刚进入系统的位置。

断言附近应能看到证据来源、前置条件和失败策略。 如果只能用“数据应该是这样”解释断言，就还没有建立足够的证明。

用类型测试固定静态保证

satisfies 的价值存在于编译器行为中，只运行 JavaScript 无法验证它。 除了执行示例，还要运行 tsc --noEmit，并把关键的接受与拒绝情况写成类型测试。

正向测试证明可用能力

正向测试应使用检查后保留的具体能力，例如把 routes.health.method 传给只接受 "GET" 的函数。 这比只声明对象更有信息量，因为目标类型意外变宽时，使用点会立即失败。

也可以用 keyof typeof registry 构造名称联合，再让函数只接受该联合。 添加或删除注册项后，类型测试会展示派生 API 是否按预期同步变化。

负向测试证明错误仍被拒绝

使用 @ts-expect-error 标记刻意错误的声明，可以让“应该报错”成为可执行断言。 若未来的重构让该行不再产生诊断，TypeScript 会报告这个指令未被使用。

有限注册表至少应测试一个缺失键、一个多余键和一个错误值。 可变配置还应测试合法重新赋值，防止从注解改成 satisfies 后无意留下过窄类型。

编译器配置属于测试输入

类型测试必须使用项目支持的 TypeScript 版本和 tsconfig。 编辑器中的临时推断不能替代 CI，因为编辑器可能选择另一个工作区版本或不同配置。

验证生成代码时，至少记录以下条件：

• TypeScript 的确切版本，而不是只写“最新版”。
• 是否启用 strict 与 exactOptionalPropertyTypes。
• 类型测试使用的入口文件和 tsconfig。
• 预期成功与预期失败的命令退出状态。

这些记录能区分语言行为变化、配置差异与代码回归。 只保存运行时快照会漏掉 satisfies 最重要的静态保证。

分层处理注册表与外部数据

成熟系统通常同时有静态注册表和动态输入，两者不应共用一种“验证”方式。 源码注册表由 TypeScript 检查，外部名称与载荷由运行时解析器检查，领域逻辑只接收已验证结果。

静态层拥有实现

处理器对象可以用有限键联合与 satisfies 校验。 这样既保证每个协议命令都有实现，也保留每个处理器的具体参数和返回类型。

从该对象派生 keyof 时，得到的是实现真正拥有的名称。 不要用断言把 Object.keys() 直接升级成任意联合，除非对象的运行时构造路径也保证没有额外键。

边界层拥有解析

解析器接收 unknown，检查输入是否为对象，再验证命令名称和对应载荷。 它可以返回判别联合，让后续控制流根据名称收窄整个请求。

运行时成员检查应来自与静态联合同步的数据源，例如一个 as const 名称数组或模式定义。 只有返回类型而没有实际比较的类型谓词，仍然只是另一种未经证明的断言。

领域层依赖已建立的不变量

领域分派不必重复检查每个基础字段，但应保留不可达分支的运行时失败。 即使静态联合看似穷尽，旧客户端、JavaScript 调用方或错误断言仍可能送入未知名称。

这种分层给 satisfies 一个清晰位置：它检查源码拥有的声明，不承担输入清洗、安全验证或数据迁移。 生成代码把这三层压成一次断言时，应先恢复边界，再讨论类型精度。