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

在现代前端开发中，类型安全和错误处理是两个至关重要的环节。本文将深入探讨如何在使用 OpenAPI-TypeScript 项目的 swr-openapi 包时，通过扩展 createQueryHook 的错误类型支持来构建更健壮的 API 客户端。

当前实现的局限性

swr-openapi 作为连接 OpenAPI 规范与 SWR 数据获取库的桥梁，其核心功能 createQueryHook 目前存在一个明显的类型约束：它只能处理 OpenAPI 规范中明确定义的错误响应类型。这种设计在实际应用中会带来以下问题：

1. 网络层错误不可见：当发生网络连接失败、CORS 错误或请求超时等情况时，原生的 fetch API 会抛出 TypeError，但这些错误无法通过类型系统提前预警
2. 自定义错误处理受限：开发者无法为自定义 fetcher 添加额外的错误元数据（如 HTTP 状态码、错误详情等）
3. 类型安全性缺口：运行时可能出现的错误与类型系统声明的不一致，导致需要额外的类型守卫

技术解决方案剖析

核心类型扩展

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

createQueryBaseHook<
  Paths extends {},
  IMediaType extends MediaType,
  Prefix extends string,
  FetcherError = never  // 新增的泛型参数
>

这种设计允许开发者在创建查询钩子时显式声明可能遇到的额外错误类型：

createQueryHook<paths, `${string}/${string}`, "pet-store", Error>(
  client,
  "pet-store"
)

类型系统整合

整合后的错误类型系统将包含三个层次：

1. 规范定义错误：OpenAPI schema 中定义的错误响应
2. 运行时错误：如 Error、TypeError 等原生错误类型
3. 自定义错误：开发者通过 fetcher 包装的增强错误对象

这种分层设计既保持了与 OpenAPI 规范的一致性，又为现实世界的错误处理提供了灵活性。

实际应用场景

增强错误元数据

结合 SWR 官方推荐的错误处理模式，现在可以安全地实现：

const fetcher = async (url: string) => {
  const res = await fetch(url);
  if (!res.ok) {
    const error = new Error('API 请求失败');
    // 添加扩展属性
    (error as any).status = res.status;
    (error as any).details = await res.json();
    throw error;
  }
  return res.json();
};

// 使用时获得完整类型提示
const { error } = useQuery("/endpoint");
if (error) {
  console.log(error.message);  // 基础错误信息
  console.log(error.status);   // 类型提示需要额外处理，但运行时安全
}

防御性编程支持

通过类型组合，开发者可以编写更完备的错误处理逻辑：

type APIError = { message: string };
type NetworkError = Error;
type CustomError = APIError | NetworkError;

const { error } = useQuery("/endpoint") as {
  error?: CustomError | undefined;
};

if (error instanceof Error) {
  // 处理网络/系统错误
} else if (error && 'message' in error) {
  // 处理 API 业务错误
}

工程实践建议

1. 错误类型标准化：建议项目定义统一的 AppError 基础类型，聚合各种错误场景
2. 类型断言工具：创建类型守卫函数来安全地处理扩展错误属性
3. 错误边界设计：在应用顶层设置错误边界组件，区分处理客户端错误和 API 错误
4. 文档规范：在团队文档中明确记录自定义错误类型的定义和使用约定

总结

通过对 swr-openapi 的错误类型系统进行扩展，我们实现了：

• 更完整的类型覆盖，减少运行时意外
• 更好的开发者体验，所有可能的错误路径都有类型提示
• 更强的扩展能力，支持自定义错误处理逻辑
• 更安全的代码，类型系统能够真实反映运行时行为

这种改进使得基于 OpenAPI 规范的前端开发既保持了规范带来的优势，又能灵活应对真实世界的复杂场景，是类型系统与实际需求平衡的优秀实践。