如何使用TypeScript与JSDoc为整个类添加类型定义？

你之前用@type标注类的方式无效，因为@type适用于变量，而非类声明。要让TypeScript检查JS类是否符合指定的TS类型结构，正确的做法是使用**@implements JSDoc标签**，具体步骤如下：

1. 优化TS类型定义（可选但更合理） #

你当前的GenericParser是仅含签名的类，更适合定义为接口（因为不需要基类实现），修改types.d.ts：

export interface GenericParser {
  // 定义构造函数签名
  new(param: string): GenericParser;
  // 定义实例方法签名
  getFoo(param: string): string[];
}

如果坚持保留原class定义，也可以继续使用，但接口更贴合“仅定义结构”的需求。

2. 在JS类中使用@implements标注 #

在JS类的JSDoc中用@implements关联TS接口，TypeScript会自动检查类的构造函数、方法是否符合类型要求：

/**
 * @implements {import('./types.d.ts').GenericParser}
 */
export class SpecificParser {
  constructor(param) {
    // 现在param会被TypeScript推断为string类型
  }

  getFoo(param) {
    // param类型为string，返回值必须是string[]
    return ['example'];
  }
}

替代方案：类表达式+@type #

如果你更倾向于用类表达式，也可以通过标注变量类型实现：

/**
 * @type {import('./types.d.ts').GenericParser}
 */
const SpecificParser = class {
  constructor(param) { /* ... */ }
  getFoo(param) { /* ... */ }
};

export { SpecificParser };

原理说明 #

• @implements是专门用于类声明的JSDoc标签，告诉TypeScript该类需要遵循指定接口的结构约束，包括构造函数和所有实例方法。
• 直接用@type标注类声明时，TypeScript无法正确关联类的构造函数与实例类型，导致参数类型仍为any。

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