引言：动态属性匹配的挑战
在TypeScript开发中，我们经常会遇到需要定义一种数据结构，其中某个数组（例如 props）列出了所有可用的字符串属性名称，而另一个数组（例如 order）则以某种特定格式引用这些属性名称。一个常见的挑战是，如何确保 order 数组中引用的所有字符串都确实是 props 数组中定义的有效属性名称。如果没有严格的类型检查，order 中可能出现拼写错误或不存在的属性名，这将在运行时导致难以调试的错误。
例如，考虑一个表示网格布局的对象：它有一个 props 数组，包含所有可在网格中显示的属性名；还有一个 order 数组，定义了这些属性在网格中的排列顺序，可以是单个属性占一行，也可以是两个属性并排显示。我们希望TypeScript能够动态地检查 order 数组中的字符串是否与 props 数组中声明的属性名一致。
解决方案：利用TypeScript泛型进行类型约束
为了实现这种动态匹配和类型安全，我们可以利用TypeScript强大的泛型类型参数。泛型允许我们定义可重用的组件，这些组件可以处理多种类型的数据，同时保持类型检查的严格性。
核心思想是引入一个泛型类型参数，它代表了所有允许的属性名称的集合。这个泛型参数随后将被用来约束 props 数组的元素类型以及 order 数组中引用的字符串类型。
/**
* 定义一个网格顺序类型 OrderGrid。
* 它接受一个泛型参数 S，该参数必须是字符串字面量联合类型。
* OrderGrid 可以是包含 S 类型元素的数组，或包含 S 类型元组的数组。
*/
type OrderGrid<S extends string> = Array<S | [S, S]>;
/**
* 定义一个有序属性对象类型 OrderedProperties。
* P: 代表所有有效的属性名称字符串字面量联合类型。
* O: 代表 order 数组中允许使用的属性名称子集，默认与 P 相同。
* O 必须是 P 的子类型 (O extends P)，确保 order 中的属性名是 props 定义的有效属性。
*/
type OrderedProperties<P extends string, O extends P = P> = {
props: P[]; // props 数组的元素必须是 P 类型，即所有有效属性的集合
order: OrderGrid<O>; // order 数组的元素必须是 O 类型，即 P 的子集
};在上述类型定义中：
- OrderGrid
定义了 order 字段的结构。它确保了网格中的每个元素（无论是单个字符串还是元组中的字符串）都必须是 S 类型，即我们预期的属性名称集合中的一员。 - OrderedProperties
是核心类型。
- P 是一个泛型参数，它将捕获 props 数组中所有唯一的字符串字面量，形成一个字符串字面量联合类型。
- props: P[] 强制 props 数组中的所有字符串都必须是 P 类型。
- order: OrderGrid
是关键所在。O extends P 的约束确保了 order 数组中使用的任何属性名都必须是 P 类型中定义的有效属性名。O = P 的默认值意味着如果 O 没有被显式指定，那么 order 数组中的属性名必须完全匹配 P 中定义的属性名。
应用场景一：显式类型注解
当我们在代码中声明一个 OrderedProperties 类型的变量时，可以直接通过显式地提供一个字符串字面量联合类型作为泛型参数 P，来强制类型检查。
使用 Scrapfly SDK（scrapfly-sdk）在 TypeScript 或 JavaScript 中进行网页抓取，用于用户请求抓取 URL、绕过反爬虫防护、渲染页面等场景。
// 示例 1: 有效的属性定义和顺序
// P 被明确指定为 "firstName" | "lastName" | "nickName" | "title"
const a: OrderedProperties<"firstName" | "lastName" | "nickName" | "title"> = {
props: ["title", "firstName", "lastName", "nickName"],
order: [
"title",
["firstName", "lastName"],
"nickName",
],
}; // 类型检查通过，一切正常
// 示例 2: 包含无效属性的定义，导致类型错误
// P 被明确指定为 "firstName" | "lastName" | "nickName"，不包含 "title"
const a2: OrderedProperties<"firstName" | "lastName" | "nickName"> = {
props: ["title", "firstName", "lastName", "nickName"], /* 错误:
~~~~~~~
类型 '"title"' 不能分配给类型 '"firstName" | "lastName" | "nickName"'。(2322)
因为 'props' 数组中包含了 'title'，而它不在泛型参数 P 定义的允许范围内。*/
order: [
"title", /* 错误:
~~~~~~~
类型 '"title"' 不能分配给类型 '"firstName" | "lastName" | "nickName" | ["firstName" | "lastName" | "nickName", "firstName" | "lastName" | "nickName"]'。(2322)
因为 'order' 数组中包含了 'title'，它也不在泛型参数 O (默认为 P) 定义的允许范围内。*/
["firstName", "lastName"],
"nickName",
],
};在 a2 的例子中，由于我们显式地将泛型参数 P 限制为不包含 "title" 的联合类型，因此在 props 数组或 order 数组中任何对 "title" 的引用都会立即触发类型错误。这种方法在编译阶段就捕获了潜在的逻辑错误，但缺点是每次声明变量时都需要手动列举所有允许的字符串字面量，这在属性列表较长时会显得繁琐且易出错。
应用场景二：函数参数的类型推断
在实际的应用程序开发中，我们通常会将这种结构化的对象作为参数传递给函数进行处理。在这种情况下，TypeScript 的类型推断机制可以极大地简化开发流程，而无需在变量声明处显式地指定冗长的泛型参数。当一个对象作为泛型函数的参数时，编译器会根据传入对象的实际结构自动推断出 P 和 O 的具体类型。
/**
* 声明一个用于处理 OrderedProperties 对象的函数。
* TypeScript 会根据传入的参数自动推断 P 和 O 的具体类型。
*/
declare function handleOrderedProps<P extends string, O extends P = P>(
props: OrderedProperties<P, O>,
): void;
// 示例 1: 有效的属性定义和顺序，类型推断成功
// TypeScript 会自动从 props 数组推断出 P 为 "title" | "firstName" | "lastName" | "nickName"
handleOrderedProps({
props: ["title", "firstName", "lastName", "nickName"],
order: [
"title",
["firstName", "lastName"],
"nickName",
],
}); // 正常，类型检查通过
// 示例 2: order 数组中缺少 props 定义的属性 (这种情况是允许的)
// P 仍被推断为所有 props 中的字符串，order 中只使用了部分，符合 O extends P 的约束
handleOrderedProps({
props: ["title", "firstName", "lastName", "nickName"],
order: [
"title",
["firstName", "lastName"],
],
}); // 正常，"nickName" 未被使用是允许的，因为它仍在 P 的范围内
// 示例 3: order 数组中包含 props 未定义的属性，导致类型错误
// P 被推断为 "title" | "firstName" | "lastName"
handleOrderedProps({
props: ["title", "firstName", "lastName"],
order: [
"title",
["firstName", "lastName"],
"nickName", /* 错误:
~~~~~~~~~~
类型 '"nickName"' 不能分配给类型 '"firstName" | "lastName" | "title" | ["firstName" | "lastName" | "title", "firstName" | "lastName" | "title"]'。(2322)
因为 'nickName' 不在从 'props' 数组推断出的 P (即 "title" | "firstName" | "lastName") 范围内。*/
],
});通过将对象传递给 handleOrderedProps 这样的泛型函数，TypeScript 能够智能地从 props 数组中提取所有字符串字面量，并将其作为 P 的推断类型。然后，它会使用这个推断出的 P 来检查 order 数组中的每个元素是否有效。这种方法极大地提高了代码的可用性和开发效率，因为它将类型检查的复杂性隐藏在函数签名中，让开发者能够以更自然的方式编写代码。
关于数据冗余的思考
在某些设计场景中，props 数组和 order 数组之间可能存在一定的冗余。如果 props 数组仅仅是 order 数组中所有属性名称的扁平化集合，那么 props 数组本身可能不是必需的，可以从 order 派生出来。
/**
* 从 OrderGrid 中提取所有属性名称并扁平化为字符串数组。
* 这可以作为一种工具函数，用于从 order 派生出 props 列表。
*/
function getPropsFromOrder<S extends string>(order: OrderGrid<S>): S[] {
// 使用 flat() 方法将嵌套数组扁平化，并进行类型断言以保持类型 S[]
return order.flat() as S[];
}
// 示例使用
const myOrder: OrderGrid<"productName" | "price" | "quantity"> = [
"productName",
["price", "quantity"]
];
const derivedProps = getPropsFromOrder(myOrder); // derivedProps 的类型是 ("productName" | "price" | "quantity")[]
console.log(derivedProps); // 输出: ["productName", "price", "quantity"]这种方法可以减少数据重复，并确保 props 始终与 order 中实际使用的属性保持一致。然而，如果 props 数组有其独立的语义（例如，它表示所有 可能 存在的属性，而 order 仅表示 当前 使用的子集），或者 props 数组包含了一些虽然定义但并未在 order 中使用的属性，那么保留 props 数组仍然是合理的。具体的数据模型设计应根据业务需求和数据语义来决定。
总结
通过巧妙地利用 TypeScript 的泛型类型参数，我们能够有效地在对象内部实现属性名称的动态匹配和严格的类型约束。这种方法确保了 order 数组中引用的所有属性名都必须是 props 数组中定义的有效属性，从而在编译阶段就捕获了潜在的引用错误。无论是通过显式类型注解来强制类型，还是借助函数参数的类型推断来简化使用，泛型都为构建健壮、可维护和类型安全的 TypeScript 应用程序提供了强大的工具。合理运用泛型是编写高质量、类型安全 TypeScript 代码的关键实践之一。
