在hey-api/openapi-ts项目中使用Axios上传进度监控功能

在基于OpenAPI规范的TypeScript客户端开发中，文件上传进度监控是一个常见的需求。本文将详细介绍如何在hey-api/openapi-ts项目中正确配置和使用Axios的onUploadProgress功能。

项目背景

hey-api/openapi-ts是一个用于生成TypeScript客户端代码的工具，它可以根据OpenAPI规范自动生成与后端API交互的客户端代码。在最新版本中，推荐使用@hey-api/client-axios客户端而非legacy/axios实现。

核心问题解决

1. 上传进度监控实现

要在生成的客户端代码中使用Axios的onUploadProgress功能，可以通过以下方式实现：

const response = await YourService.uploadFile(data, {
  onUploadProgress: (progressEvent) => {
    const percentCompleted = Math.round(
      (progressEvent.loaded * 100) / progressEvent.total
    );
    console.log(`上传进度: ${percentCompleted}%`);
  }
});

2. 认证配置注意事项

在使用新版客户端时，认证配置方式有所变化：

import { client } from "your-generated-client";

client.setConfig({
  baseURL: "your-api-base-url",
  accessToken: async () => {
    return localStorage.getItem("access_token") || "";
  },
});

需要注意的是，accessToken功能需要使用实验性解析器才能正常工作。在openapi-ts.config.ts配置文件中需要启用：

export default defineConfig({
  input: "your-openapi-spec.json",
  output: "src/client",
  parser: "experimental", // 必须启用实验性解析器
  // 其他配置...
});

3. 方法名生成器调整

如果项目中自定义了方法名生成逻辑，需要注意新版解析器的中间表示模型有所变化，需要相应调整生成函数：

export function operationNameGenerator(operation) {
  return operation.operationId
    ? operation.operationId
    : `${operation.method}${operation.path
        .split("/")
        .filter(Boolean)
        .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
        .join("")}`;
}

最佳实践建议

1. 迁移建议：从legacy/axios迁移到@hey-api/client-axios时，注意响应数据结构的变化（response.data包含实际数据）

2. 错误处理：在上传过程中添加适当的错误处理逻辑

3. UI反馈：将上传进度信息与UI组件绑定，提供更好的用户体验

4. 性能考虑：对于大文件上传，考虑结合进度监控实现断点续传功能

通过以上配置和实现，开发者可以在hey-api/openapi-ts生成的客户端中充分利用Axios的上传进度监控功能，同时确保认证等核心功能的正常工作。