TypeScript类型不匹配：返回类型中已声明Promise包装的处理

给定一段TypeScript代码，其中Api类型已将函数返回值包装为Promise，但callApi异步函数触发了如下错误：

The return type of an async function or method must be the global Promise type. Did you mean to write 'Promise<ReturnType<Api[K]>>'?

错误原因 #

TypeScript对async函数的返回类型有强制要求：必须显式声明为全局标准的Promise<T>类型。虽然ReturnType<Api[K]>推导出来的结果确实是Promise，但它属于类型工具生成的推导类型，TS的类型检查器不会自动将其等同于原生Promise类型来认可，因此抛出错误。

解决方法 #

方法一：显式声明标准Promise类型 #

最可靠的方式是直接写出Promise<ReturnType<ApiMethods[K]>>作为返回类型——因为Api[K]的返回值本质就是Promise<ReturnType<ApiMethods[K]>>，显式声明后TS能直接识别这是合法的async函数返回值：

private async callApi<K extends keyof Api>(path: ApiPath<K>, payload: Payload<K>): Promise<ReturnType<ApiMethods[K]>> {
  // 示例实现：发起API请求并返回结果
  const res = await fetch(`${this.options.apiRoot}${path}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload)
  });
  return res.json() as ReturnType<ApiMethods[K]>;
}

方法二：通过辅助类型明确推导关系 #

如果想保留基于Api类型的推导逻辑，可以定义一个辅助类型来明确返回值是Promise，避免TS的类型识别问题：

// 定义辅助类型，明确Api方法的返回值类型
type ApiMethodResponse<K extends keyof Api> = ReturnType<Api[K]>;

// 修改callApi的返回类型
private async callApi<K extends keyof Api>(path: ApiPath<K>, payload: Payload<K>): ApiMethodResponse<K> {
  // 实现逻辑
}

不过这种方式偶尔仍可能触发类型检查错误，因此更推荐第一种显式声明的方式。

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