本教程探讨在 jsdoc 中定义具有固定必选属性和任意可选额外属性的对象类型。我们将介绍两种主要策略：使用通配符属性实现高度灵活性，以及结合交叉类型与字典类型实现更强的类型约束，以确保类型定义的准确性和避免因额外属性导致的类型检查错误。
在 JavaScript 项目中，JSDoc 是一种强大的工具，用于为代码添加类型注解，从而提升开发效率和代码可维护性。然而，在某些场景下，我们需要定义一种对象类型，它既包含一组固定的、明确定义的属性，又允许开发者自由添加任意数量的额外属性。例如，一个 User 对象可能需要强制包含 name 和 age 属性，同时又允许添加 from、to 等动态属性。本文将详细介绍如何在 JSDoc 中实现这种灵活的对象类型定义。
1. 场景需求分析
假设我们有一个 User 类型，要求：
- 必须包含 name (字符串) 和 age (数字) 属性。
- 可以包含任意数量的其他属性，这些属性的键和值类型可以是任意的，或者有特定的约束。
以下是一个初始的 JSDoc 定义，它会在添加额外属性时引发类型错误：
/**
* @typedef {object} User
* @property {string} name - 用户名
* @property {number} age - 用户年龄
*/
/**
* @type {User}
*/
const tom = {
name: 'cx',
age: 25,
from: 'sh', // 预期会报错
to: 'bj', // 预期会报错
};为了解决这个问题，我们可以采用以下两种 JSDoc 定义策略。
2. 方法一：使用通配符属性 (*) 允许任意额外属性
最直接且最灵活的方法是使用 JSDoc 的通配符属性 (*) 来指示对象可以拥有除明确定义属性之外的任何其他属性。这种方法不对额外属性的键或值进行类型限制。
/**
* @typedef {Object} User
* @property {string} name - 用户名 (必填)
* @property {number} age - 用户年龄 (必填)
* @property {*} [key: value] - 允许用户添加的任意额外属性 (可选)
*/
/**
* @type {User}
*/
const tom = {
name: 'cx',
age: 25,
from: 'sh', // 不再报错
to: 'bj', // 不再报错
isActive: true, // 同样不会报错
};说明：
- @property {*} [key: value] 告诉 JSDoc，除了 name 和 age 之外，该对象可以包含任何键 (key) 和任何值 (value) 的属性。
- [key: value] 是一个占位符，表示任意键值对。
- * 表示这些额外属性的值可以是任何类型。
优点：
- 高度灵活： 允许添加任何类型的额外属性，无需提前声明。
- 简单易懂： 定义直观，易于理解。
缺点：
- 类型安全性低： 对额外属性的类型没有任何约束，可能导致潜在的运行时错误，因为类型检查器不会对这些属性的值进行验证。
3. 方法二：结合交叉类型 (&) 与字典类型 (Object.<string, Type>) 实现类型约束
当我们需要对额外属性的类型进行更具体的约束时（例如，所有额外属性的值都必须是字符串），可以使用 JSDoc 的交叉类型 (&) 结合字典类型 Object.<string, Type>。这种方法允许我们定义一个具有特定类型签名的额外属性集合，并将其与固定属性合并。
/**
* @typedef {object} UserBase
* @property {string} name - 用户名
* @property {number} age - 用户年龄
*/
/**
* @typedef {Object.<string, string>} AdditionalProperties - 额外属性，键为字符串，值为字符串
*/
/**
* @typedef {UserBase & AdditionalProperties} User - 包含固定属性和额外字符串属性的用户类型
*/
/**
* @type {User}
*/
const tom = {
name: "cx",
age: 25,
from: "sh", // 不再报错
to: "bj", // 不再报错
// isActive: true, // 如果这里尝试添加非字符串值，将引发类型错误
};
/**
* 尝试添加一个不符合类型约束的属性
* @type {User}
*/
const invalidTom = {
name: "john",
age: 30,
country: "USA",
// isVerified: true, // 错误：'true' 不是 string 类型
};说明：
- 我们首先定义了 UserBase，它包含所有固定的必选属性。
- @typedef {Object.<string, string>} AdditionalProperties 定义了一个字典类型，其中所有的键都是 string，所有的值也都是 string。你可以根据需要将 string 替换为其他类型（例如 number、boolean 或 any）。
- @typedef {UserBase & AdditionalProperties} User 使用交叉类型 (&) 将 UserBase 和 AdditionalProperties 合并。这意味着 User 类型必须满足 UserBase 的所有要求，同时其所有未明确定义的属性都必须符合 AdditionalProperties 的类型签名。
优点：
- 类型安全性高： 对额外属性的键和值类型有明确的约束，有助于在开发阶段捕获类型错误。
- 结构清晰： 将固定属性和额外属性的类型定义分离，提高了可读性。
缺点：
- 略复杂： 需要定义多个 typedef 来组合类型。
- 约束性强： 如果额外属性的类型非常多样，可能需要更复杂的 Object.<string, Type> 定义，甚至可能需要回退到 Object.<string, *>。
总结与建议
在 JSDoc 中定义同时包含固定属性和可变额外属性的对象类型时，选择哪种方法取决于你对类型安全性和灵活性的具体需求：
- 当额外属性的类型完全不可预测，且你更看重灵活性和简洁性时，请使用 @property {*} [key: value]。这种方法最简单，但牺牲了额外属性的类型检查。
- 当需要对额外属性的类型进行约束，以提高代码的健壮性和可维护性时，请使用交叉类型结合 Object.<string, Type>。这种方法提供了更强的类型保证，尤其适用于所有额外属性都遵循相似类型模式的场景。
通过合理运用这些 JSDoc 策略，你可以为复杂的 JavaScript 对象提供清晰、准确的类型定义，从而提升项目的整体质量和开发体验。
