openapi-fetch 中错误处理的最佳实践与类型安全探讨

在基于 TypeScript 的前端开发中，openapi-fetch 是一个强大的工具，它能够根据 OpenAPI 规范自动生成类型安全的 API 客户端。然而，在实际应用中，开发者经常遇到错误处理不够直观的问题，特别是当 API 返回非 2xx 响应时。

问题背景

openapi-fetch 默认的错误处理方式是将错误作为返回值的一部分，这虽然符合函数式编程的理念，但在实际开发中往往不够直观。许多开发者更习惯使用 try-catch 结构来处理错误，特别是在与 React Query 等库配合使用时，这些库通常期望 API 调用能够抛出异常。

文档中的误导

官方文档曾经提供了一个通过中间件抛出错误的示例，但这个示例存在两个主要问题：

1. 类型定义不准确：Response 类型实际上并不包含 error 属性
2. 功能不完整：即使能够抛出错误，返回值的类型仍然包含 undefined 的可能性

解决方案探讨

中间件方案

最直接的解决方案是使用中间件来转换错误处理方式：

const throwErrorMiddleware: Middleware = {
  async onResponse({ response }) {
    if (!response.ok) {
      throw new Error(`${response.status} ${response.statusText}`);
    }
  }
};

这种方案虽然简单，但存在类型安全问题，因为即使抛出了错误，TypeScript 仍然认为返回值中的 data 可能是 undefined。

包装器方案

更完善的解决方案是创建一个包装器函数，完全改变客户端的类型签名：

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.method = method;
    this.response = response;
    this.errorPayload = errorPayload;
  }
}

function createThrowingClient<Paths extends {}>(options?: ClientOptions) {
  const client = createClient<Paths>(options);
  
  return {
    GET: (url, ...init) => wrap(client, "get", url, ...init),
    // 其他方法类似
  };
}

这种方案虽然需要更多代码，但提供了完整的类型安全，确保在成功情况下 data 不会是 undefined。

类型安全的挑战

在实现抛出错误的方案时，最大的挑战是 TypeScript 对错误处理的限制：

1. TypeScript 无法为 catch 块中的错误提供类型信息
2. 无法在类型系统中表达"这个函数要么返回数据，要么抛出特定类型的错误"

这意味着即使我们创建了 APIError 类，开发者仍然需要在 catch 块中手动检查错误类型。

与状态管理库的集成

当与 React Query 等库一起使用时，抛出错误的模式更加自然，因为这些库通常期望查询函数要么返回数据，要么抛出错误。使用中间件方案可以很好地满足这种需求：

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      queryFn: async ({ queryKey }) => {
        const [path, params] = queryKey;
        const { data } = await client.GET(path, { params });
        return data; // 如果出错，中间件已经抛出
      }
    }
  }
});

最佳实践建议

1. 简单项目：使用中间件方案，虽然类型不够完美，但实现简单
2. 复杂项目：考虑使用包装器方案，获得更好的类型安全
3. 与React Query集成：优先选择抛出错误的模式
4. 错误信息：创建自定义错误类，携带更多上下文信息

未来改进方向

openapi-fetch 可以考虑在核心库中提供以下功能：

1. 可配置的错误处理模式（返回错误或抛出错误）
2. 更好的类型支持，可能通过条件类型实现
3. 内置的自定义错误类，能够携带API错误响应

通过这些改进，可以大大提升开发者在错误处理方面的体验，同时保持类型安全。