如何在TypeScript中正确声明带回调参数的函数重载？

要同时保留回调风格的向后兼容性、Promise风格的新特性，还要让TypeScript编译器通过类型检查并提供完整智能提示，核心是精准定义重载签名，同时让实现签名兼容所有重载分支。以下是具体实现方案：

1. 复用回调类型（可选，简化代码） #

先统一定义回调的类型，避免重复书写：

// 根据实际业务调整回调参数，比如是否需要返回结果
type BucketCallback = (err: Error | null) => void;

2. 编写重载签名与实现 #

在类中先声明两个重载签名，分别对应回调风格和Promise风格，再编写兼容两者的实现逻辑：

class MinioClient {
  // 重载1：回调风格（向后兼容），传入回调时返回void
  makeBucket(bucketName: string, region: string, callback: BucketCallback): void;
  // 重载2：Promise风格，无回调时返回Promise
  makeBucket(bucketName: string, region: string): Promise<void>;
  // 实现签名：必须兼容所有重载的参数和返回值
  makeBucket(bucketName: string, region: string, callback?: BucketCallback): void | Promise<void> {
    // 根据是否传入回调分支处理逻辑
    if (callback) {
      // 执行原回调风格的业务逻辑
      try {
        // 替换为实际创建Bucket的操作
        callback(null); // 成功时传入null
      } catch (err) {
        callback(err as Error); // 失败时传入错误对象
      }
      return;
    }

    // 无回调时返回Promise
    return new Promise((resolve, reject) => {
      try {
        // 复用创建Bucket的业务逻辑
        resolve();
      } catch (err) {
        reject(err);
      }
    });
  }
}

关键说明 #

• 重载签名保障智能提示：明确区分两种调用方式的参数和返回值，编辑器会根据传入的参数自动提示对应的返回类型——传回调时提示void，不传时提示Promise<void>。
• 实现签名解决兼容性：将callback设为可选参数，返回值用void | Promise<void>覆盖两种情况，直接消除编译器抛出的2394错误。
• 无需修改类原型：直接在函数内部通过分支判断处理两种调用逻辑，替代util.promisify修改原型的方案，更贴合TypeScript的类型规范。

扩展调整（处理可选参数） #

如果makeBucket存在可选参数（比如region可选），只需补充对应的重载签名并调整实现逻辑即可：

// 补充region可选的重载
makeBucket(bucketName: string, callback: BucketCallback): void;
makeBucket(bucketName: string): Promise<void>;

// 更新实现签名的参数
makeBucket(bucketName: string, regionOrCallback?: string | BucketCallback, callback?: BucketCallback): void | Promise<void> {
  // 区分参数类型：第二个参数如果是函数，视为回调，region用默认值
  let region: string;
  let cb: BucketCallback | undefined;

  if (typeof regionOrCallback === 'function') {
    region = 'default-region'; // 替换为实际默认值
    cb = regionOrCallback;
  } else {
    region = regionOrCallback ?? 'default-region';
    cb = callback;
  }

  // 后续逻辑和之前一致，根据cb是否存在分支处理
}

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