Orval项目中Blob响应类型与错误处理的兼容性问题分析

问题背景

在使用Orval生成API客户端时，当接口定义了二进制文件(如PDF)作为成功响应类型时，生成的客户端会自动将responseType设置为Blob。然而，当同一个接口定义了不同类型的错误响应(如JSON或HTML)时，这些错误响应也会被强制转换为Blob对象，导致开发者无法直接获取原始的错误信息。

技术原理

这个问题本质上源于Axios库的工作机制。当我们在OpenAPI/Swagger规范中定义了一个接口的200响应为二进制类型时，Orval会生成带有responseType: 'blob'配置的Axios请求。这个配置会指示Axios将所有响应(包括错误响应)都作为Blob对象处理。

问题复现

假设我们有一个获取宠物文件的接口：

• 成功响应(200): application/pdf类型，二进制格式
• 错误响应(404): text/html类型，字符串格式

当调用这个接口并遇到404错误时，我们期望获取的是HTML格式的错误信息字符串，但实际上得到的是一个Blob对象，需要额外的处理才能读取内容。

解决方案

虽然这个问题主要源于Axios的设计，但我们可以通过以下方式解决：

1. 手动处理Blob错误响应：

const downloadPet = (id: string) => {
  getPetFileById(id)
    .then((response) => console.log('Data', response))
    .catch((err) => new Promise((_, reject) => {
      const fileReader = new FileReader();
      fileReader.onload = () => reject(fileReader.result);
      fileReader.readAsText(err.response.data);
    }));
}

2. 修改OpenAPI规范： 可以考虑将错误响应也定义为二进制类型，保持响应类型的一致性。

3. 自定义Axios拦截器： 可以创建一个全局的响应拦截器，自动检测错误响应的内容类型并做相应处理。

最佳实践建议

1. 在设计API时，尽量保持错误响应与成功响应的内容类型一致
2. 对于混合内容类型的接口，建议在前端封装统一的错误处理逻辑
3. 考虑使用TypeScript类型守卫来区分不同类型的响应
4. 在团队内部建立API响应规范的约定，减少这类问题的发生

总结

Orval作为一个优秀的API客户端生成工具，在处理复杂响应类型时可能会遇到与底层HTTP库(Axios)的兼容性问题。理解这些限制并采取适当的解决方案，可以帮助开发者构建更健壮的前端应用。虽然这个问题没有完美的解决方案，但通过合理的架构设计和错误处理策略，可以有效地规避大部分实际使用中的困扰。