sionrui/frontend/api/README.md

# Mono 级别 API 架构

## 📁 目录结构

```
frontend/api/
├── axios/
│   └── client.js          # Mono 级别的 C 端 Axios 实例
├── services/
│   ├── tikhub.js          # TikHub API 服务
│   └── index.js           # 服务统一导出
└── README.md              # 本文档
```

## 🎯 设计理念

### 1. 分层清晰
- **Mono 级别** (`frontend/api/`): 可在 monorepo 中所有应用复用的代码
- **应用级别** (`frontend/app/web-gold/src/api/`): 应用特定的 API 封装

### 2. 模块化设计
- **Axios 实例**: 统一的 HTTP 客户端配置
- **API 服务**: 按功能模块组织（如 `TikHubService`）
- **Hooks**: 直接使用服务，无需全局注入

### 3. 人类可读
- 清晰的命名和注释
- 直观的导入路径
- 易于理解和维护

## 🚀 使用方式

### 在 Mono 级别使用

```javascript
// 直接使用服务
import { TikHubService } from '@gold/api/services'

const result = await TikHubService.videoToCharacters({
  fileLinkList: ['https://example.com/audio.mp3']
})
```

### 在应用层使用

```javascript
// 使用应用层封装的服务
import { CommonService } from '@/api/common'

const result = await CommonService.videoToCharacters({
  fileLinkList: ['https://example.com/audio.mp3']
})
```

### 在 Hooks 中使用

```typescript
// useVoiceText 直接使用 TikHubService，无需配置
import useVoiceText from '@gold/hooks/web/useVoiceText'

const { getVoiceText } = useVoiceText()
const transcriptions = await getVoiceText([
  { audio_url: 'https://example.com/audio.mp3' }
])
```

## 📦 添加新的 API 服务

### 1. 创建服务文件

```javascript
// frontend/api/services/my-service.js
import { clientAxios } from '@gold/api/axios/client'
import { API_BASE } from '@gold/config/api'

const BASE_URL = API_BASE.MY_SERVICE || ''

export const MyService = {
  async getData(params) {
    return await clientAxios.get(`${BASE_URL}/data`, { params })
  },
  
  async createData(data) {
    return await clientAxios.post(`${BASE_URL}/data`, data)
  },
}

export default MyService
```

### 2. 导出服务

```javascript
// frontend/api/services/index.js
export { TikHubService } from './tikhub'
export { MyService } from './my-service'
```

### 3. 使用服务

```javascript
import { MyService } from '@gold/api/services'

const data = await MyService.getData({ id: 1 })
```

## 🔧 自定义 Axios 实例

如果需要创建自定义的 Axios 实例：

```javascript
import { createClientAxios } from '@gold/api/axios/client'

const customAxios = createClientAxios({
  baseURL: '/custom-api',
  timeout: 60000,
  on401: () => {
    // 自定义 401 处理
  }
})
```

## 📝 注意事项

1. **Mono 级别代码**应该保持通用，不依赖特定应用的逻辑
2. **应用层代码**可以依赖应用特定的 store、组件等
3. **服务模块**应该按功能划分，保持单一职责
4. **Axios 实例**统一管理，避免重复配置