如何用JSDoc描述含必填属性与额外属性的对象类型？

要让User类型既包含必填的name（字符串）和age（数字）属性，又支持添加任意数量的其他属性，只需在JSDoc的类型定义中添加索引签名，或者用交叉类型结合Record来实现，两种方案都能解决额外属性报错的问题：

方案一：添加索引签名（纯JSDoc写法） #

直接在@typedef的User类型里定义一个匹配任意字符串键的属性，允许值为任意类型：

/**
 * @typedef {object} User
 * @property {string} name - 用户名
 * @property {number} age - 用户年龄
 * @property {any} [key: string] - 允许添加任意额外属性
 */

/**
 * @type {User}
 */
const tom = {
  name: 'cx',
  age: 25,
  from: 'sh', // 不再触发报错
  to: 'bj'    // 不再触发报错
}

这里的[key: string]是索引签名，代表可以用任意字符串作为属性名，any表示属性值可以是任意类型；如果需要限制额外属性的类型，把any换成对应的类型（比如string、number）即可。

方案二：交叉类型结合Record（TypeScript风格JSDoc） #

利用TypeScript的交叉类型&，将必填属性对象和任意键值对类型Record<string, any>合并：

/**
 * @typedef {Record<string, any> & { name: string; age: number }} User
 */

/**
 * @type {User}
 */
const tom = {
  name: 'cx',
  age: 25,
  from: 'sh',
  to: 'bj'
}

Record<string, any>表示任意字符串键对应任意值的对象，和必填属性对象交叉后，既强制要求name和age存在，又允许添加其他属性。

内容的提问来源于stack exchange，提问作者Fander