深入解析openapi-typescript与Tanstack Query的集成方案

在构建现代Web应用时，前端开发者经常需要处理API请求和数据缓存。openapi-typescript项目提供了一个强大的工具链，能够根据OpenAPI规范自动生成TypeScript类型定义。而其子项目openapi-fetch则提供了基于这些类型定义的类型安全HTTP客户端。与此同时，Tanstack Query(原React Query)已成为管理服务器状态的事实标准库。

本文将深入探讨如何优雅地将openapi-fetch与Tanstack Query集成，解决实际开发中的类型安全和错误处理问题。

核心问题分析

openapi-fetch的设计哲学遵循fetch API的模式，即不自动抛出错误，而是返回包含数据和错误的响应对象。这与Tanstack Query的期望行为存在差异，因为Tanstack Query希望查询函数要么返回数据，要么抛出错误。

这种设计差异导致开发者需要手动处理转换逻辑：

const {data, isLoading, isError} = useQuery({
    queryFn: async () => {
        const { data, error } = await client.GET("/articles/", { params });
        if (data) return data;
        throw new Error(error);
    }
})

解决方案探讨

1. 中间件方案

openapi-fetch最新版本引入了中间件支持，这为解决集成问题提供了新思路。我们可以创建一个错误处理中间件，在响应状态码大于等于400时自动抛出错误：

const throwOnError: Middleware = {
  async onResponse(res) {
    if (res.status >= 400) {
      const body = res.headers.get('content-type')?.includes('json')
        ? await res.clone().json()
        : await res.clone().text();
      throw new Error(body);
    }
    return res;
  },
};

这种方案的优点是不需要修改现有代码结构，只需添加中间件即可实现集成。

2. 包装器方案

另一种更彻底的解决方案是创建专门的包装函数，将openapi-fetch的调用方式转换为Tanstack Query期望的形式：

type QueryClient = <T>(...args: Parameters<typeof client.GET>) => Promise<T>;

const createQueryClient = (): QueryClient => async (...args) => {
  const { data, error } = await client.GET(...args);
  if (error) throw error;
  return data;
};

这种方案提供了更干净的API接口，但需要维护额外的包装层。

类型安全考量

无论采用哪种方案，都需要注意类型安全问题。openapi-fetch返回的类型通常是T | undefined，因为TypeScript无法确定运行时是否会有错误。在使用Tanstack Query时，我们有以下几种处理类型安全的方式：

1. 显式检查错误：在回调中检查error属性

onSuccess({ data, error }) {
  if (!error) {
    // 这里data的类型会被正确推断
  }
}

2. 类型断言：在确定不会出错时使用类型断言

onSuccess({ data }) {
  const safeData = data as MyType;
}

3. 自定义错误类型：创建自定义错误类增强类型信息

class APIError extends Error {
  constructor(public body: any, public status: number) {
    super(body);
  }
}

最佳实践建议

1. 保持一致性：在整个项目中统一使用一种错误处理方案
2. 错误信息丰富化：确保抛出的错误包含足够调试信息
3. 类型安全优先：即使使用包装方案，也要确保类型系统能够捕获潜在问题
4. 考虑性能影响：中间件方案可能会对性能有轻微影响，在性能敏感场景需测试

总结

openapi-typescript与Tanstack Query的集成为开发者提供了类型安全的API请求和数据管理方案。通过中间件或包装器模式，我们可以优雅地解决两者在设计哲学上的差异。在实际项目中，开发者应根据团队习惯和项目规模选择合适的集成方案，同时注意保持类型安全和良好的错误处理实践。