在openapi-typescript-codegen中使用自定义Axios客户端的实践指南

背景介绍

openapi-typescript-codegen是一个强大的工具，能够根据OpenAPI规范自动生成TypeScript客户端代码。在实际开发中，我们经常需要自定义HTTP客户端的行为，比如添加拦截器、修改默认配置等。本文将详细介绍如何在openapi-typescript-codegen生成的项目中使用自定义Axios客户端。

问题发现

许多开发者在使用openapi-typescript-codegen生成Axios客户端代码时，发现文档中提到的BaseHttpRequest类在实际生成的代码中并不存在。这导致无法按照官方文档的方式自定义Axios实例。

解决方案

经过实践发现，要生成包含必要包装类的完整Axios客户端代码，需要在生成命令中添加--name参数。例如：

openapi -o ./generated/ -i http://localhost:8080/rest/v3/api-docs -c axios --useOptions --name AppClient

这个命令会生成一个完整的客户端结构，包括：

• 核心服务类
• 自定义HTTP请求类
• 类型定义
• 配置接口

生成结果分析

执行上述命令后，生成的代码结构将包含以下关键部分：

1. AppClient.ts - 主客户端类，封装了所有API服务
2. httpRequest.ts - 包含BaseHttpRequest实现，用于自定义HTTP请求
3. services/ - 包含所有API端点服务
4. models/ - 包含所有数据模型定义

自定义Axios客户端的实现

有了完整的生成代码后，我们可以通过以下步骤实现自定义Axios客户端：

1. 创建自定义Axios实例

const customAxios = axios.create({
  baseURL: 'https://api.example.com',
  timeout: 10000,
  headers: {'X-Custom-Header': 'foobar'}
});

2. 扩展BaseHttpRequest类

class CustomHttpRequest extends BaseHttpRequest {
  constructor(config: OpenAPIConfig) {
    super(config, customAxios);
  }
}

3. 使用自定义请求类初始化客户端

const client = new AppClient({
  BASE: 'https://api.example.com',
  WITH_CREDENTIALS: true,
  CREDENTIALS: 'include',
  TOKEN: 'your_token',
  USERNAME: undefined,
  PASSWORD: undefined,
  HEADERS: undefined,
  ENCODE_PATH: undefined,
}, CustomHttpRequest);

最佳实践建议

1. 拦截器使用：在自定义Axios实例中添加请求/响应拦截器，统一处理错误、添加认证信息等。

2. 配置管理：将OpenAPI配置与Axios配置分离，便于独立管理。

3. 类型安全：充分利用生成的类型定义，确保API调用的类型安全。

4. 环境适配：根据不同的环境(开发、测试、生产)配置不同的Axios实例。

总结

通过为openapi-typescript-codegen生成命令添加--name参数，我们可以获得完整的Axios客户端结构，从而能够灵活地自定义HTTP请求行为。这种方法既保持了自动生成代码的优势，又提供了足够的灵活性来满足各种定制需求。

在实际项目中，合理使用自定义Axios客户端可以显著提高代码的可维护性和一致性，特别是在需要统一处理认证、错误、日志等横切关注点时。