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 级别使用

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

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

在应用层使用

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

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

在 Hooks 中使用

// 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. 创建服务文件

// 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. 导出服务

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

3. 使用服务

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

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

🔧 自定义 Axios 实例

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

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

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

📝 注意事项

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