如何为TypeScript映射类型的键添加JSDoc @deprecated标签？

你遇到的问题是直接在映射类型[K in Something]上方加@deprecated不生效，这是因为这个语法是对整个类型的所有键做映射，JSDoc会把这个标记当成整个类型的注释，而非单个键的废弃提示。目前没有直接给映射类型所有键批量加@deprecated的方式，但可以通过以下几种方法实现需求：

1. 拆分类型，单独标注废弃键 #

如果你的Something类型中只有部分键需要废弃，可以把废弃键单独抽出来，用交叉类型组合，给废弃部分的键单独加注释：

// 定义废弃键的类型及注释
type DeprecatedKeys = 'oldKey';
/** @deprecated 此键即将移除，请使用newKey替代 */
type DeprecatedObj = { [K in DeprecatedKeys]: string };

// 定义有效键的类型
type ValidKeys = 'newKey';
type ValidObj = { [K in ValidKeys]: string };

// 组合成最终类型
type MyObj = DeprecatedObj & ValidObj;

function getDynamicObj(something: DeprecatedKeys | ValidKeys): MyObj {
  return { [something]: 'test' } as MyObj;
}

这种方式下，当你访问oldKey时，编辑器会正确显示废弃提示。

2. 在函数返回值的JSDoc中单独说明 #

如果提前知道哪些动态键可能被废弃，可以在函数的JSDoc里通过@property标注：

/**
 * 返回包含动态键的对象
 * @param {string} something - 动态键名
 * @returns {Object.<string, string>} 动态键值对象
 * @property {string} [oldKey] - @deprecated 此键已废弃，建议使用newKey
 */
function getDynamicObj(something) {
  return { [something]: 'test' } as { [K in typeof something]: string };
}

这种方式适合需要给特定动态键做废弃提示的场景。

3. 结合可选类型标注废弃键 #

如果废弃的键是可选的，可以把废弃键单独放在一个可选的映射类型中，并添加注释：

type Something = 'oldKey' | 'newKey';

type MyObj = {
  [K in Exclude<Something, 'oldKey'>]: string;
} & {
  /** @deprecated 此键已废弃 */
  oldKey?: string;
};

function getObj(something: Something): MyObj {
  return { [something]: 'test' } as MyObj;
}

这种写法可以让编辑器识别到oldKey的废弃状态，同时不影响其他正常键的类型检查。

内容的提问来源于stack exchange，提问作者Thiago Pereira Maia