如何用JSDOC的@deprecated标记第三方模块导入的符号为弃用？

1. 封装带弃用警告的函数 #

自己封装原函数，调用时输出警告提示：

import { foo as originalFoo } from 'bar';

/**
 * @deprecated 该API已弃用，请使用替代方案
 */
export function foo(...args) {
  console.warn('警告：foo函数已弃用，请勿继续使用');
  return originalFoo(...args);
}

// 后续代码使用这个封装后的foo
foo();

2. 用ESLint在开发阶段限制导入 #

配置ESLint的no-restricted-imports规则，直接阻止导入并给出提示：

{
  "rules": {
    "no-restricted-imports": [
      "error",
      {
        "paths": [
          {
            "name": "bar",
            "importNames": ["foo"],
            "message": "foo已弃用，请使用其他替代API"
          }
        ]
      }
    ]
  }
}

3. TypeScript项目通过类型声明添加弃用标记 #

创建类型声明文件覆盖原模块类型，让IDE直接显示弃用提示：

// bar.d.ts
declare module 'bar' {
  /**
   * @deprecated 该函数已弃用
   */
  export function foo(...args: Parameters<typeof import('bar').foo>): ReturnType<typeof import('bar').foo>;
}

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