TypeScript keyof 怎样约束对象键并安全读取属性

当配置对象从表单、路由或接口数据中被动态读取时，最容易留下的缺口是把键写成普通 string。这样一来，拼写错误、已删除字段和不匹配的返回值都可能绕过类型提示。更稳妥的做法是让键参数受 keyof 约束，再用索引访问类型 T[K] 绑定返回值。

官方地址：https://www.typescriptlang.org/

本文只讨论对象键约束与属性读取，不把所有动态字典都改成固定接口。你会得到一个可复用的泛型读取函数，并知道它在哪些场景下应该收紧、放宽或改用运行时校验。

先保护对象键：keyof 不是任意字符串

假设页面配置有三个字段：

interface PageConfig {
  title: string;
  pageSize: number;
  showToolbar: boolean;
}

type ConfigKey = keyof PageConfig;
// ConfigKey 等价于 "title" | "pageSize" | "showToolbar"
const key: ConfigKey = "pageSize";
// 错误示例："pagesize" 不在对象真实键集合中
// const wrongKey: ConfigKey = "pagesize";

keyof PageConfig 把对象的键转换成联合类型，所以调用方不能随便传入一个字符串。这里保护的资产不是字段值本身，而是“字段名与对象结构之间的对应关系”。如果类型上存在字符串索引签名，keyof 的结果还会扩大到 string | number，这正是需要单独评估的边界。

再看攻击路径：string 和 any 怎样绕过约束

如果读取函数把键写成 string，对象结构和调用参数就脱钩了。为了让示例保持在类型层面，先看下面这个不推荐的写法：

function readLoose(config: PageConfig, key: string) {
  // 这里用 any 会丢掉字段值的精确类型，不能作为安全兜底
  return (config as any)[key];
}

const value = readLoose({
  title: "首页",
  pageSize: 20,
  showToolbar: true,
}, "pageSzie");
// 拼写错误只能在运行时暴露，value 也失去明确类型

风险可以分三档：固定键最安全；受 keyof 约束的动态键可控；普通字符串加类型断言最弱。最后一种写法看起来灵活，却把错误推迟到了运行时。

用泛型绑定键和值：K extends keyof T

通用读取函数需要两个类型参数：T 表示对象，K 表示该对象的键。返回值写成 T[K] 后，传入不同键时，结果会跟着变化：

function readProperty(object: T, key: K): T[K] {
  // K 被限制为 T 的真实键，返回值由同一个键索引得到
  return object[key];
}

const config: PageConfig = {
  title: "首页",
  pageSize: 20,
  showToolbar: true,
};

const title = readProperty(config, "title");
// title 的类型是 string
const pageSize = readProperty(config, "pageSize");
// pageSize 的类型是 number
// readProperty(config, "pageSzie"); // 编译期拒绝拼写错误

这段签名的关键不是“把错误字符串列出来”，而是让参数和返回值共享一个键变量。调用方传入 "title" 时，返回值就是 PageConfig["title"]，不会退化成所有字段值的宽联合。

风险分级：可选属性、运行时键与索引签名

当对象包含可选字段时，返回值应诚实地包含 undefined。不要为了消除提示直接断言成非空：

interface UserPreferences {
  theme: "light" | "dark";
  locale?: string;
}

function readPreference(
  preferences: UserPreferences,
  key: K,
): UserPreferences[K] {
  // 可选字段的 undefined 由类型系统保留下来
  return preferences[key];
}

const locale = readPreference({ theme: "light" }, "locale");
// locale 的类型是 string | undefined，调用前应先判断存在性

如果键来自接口或用户输入，keyof 只能约束编译期变量，不能证明运行时字符串真的属于对象。此时先做运行时集合判断，再把结果收窄；如果对象本来就是任意键字典，则应明确写出索引签名，并接受更宽的值类型，而不是把字典伪装成固定对象。

留下审计记录：用负例确认边界没有被绕开

在代码审查或 CI 中，重点检查三件事：读取函数是否仍使用普通 string；是否出现无必要的 any 和类型断言；可选字段是否保留了 undefined。可以把最小复查命令写成：

# 对项目做一次完整类型检查，不输出 JavaScript 文件
npx tsc --noEmit

# 只在示例验证时保留一个预期失败调用
# readProperty(config, "pageSzie")

这里的成功标准不是“所有动态访问都消失”，而是每一种访问都能说明自己的边界：固定结构使用 keyof，泛型工具使用 T[K]，可选字段处理 undefined，外部字符串先做运行时校验。

常见问题

keyof 为什么有时得到 string | number？

通常是对象声明了字符串索引签名。JavaScript 的数字属性访问最终也会参与字符串键转换，因此类型结果会比固定对象的字面量联合更宽。

keyof 能替代运行时参数校验吗？

不能。它只在编译期约束已知类型；来自请求、表单或配置文件的字符串仍应先做运行时校验，再进入泛型读取函数。

记住一个可复用的判断：对象结构固定时，用 K extends keyof T 锁住键；返回值需要跟随键变化时，用 T[K] 表达对应关系；一旦输入越过编译边界，就补上运行时检查，而不是用 as any 把问题藏起来。