如何用JSDoc定义含静态属性与方法的接口并实现校验？

JSDoc 的 @implements 仅校验类的实例成员，不会检查静态属性/方法，以下是两种可行的解决思路：

1. TypeScript 原生实现（推荐） #

TypeScript 支持直接定义静态成员的接口，并通过类型约束强制类的构造函数实现这些静态成员：

// 定义静态成员的接口
interface ISomethingStatic {
  aMethod(): number;
  property: object;
}

// 类直接实现静态接口，未实现时会触发报错
class Implementation implements ISomethingStatic {
  static aMethod(): number {
    return 123;
  }

  static property: object = {};
}

// 示例：缺少静态成员时的错误提示
// Class 'BadImplementation' incorrectly implements interface 'ISomethingStatic'.
// Property 'aMethod' is missing in type 'typeof BadImplementation' but required in type 'ISomethingStatic'.
class BadImplementation implements ISomethingStatic {
  static property: object = {}; // 缺少aMethod，直接报错
}

若需同时约束实例和静态成员，可拆分两个接口分别处理：

// 实例成员接口
interface ISomethingInstance {
  instanceMethod(): void;
}

// 静态成员接口
interface ISomethingStatic {
  aMethod(): number;
  property: object;
}

// 实例成员用implements约束，静态成员通过构造函数类型校验
class Implementation implements ISomethingInstance {
  static aMethod(): number {
    return 123;
  }

  static property: object = {};

  instanceMethod(): void {}
}

2. 纯 JSDoc 方案（无需转 TypeScript） #

通过 @typedef 定义静态成员的类型，再用 @type 绑定到类的构造函数上，让 VSCode 触发类型检查：

/**
 * @typedef {Object} ISomethingStatic
 * @property {function(): number} aMethod 静态方法，返回数字
 * @property {Object} property 静态属性
 */

/**
 * @type {ISomethingStatic}
 */
class Implementation {
  static aMethod() {
    return 123;
  }

  static property = {};
}

// 示例：缺少静态成员时的提示
// Property 'aMethod' is missing in type 'typeof Implementation' but required in type 'ISomethingStatic'.
/**
 * @type {ISomethingStatic}
 */
class BadImplementation {
  static property = {}; // 缺少aMethod，VSCode会报错
}

如果需要同时保留实例成员的 @implements，可以合并类型定义：

/**
 * @interface
 */
class ISomethingInstance {
  /**
   * @returns {void}
   */
  instanceMethod() {}
}

/**
 * @typedef {typeof ISomethingInstance & {
 *   aMethod: function(): number,
 *   property: Object
 * }} ISomethingFull
 */

/**
 * @type {ISomethingFull}
 */
class Implementation {
  static aMethod() {
    return 123;
  }

  static property = {};

  instanceMethod() {}
}

核心说明 #

• JSDoc 的 @implements 设计目标仅覆盖实例成员，无法直接校验静态成员
• TypeScript 方案更原生、可靠，适合长期维护的项目
• 纯 JSDoc 方案依赖编辑器的类型推断，能满足轻量场景的需求

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