资源描述
axios-api-versioning 是一款专为 Axios 设计的 API 版本管理扩展库。它允许开发者在 JavaScript 项目中轻松管理多个 API 版本，无需维护多个 Axios 实例。适用于需要平滑过渡 API 版本、兼容旧版客户端或进行灰度测试的前端及 Node.js 场景，有效简化 API 迭代与请求配置，提升代码可维护性。
详细内容
### 工具定位与核心价值
`axios-api-versioning` 是一个轻量级的 Axios 扩展库，旨在为前端和 Node.js 项目提供优雅的 API 版本控制能力。其核心价值在于允许开发者在单一 Axios 实例中管理多个 API 版本，避免了为不同版本创建多个实例的冗余，大幅简化了 API 迭代过程中的请求管理。
### 主要功能列表
- **多版本策略支持**：支持通过 URL 路径、请求头（Header）、查询参数（Query）或媒体类型（Media Type）等多种方式传递版本号。
- **无缝集成**：作为 Axios 的包装器，完全兼容现有的 Axios 拦截器、默认配置和生态插件。
- **灵活的默认版本**：支持配置全局默认版本号，当请求未指定版本时自动应用默认策略。
- **TypeScript 友好**：提供完整的类型定义，提升开发体验和代码安全性。
### 典型使用场景
- **API 平滑升级**：在后端发布新版接口时，前端可逐步迁移，新旧版本接口在同一项目中稳定共存。
- **多端兼容维护**：针对未强制更新的旧版 App 客户端继续提供旧版接口支持，而新版 Web 端使用新版接口。
- **灰度发布验证**：通过动态切换请求的 API 版本，配合后端实现接口的灰度验证与 A/B 测试。
### 上手步骤与操作要点
**1. 安装依赖**
```bash
npm install axios axios-api-versioning
```
**2. 初始化配置**
使用 `addVersioning` 方法包装原有的 Axios 实例，并配置版本控制策略：
```javascript
import axios from 'axios';
import { addVersioning } from 'axios-api-versioning';
const apiClient = addVersioning(axios.create({
baseURL: 'https://api.example.com'
}), {
defaultVersion: '1.0',
versioningStrategy: 'url' // 支持 'url', 'header', 'query', 'mediaType'
});
```
**3. 发起版本化请求**
在请求配置中通过 `version` 属性指定当前请求的版本：
```javascript
// 若策略为 url，请求将自动转换为 https://api.example.com/v2/users
apiClient.get('/users', {
version: '2.0'
});
```