OpenAPI TypeScript 项目中增强 SWR 错误处理的实践方案

在现代前端开发中，类型安全和错误处理是两个至关重要的环节。OpenAPI TypeScript 项目通过自动生成类型定义，为开发者提供了强大的类型支持。然而，在实际应用中，我们发现其与 SWR 库结合时存在一个明显的类型缺陷——无法正确处理非 OpenAPI 定义的错误类型。

当前问题分析

当开发者使用 createQueryHook 创建自定义 Hook 时，目前只能识别 OpenAPI 规范中明确定义的错误类型。这导致了一个类型安全限制：常见的网络错误（如 TypeError）或开发者自定义的错误类型无法被类型系统捕获。

考虑以下典型场景：

const { data, error } = useQuery("/api/endpoint");

按照当前实现，error 的类型仅包含 OpenAPI 定义的结构（如 { message: string }），而实际运行时可能遇到的 TypeError 或自定义错误完全游离于类型系统之外。

技术解决方案

核心改进思路

通过在 createQueryBaseHook 中引入泛型参数 FetcherError，我们可以实现错误类型的可扩展性：

createQueryBaseHook<Paths, IMediaType, Prefix, FetcherError = never>

这种设计带来了以下优势：

1. 向后兼容：默认值为 never 保持现有行为
2. 灵活扩展：开发者可以指定自定义错误类型
3. 类型安全：将所有可能的错误类型纳入类型系统

实际应用示例

开发者可以这样使用改进后的 Hook：

// 定义包含网络错误的查询Hook
const useQuery = createQueryHook<paths, `${string}/${string}`, "api", Error>(
  client,
  "api"
);

// 使用时获得完整类型提示
const { error } = useQuery("/endpoint");
// error 类型现在包含：API定义错误 | Error | undefined

深入技术价值

对错误处理模式的提升

现代前端应用通常需要处理多层级的错误：

1. 网络层错误（如 TypeError）
2. HTTP 状态码错误（如 404、500）
3. 业务逻辑错误（OpenAPI 定义）

本方案通过类型系统完整覆盖了这些场景，使开发者能够：

• 在编译期发现错误处理遗漏
• 实现更精细的错误分类处理
• 保持类型推断的连贯性

与 SWR 生态的深度整合

SWR 本身提供了丰富的错误处理机制，如：

const fetcher = async (url) => {
  const res = await fetch(url);
  if (!res.ok) {
    const error = new Error();
    error.status = res.status;  // 附加状态码
    error.info = await res.json();  // 附加错误详情
    throw error;
  }
  return res.json();
};

改进后的类型系统能够完美支持这种模式，将自定义错误属性纳入类型检查范围，实现真正的端到端类型安全。

实施建议

对于项目维护者，建议采用渐进式改进策略：

1. 首先实现基础泛型支持
2. 提供详细的类型文档和迁移指南
3. 考虑为常见错误类型（如 Error）提供预设配置

对于使用者，升级后可获得以下收益：

• 更可靠的错误处理代码
• 减少运行时意外错误
• 提升代码可维护性

总结

通过在 OpenAPI TypeScript 的 SWR 集成中引入错误类型泛型，我们不仅解决了一个具体的技术限制，更重要的是建立了一个可扩展的类型安全架构。这种改进体现了现代 TypeScript 开发的核心思想：通过类型系统尽可能多地捕获潜在问题，将运行时错误转化为编译期错误，最终提升应用的整体质量。

对于正在使用或考虑采用 OpenAPI TypeScript 的项目，这一改进将显著增强其错误处理能力，特别是在复杂企业级应用中，完善的错误类型系统将成为保障应用稳定性的重要基石。