如何在TypeScript Next.js项目中实现类似@deprecated的自定义提醒注解

完全懂你的困扰！用@deprecated总有种“这个函数快被淘汰了”的暗示，但很多时候我们只是想引导团队优先用另一个更合适的函数，根本没打算删掉旧函数。下面给你几个实用的方案，不用真的标记废弃也能达到提醒效果：

方案一：自定义JSDoc标签 + ESLint规则（推荐） #

你可以自己定义一个比如@useInstead或者@prefer的JSDoc标签，然后通过ESLint来检测调用这个函数的地方，给出醒目的警告，甚至让VSCode显示特殊样式。

步骤1：给函数添加自定义JSDoc标签 #

先给需要提醒的旧函数加上自定义标签，比如：

/**
 * 旧的数据处理函数
 * @useInstead 请优先使用 newProcessData() 函数
 */
function oldProcessData() {
  // 函数逻辑...
}

步骤2：配置ESLint检测规则 #

我们可以用eslint-plugin-jsdoc插件来支持自定义标签，还能给调用者抛出警告。先安装插件：

npm install eslint-plugin-jsdoc --save-dev

然后在你的.eslintrc.json里添加规则配置：

{
  "plugins": ["jsdoc"],
  "rules": {
    // 允许我们自定义的@useInstead标签
    "jsdoc/check-tag-names": ["warn", {
      "definedTags": ["useInstead"]
    }],
    // 给旧函数的调用者抛出提醒
    "no-restricted-properties": ["warn", {
      "property": "oldProcessData",
      "message": "请优先使用 newProcessData() 函数"
    }]
  }
}

如果你的函数是某个模块导出的，把object字段改成你的模块名就行。要是需要批量处理多个带标签的函数，也可以自己写个简单的自定义ESLint规则，不过函数不多的话，直接配置单个规则就够用。

方案二：VSCode自定义视觉高亮 #

如果你只想在VSCode里看到视觉提醒（比如下划线、删除线），不需要ESLint警告，可以直接修改VSCode的设置：

1. 打开VSCode设置（快捷键Ctrl+,），搜索editor.tokenColorCustomizations，点击「编辑 in settings.json」
2. 添加如下配置：

"editor.tokenColorCustomizations": {
  "textMateRules": [
    {
      "scope": "variable.function",
      "settings": {
        "fontStyle": "line-through" // 或者改成 underline 下划线
      },
      "when": "hasJSDocTag(useInstead)"
    }
  ]
}

这样只要函数带有@useInstead标签，所有调用它的地方都会显示删除线（或下划线），和@deprecated的视觉效果几乎一样，但不会传递“废弃”的信号。

方案三：TypeScript类型提示小技巧 #

如果你不需要视觉样式，只是想让调用者鼠标悬停时看到提醒，可以给旧函数加个自定义类型：

// 定义一个带提醒的类型
type PreferredFunction<T extends (...args: any[]) => any> = T & {
  /** 请优先使用 newProcessData() 函数 */
  __preferWarning: never;
};

// 给旧函数套上这个类型
const oldProcessData: PreferredFunction<() => void> = () => {
  // 函数逻辑...
};

这样当有人调用oldProcessData()时，鼠标悬停就能看到我们自定义的提醒文字，简单又有效。

备注：内容来源于stack exchange，提问作者Ryan