130 lines
2.9 KiB
Markdown
130 lines
2.9 KiB
Markdown
# 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 实例**统一管理，避免重复配置
|
||
|