泛型类型守卫使用时类型被收窄为never的问题排查

问题场景 #

我在实现API响应模型时，定义了两种输出类型：

• 响应成功：返回IApiResponse<T>（T为业务数据类型）
• 响应错误：返回IApiResponse<IApiError>

相关接口定义如下：

export interface IApiResponse<T> {
  data: T | IApiError
  originalResponse: AxiosResponse<any, any> | null
  ok: boolean
  statusCode: number | undefined
  error: string | null // 自定义错误字段
  attribute: string | null // 自定义错误字段
  errorDetail: string | null // 自定义错误字段
}

export interface IApiError {
  type: string
  errors: {
    code: string
    detail: string
    attr: string
  }[]
}

我用以下类型守卫判断响应是否成功：

export function isSuccessResponse<T>(response: any): response is IApiResponse<T> {
  return response.ok
}

但实际调用时，即使确认ok为true，VS Code中response的类型仍被收窄为never：

if (isSuccessResponse<IAvailableSport[]>(response)) {
  console.log(typeof response) // hover查看response类型显示为never
}

问题原因 #

1. 接口设计的歧义
   当前IApiResponse<T>的data字段同时允许T和IApiError，无论ok是true还是false，TypeScript都无法通过ok的值推断data的具体类型。且成功/失败响应本质是同一接口的不同泛型变体，TypeScript难以区分二者的类型差异。

2. 类型守卫的逻辑缺陷
   泛型T是手动传入的，但TypeScript无法验证response.data是否真的符合T的结构。若原response的类型被推断为IApiResponse<IAvailableSport[]> | IApiResponse<IApiError>，使用isSuccessResponse<IAvailableSport[]>判断时，TypeScript找不到两个类型的有效交集，最终收窄为never。

解决方案 #

方案一：拆分成功/失败响应接口（推荐） #

将成功和失败响应拆分为独立接口，通过ok字段的字面量类型让TypeScript自动判别：

// 基础公共字段
interface IBaseApiResponse {
  originalResponse: AxiosResponse<any, any> | null
  statusCode: number | undefined
}

// 成功响应
export interface IApiSuccessResponse<T> extends IBaseApiResponse {
  ok: true
  data: T
  error: null
  attribute: null
  errorDetail: null
}

// 失败响应
export interface IApiErrorResponse extends IBaseApiResponse {
  ok: false
  data: IApiError
  error: string | null
  attribute: string | null
  errorDetail: string | null
}

// 合并后的统一响应类型
export type ApiResponse<T> = IApiSuccessResponse<T> | IApiErrorResponse

此时无需自定义类型守卫，直接通过response.ok即可完成类型收窄：

// 假设response类型为ApiResponse<IAvailableSport[]>
if (response.ok) {
  // response自动收窄为IApiSuccessResponse<IAvailableSport[]>
  console.log(response.data) // 类型为IAvailableSport[]
} else {
  // response自动收窄为IApiErrorResponse
  console.log(response.data.errors)
}

方案二：修改现有类型守卫的逻辑 #

若无法调整接口结构，需在类型守卫中同时验证data的结构，确保其符合目标类型：

// 针对数组类型的验证示例
export function isSuccessResponse(response: any): response is IApiResponse<IAvailableSport[]> {
  return response.ok && Array.isArray(response.data) && 
         response.data.every(item => 'id' in item) // 验证IAvailableSport的特征字段
}

这样TypeScript能通过结构检查，正确将response收窄为目标类型。

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