openapi-typescript项目中错误处理中间件的实现与改进

背景介绍

openapi-typescript是一个强大的TypeScript工具集，能够根据OpenAPI规范自动生成类型定义。其中的openapi-fetch子项目提供了一个类型安全的HTTP客户端，可以根据API规范自动推断请求和响应的类型。

问题发现

在项目使用过程中，开发者发现文档中提供的错误处理中间件示例存在两个主要问题：

1. 类型错误：文档示例中假设响应对象包含error属性，但实际上该属性并不存在
2. 功能限制：即使实现了错误抛出，返回的数据类型仍然会被推断为可能包含undefined，需要额外的类型检查

技术分析

原始文档示例的问题

文档中提供的错误处理中间件示例代码如下：

onResponse({ response }) {
  if (response.error) {
    throw new Error(response.error.message);
  }
}

这段代码存在以下技术问题：

1. Response类型实际上并不包含error属性
2. 抛出普通Error会丢失原始错误响应中的有价值信息

改进方案探讨

社区提出了几种改进方案：

1. 基础改进方案：检查响应状态码而非error属性

onResponse({ response }) {
  if (!response.ok) {
    throw new Error(`${response.status} ${response.statusText}`);
  }
}

2. 完整封装方案：创建专门的APIError类和包装函数

export class APIError extends Error {
  public readonly method: HttpMethod;
  public readonly response: Response;
  public readonly errorPayload: any;

  constructor(method: HttpMethod, response: Response, errorPayload: any) {
    super(`${method.toUpperCase()} ${response.url}: ${response.status} ${response.statusText}`);
    this.name = "APIError";
    this.method = method;
    this.response = response;
    this.errorPayload = errorPayload;
  }
}

3. 类型系统改进：修改FetchResponse类型定义，移除data的可选性

最佳实践建议

基于讨论内容，推荐以下实现方式：

1. 自定义错误类：创建专门的HttpError类，保留完整的错误信息

export class HttpError extends Error {
  public errors?: Record<string, string>;
  public message: string;
  public statusCode: number;

  constructor(props: {
    statusCode: number; 
    message: string; 
    errors?: Record<string, string>;
  }) {
    super(props.message);
    this.name = "HttpError";
    this.statusCode = props.statusCode;
    this.message = props.message;
    this.errors = props.errors;
    Object.setPrototypeOf(this, HttpError.prototype);
  }
}

2. 中间件实现：在中间件中统一处理错误响应

const throwErrorMiddleware: Middleware = {
  async onResponse({ request, response, options }) {
    if (!response.ok) {
      const { message } = await response.json();
      const fallbackErrorMessage = `${response.status} - ${request.url}`;
      const errorMessage = typeof (message) === "string" ? message : fallbackErrorMessage;

      throw new HttpError({
        statusCode: response.status,
        message: errorMessage,
        errors: {
          url: request.url,
          method: request.method,
        },
      });
    }
  },
};

3. 类型安全增强：通过类型断言确保返回数据不为undefined

技术难点与解决方案

1. 类型系统限制：

   • 问题：TypeScript无法在抛出错误后自动推断剩余代码路径的数据类型
   • 解决方案：通过修改FetchResponse类型定义或使用类型断言

2. 错误信息完整性：

   • 问题：普通Error会丢失HTTP响应细节
   • 解决方案：自定义错误类保留状态码、响应体等信息

3. 与现有生态集成：

   • 问题：如TanStack Query等库期望查询函数抛出错误
   • 解决方案：在中间件层统一转换错误响应为异常抛出

总结

openapi-fetch的错误处理机制需要开发者根据实际需求进行定制。通过创建专门的错误类和中间件，可以实现类型安全且信息丰富的错误处理方案。虽然目前官方尚未内置抛出错误的选项，但社区提供的解决方案已经能够很好地满足大多数使用场景的需求。

对于需要严格类型安全的应用，建议考虑创建客户端包装器或等待官方提供更完善的支持。无论采用哪种方案，保持错误处理的统一性和信息完整性都是提升应用健壮性的关键。