如何在TypeScript中标记内容为废弃？含类型定义文件场景

嘿，我来帮你搞定TypeScript里标记内容为废弃的问题，不管是类型定义文件还是普通业务代码都适用～

1. 用@deprecated JSDoc注释（官方推荐，最通用） #

这是TypeScript支持最完善的方式，不管是.d.ts类型定义文件还是普通TS代码都能用，主流编辑器（比如VS Code）会自动识别，给废弃内容加上删除线，hover时还会显示提示信息。

比如针对你提到的废弃API，在类型定义里可以这么写：

/**
 * 此API无任何作用，仅为兼容性保留。
 * @deprecated 请不要再使用此方法，它仅用于兼容旧代码
 */
declare function legacyUnusedMethod(): void;

普通业务代码里的废弃函数也可以照搬这个写法：

/**
 * 旧的数据处理函数，已被新方法替代
 * @deprecated 请使用`newDataHandler()`替代
 */
function oldDataHandler(): void {
  // 仅保留兼容逻辑
}

2. 搭配@see引导替代方案 #

如果有对应的新API，可以在注释里加上@see，方便用户直接跳转使用：

/**
 * 旧的初始化方法
 * @deprecated 此方法已废弃，请使用新的初始化逻辑
 * @see newInitFunction
 */
declare function oldInit(): void;

declare function newInitFunction(): void;

3. 标记接口中的废弃属性 #

如果是接口里的属性需要标记废弃，同样用JSDoc注释即可：

interface OldConfig {
  /**
   * 旧的配置项
   * @deprecated 请使用`modernConfig`替代
   */
  legacyConfig: string;
  modernConfig: string;
}

4. 编译层面强制警告（可选） #

如果你想让使用废弃代码时触发编译警告，可以在tsconfig.json里开启noDeprecated选项（TypeScript 4.4+支持），这样编译时只要用到废弃内容就会抛出警告，更严格地约束代码：

{
  "compilerOptions": {
    "noDeprecated": true,
    // 其他编译配置...
  }
}

总结一下，@deprecated JSDoc注释是最通用且友好的方案，完全能满足你在类型定义里标记废弃API，同时兼容旧代码的需求，普通业务代码里也能直接复用这个方式～

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