# API集成

<cite>
**本文引用的文件**
- [request.ts](file://my-uniapp-vue3/src/utils/request.ts)
- [config.ts](file://my-uniapp-vue3/src/utils/config.ts)
- [debug.ts](file://my-uniapp-vue3/src/utils/debug.ts)
- [book-generator-api.ts](file://my-uniapp-vue3/src/utils/book-generator-api.ts)
- [publish-api.ts](file://my-uniapp-vue3/src/utils/publish-api.ts)
- [video-generator-api.ts](file://my-uniapp-vue3/src/utils/video-generator-api.ts)
- [auth.ts](file://server/src/middleware/auth.ts)
- [errorHandler.ts](file://server/src/middleware/errorHandler.ts)
- [cache.ts](file://server/src/middleware/cache.ts)
- [rate-limiter.ts](file://server/src/middleware/rate-limiter.ts)
- [performance.ts](file://server/src/middleware/performance.ts)
- [tts.controller.ts](file://server/src/modules/tts/tts.controller.ts)
- [book-generator.controller.ts](file://server/src/modules/book-generator/book-generator.controller.ts)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件面向AI有声书生成平台的前端与后端API集成，系统性阐述HTTP请求封装、拦截器配置、错误处理机制、认证与令牌管理、请求重试与超时策略、数据缓存与离线处理、网络状态与断网重连、以及性能监控方案。文档同时提供API接口规范、参数校验与响应处理最佳实践，帮助开发者快速理解并高效扩展API能力。

## 项目结构
前端采用UniApp生态，API封装集中在utils目录；后端基于Koa，中间件与控制器分层清晰。整体结构如下：

```mermaid
graph TB
subgraph "前端"
FE_Config["配置工具<br/>config.ts"]
FE_Request["请求封装<br/>request.ts"]
FE_Debug["调试工具<br/>debug.ts"]
FE_API_BG["书籍生成API<br/>book-generator-api.ts"]
FE_API_PUB["发布API<br/>publish-api.ts"]
FE_API_VG["视频生成API<br/>video-generator-api.ts"]
end
subgraph "后端"
BE_Router["路由与控制器<br/>tts.controller.ts<br/>book-generator.controller.ts"]
BE_MW_Auth["认证中间件<br/>auth.ts"]
BE_MW_Error["错误处理中间件<br/>errorHandler.ts"]
BE_MW_Cache["缓存中间件<br/>cache.ts"]
BE_MW_Rate["限流中间件<br/>rate-limiter.ts"]
BE_MW_Perf["性能监控中间件<br/>performance.ts"]
end
FE_Config --> FE_Request
FE_Request --> FE_API_BG
FE_Request --> FE_API_PUB
FE_Request --> FE_API_VG
FE_Request --> BE_Router
BE_Router --> BE_MW_Auth
BE_Router --> BE_MW_Error
BE_Router --> BE_MW_Cache
BE_Router --> BE_MW_Rate
BE_Router --> BE_MW_Perf
```

图表来源
- [config.ts:1-80](file://my-uniapp-vue3/src/utils/config.ts#L1-L80)
- [request.ts:1-207](file://my-uniapp-vue3/src/utils/request.ts#L1-L207)
- [debug.ts:1-305](file://my-uniapp-vue3/src/utils/debug.ts#L1-L305)
- [book-generator-api.ts:1-571](file://my-uniapp-vue3/src/utils/book-generator-api.ts#L1-L571)
- [publish-api.ts:1-140](file://my-uniapp-vue3/src/utils/publish-api.ts#L1-L140)
- [video-generator-api.ts:1-188](file://my-uniapp-vue3/src/utils/video-generator-api.ts#L1-L188)
- [auth.ts:1-81](file://server/src/middleware/auth.ts#L1-L81)
- [errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)
- [cache.ts:1-98](file://server/src/middleware/cache.ts#L1-L98)
- [rate-limiter.ts:1-120](file://server/src/middleware/rate-limiter.ts#L1-L120)
- [performance.ts:1-110](file://server/src/middleware/performance.ts#L1-L110)
- [tts.controller.ts:1-274](file://server/src/modules/tts/tts.controller.ts#L1-L274)
- [book-generator.controller.ts:1-199](file://server/src/modules/book-generator/book-generator.controller.ts#L1-L199)

章节来源
- [config.ts:1-80](file://my-uniapp-vue3/src/utils/config.ts#L1-L80)
- [request.ts:1-207](file://my-uniapp-vue3/src/utils/request.ts#L1-L207)
- [debug.ts:1-305](file://my-uniapp-vue3/src/utils/debug.ts#L1-L305)
- [book-generator-api.ts:1-571](file://my-uniapp-vue3/src/utils/book-generator-api.ts#L1-L571)
- [publish-api.ts:1-140](file://my-uniapp-vue3/src/utils/publish-api.ts#L1-L140)
- [video-generator-api.ts:1-188](file://my-uniapp-vue3/src/utils/video-generator-api.ts#L1-L188)
- [auth.ts:1-81](file://server/src/middleware/auth.ts#L1-L81)
- [errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)
- [cache.ts:1-98](file://server/src/middleware/cache.ts#L1-L98)
- [rate-limiter.ts:1-120](file://server/src/middleware/rate-limiter.ts#L1-L120)
- [performance.ts:1-110](file://server/src/middleware/performance.ts#L1-L110)
- [tts.controller.ts:1-274](file://server/src/modules/tts/tts.controller.ts#L1-L274)
- [book-generator.controller.ts:1-199](file://server/src/modules/book-generator/book-generator.controller.ts#L1-L199)

## 核心组件
- 前端请求封装与拦截器
  - 统一HTTP请求封装，支持GET/POST/PUT/DELETE，内置重试、超时、缓存、加载提示、调试日志与错误处理。
  - 自动注入Authorization头与JSON Content-Type，统一响应格式兼容与错误分支处理。
- 配置与环境适配
  - 自动识别H5/APP/Web平台，按NODE_ENV选择生产或开发API地址，支持微信小程序模拟器特殊处理。
- 调试与可观测性
  - 提供页面切换、导航拦截、API请求/响应/错误日志，便于问题定位与性能分析。
- 后端中间件体系
  - 认证中间件：支持强制认证与可选认证，Token校验与用户上下文注入。
  - 错误处理中间件：统一错误响应格式与状态码映射，开发环境返回堆栈。
  - 缓存中间件：基于Redis的响应缓存与键空间清理。
  - 限流中间件：内存与Redis双栈限流，支持多场景限流策略。
  - 性能监控中间件：统计请求总量、平均耗时、慢请求、错误率与端点维度指标。
- 业务API模块
  - 书籍生成：创建/查询/生成/进度/工作流/音频/视频/合并等全链路API。
  - 发布模块：平台账号绑定/解绑/校验、发布任务创建/重试、预览信息。
  - 视频生成：项目管理、素材管理、生成进度、从书籍生成视频项目。

章节来源
- [request.ts:34-168](file://my-uniapp-vue3/src/utils/request.ts#L34-L168)
- [config.ts:26-66](file://my-uniapp-vue3/src/utils/config.ts#L26-L66)
- [debug.ts:158-191](file://my-uniapp-vue3/src/utils/debug.ts#L158-L191)
- [auth.ts:7-49](file://server/src/middleware/auth.ts#L7-L49)
- [errorHandler.ts:3-24](file://server/src/middleware/errorHandler.ts#L3-L24)
- [cache.ts:13-47](file://server/src/middleware/cache.ts#L13-L47)
- [rate-limiter.ts:49-71](file://server/src/middleware/rate-limiter.ts#L49-L71)
- [performance.ts:29-75](file://server/src/middleware/performance.ts#L29-L75)
- [book-generator-api.ts:138-571](file://my-uniapp-vue3/src/utils/book-generator-api.ts#L138-L571)
- [publish-api.ts:42-140](file://my-uniapp-vue3/src/utils/publish-api.ts#L42-L140)
- [video-generator-api.ts:78-188](file://my-uniapp-vue3/src/utils/video-generator-api.ts#L78-L188)

## 架构总览
前后端交互遵循“前端请求封装 → 后端路由与控制器 → 中间件链路（认证/限流/缓存/性能）→ 业务服务”的标准流程。认证与错误处理贯穿始终，性能与缓存中间件提供横切能力。

```mermaid
sequenceDiagram
participant UI as "前端页面"
participant Req as "请求封装<br/>request.ts"
participant Cfg as "配置工具<br/>config.ts"
participant DBG as "调试工具<br/>debug.ts"
participant Ctrl as "控制器<br/>tts.controller.ts"
participant MW_A as "认证中间件<br/>auth.ts"
participant MW_E as "错误处理中间件<br/>errorHandler.ts"
participant MW_R as "限流中间件<br/>rate-limiter.ts"
participant MW_C as "缓存中间件<br/>cache.ts"
participant MW_P as "性能监控中间件<br/>performance.ts"
UI->>Req : 调用API方法
Req->>Cfg : 获取API基础地址
Req->>DBG : 记录请求日志
Req->>Ctrl : 发起HTTP请求
Ctrl->>MW_A : 认证校验
Ctrl->>MW_R : 限流检查
Ctrl->>MW_C : 缓存命中检测
Ctrl->>MW_P : 记录性能指标
Ctrl-->>Req : 返回统一响应
Req->>DBG : 记录响应/错误日志
Req-->>UI : Promise结果
```

图表来源
- [request.ts:34-168](file://my-uniapp-vue3/src/utils/request.ts#L34-L168)
- [config.ts:44-66](file://my-uniapp-vue3/src/utils/config.ts#L44-L66)
- [debug.ts:158-191](file://my-uniapp-vue3/src/utils/debug.ts#L158-L191)
- [tts.controller.ts:12-127](file://server/src/modules/tts/tts.controller.ts#L12-L127)
- [auth.ts:7-49](file://server/src/middleware/auth.ts#L7-L49)
- [rate-limiter.ts:49-71](file://server/src/middleware/rate-limiter.ts#L49-L71)
- [cache.ts:13-47](file://server/src/middleware/cache.ts#L13-L47)
- [performance.ts:29-75](file://server/src/middleware/performance.ts#L29-L75)

## 详细组件分析

### 前端请求封装与拦截器
- 统一入口
  - request(url, options)：支持method/data/header/showLoading/config（重试/延迟/超时/缓存/TTL）。
  - 仅GET请求支持内存缓存，缓存键为url+params序列化，TTL默认5分钟。
- 认证与头部
  - 自动从本地存储读取token并注入Authorization头；统一Content-Type为application/json。
- 重试与超时
  - retry/retryDelay/timeout可配置，默认重试0次、延迟1000ms、超时30000ms。
  - 成功后写入缓存，失败抛出最后一次错误。
- 响应处理
  - 兼容两种响应格式：{ code: 0, data: ... } 与 { success: true, data: ... }。
  - 401跳转登录并清理本地token；429返回“请求过于频繁”；5xx弹Toast并拒绝；其他错误统一提示。
- 辅助方法
  - get/post/put/del：对request的便捷封装。
  - clearRequestCache：按模式或清空缓存。
- 加载与调试
  - showLoading=true时自动显示/隐藏loading；debugApiRequest/debugApiResponse/debugApiError输出详细日志。

```mermaid
flowchart TD
Start(["进入 request"]) --> BuildURL["拼接BASE_URL与路径"]
BuildURL --> LoadToken["读取token并注入Authorization"]
LoadToken --> SetHeaders["设置Content-Type"]
SetHeaders --> CheckCache{"GET且启用缓存？"}
CheckCache --> |是| CacheHit{"缓存未过期？"}
CacheHit --> |是| ReturnCache["返回缓存数据"]
CacheHit --> |否| MakeReq["发起实际请求"]
CheckCache --> |否| MakeReq
MakeReq --> RetryLoop{"重试循环"}
RetryLoop --> TryReq["makeRequest执行"]
TryReq --> RespOK{"响应成功？"}
RespOK --> |是| WriteCache["写入缓存GET"]
WriteCache --> HideLoading["隐藏loading"]
HideLoading --> Resolve["Promise成功返回"]
RespOK --> |否| Delay["等待retryDelay"]
Delay --> RetryLoop
RetryLoop --> |超过次数| ThrowErr["抛出最后错误"]
ReturnCache --> End(["结束"])
Resolve --> End
ThrowErr --> End
```

图表来源
- [request.ts:34-168](file://my-uniapp-vue3/src/utils/request.ts#L34-L168)

章节来源
- [request.ts:34-168](file://my-uniapp-vue3/src/utils/request.ts#L34-L168)

### 配置与环境适配
- 平台识别：H5/APP/Web三类平台自动识别，微信小程序模拟器走Web路径。
- 环境区分：生产环境固定域名，开发环境H5使用反向代理路径，APP使用真实域名。
- 服务器地址：getServerBaseUrl用于拼接静态资源URL（如音频文件）。

章节来源
- [config.ts:26-72](file://my-uniapp-vue3/src/utils/config.ts#L26-L72)

### 调试与可观测性
- 页面与导航拦截：记录页面切换、navigateTo/redirectTo/switchTab/reLaunch/navigateBack调用与失败。
- API日志：请求方法、URL、参数、所在页面、耗时、响应状态与消息。
- 全局错误捕获：UnhandledRejection与window/global error事件，uni.onError回调。

章节来源
- [debug.ts:158-278](file://my-uniapp-vue3/src/utils/debug.ts#L158-L278)

### 后端中间件体系

#### 认证中间件
- 强制认证：未开启AUTH_ENABLED时注入测试用户；开启后校验Authorization头格式与JWT签名。
- 可选认证：无Token则注入测试用户，Token无效也注入测试用户，保证部分接口可用。

章节来源
- [auth.ts:7-81](file://server/src/middleware/auth.ts#L7-L81)

#### 错误处理中间件
- 统一响应：{ code, message, data }，状态码继承自错误对象。
- 开发环境附加stack信息；429错误携带retryAfter字段。

章节来源
- [errorHandler.ts:3-67](file://server/src/middleware/errorHandler.ts#L3-L67)

#### 缓存中间件
- 命中优先：Redis可用时优先从缓存返回，设置X-Cache头。
- 写入缓存：200且body存在时写入，TTL可配置。
- 清理：支持按前缀删除键空间。

章节来源
- [cache.ts:13-98](file://server/src/middleware/cache.ts#L13-L98)

#### 限流中间件
- 双栈限流：Redis可用走Redis限流，否则回退内存限流。
- 多场景策略：API全局限流、登录、短信、TTS、上传等。
- 429响应：设置Retry-After头与友好提示。

章节来源
- [rate-limiter.ts:17-120](file://server/src/middleware/rate-limiter.ts#L17-L120)

#### 性能监控中间件
- 指标采集：总请求数、平均耗时、慢请求、错误数、端点维度统计。
- 响应头：X-Response-Time标注本次耗时。
- 指标路由：提供性能指标查询接口。

章节来源
- [performance.ts:29-110](file://server/src/middleware/performance.ts#L29-L110)

### 业务API模块

#### 书籍生成API
- 能力覆盖：创建/查询/删除、生成大纲/章节/全文、工作流状态、音频/视频生成与合并、进度查询、重新生成等。
- 统一返回：外层包裹{ code, message, data }，data内聚合具体字段。
- 前端封装：基于request封装各方法，自动注入Authorization头。

章节来源
- [book-generator-api.ts:138-571](file://my-uniapp-vue3/src/utils/book-generator-api.ts#L138-L571)
- [request.ts:34-168](file://my-uniapp-vue3/src/utils/request.ts#L34-L168)

#### 发布API
- 账号管理：绑定/解绑/校验平台账号（抖音/快手/B站）。
- 任务管理：创建并发布、重试发布、查询列表与详情。
- 预览：获取视频发布预览信息。

章节来源
- [publish-api.ts:42-140](file://my-uniapp-vue3/src/utils/publish-api.ts#L42-L140)

#### 视频生成API
- 项目管理：创建/更新/删除、查询列表与详情、开始生成、获取进度。
- 素材管理：上传/删除、分类查询。
- 从书籍生成：一键从书籍生成视频项目。

章节来源
- [video-generator-api.ts:78-188](file://my-uniapp-vue3/src/utils/video-generator-api.ts#L78-L188)

## 依赖关系分析
- 前端依赖
  - request.ts依赖config.ts与debug.ts；业务API模块依赖request.ts。
- 后端依赖
  - 控制器依赖中间件；中间件依赖redisService与rate-limiter-flexible；控制器依赖数据库与业务服务。

```mermaid
graph LR
FE_REQ["request.ts"] --> FE_CFG["config.ts"]
FE_REQ --> FE_DBG["debug.ts"]
FE_BG["book-generator-api.ts"] --> FE_REQ
FE_PUB["publish-api.ts"] --> FE_REQ
FE_VG["video-generator-api.ts"] --> FE_REQ
BE_CTRL_TTS["tts.controller.ts"] --> BE_MW_AUTH["auth.ts"]
BE_CTRL_TTS --> BE_MW_ERR["errorHandler.ts"]
BE_CTRL_TTS --> BE_MW_RATE["rate-limiter.ts"]
BE_CTRL_TTS --> BE_MW_CACHE["cache.ts"]
BE_CTRL_TTS --> BE_MW_PERF["performance.ts"]
BE_CTRL_BG["book-generator.controller.ts"] --> BE_MW_AUTH
BE_CTRL_BG --> BE_MW_ERR
BE_CTRL_BG --> BE_MW_RATE
BE_CTRL_BG --> BE_MW_CACHE
BE_CTRL_BG --> BE_MW_PERF
```

图表来源
- [request.ts:1-207](file://my-uniapp-vue3/src/utils/request.ts#L1-L207)
- [config.ts:1-80](file://my-uniapp-vue3/src/utils/config.ts#L1-L80)
- [debug.ts:1-305](file://my-uniapp-vue3/src/utils/debug.ts#L1-L305)
- [book-generator-api.ts:1-571](file://my-uniapp-vue3/src/utils/book-generator-api.ts#L1-L571)
- [publish-api.ts:1-140](file://my-uniapp-vue3/src/utils/publish-api.ts#L1-L140)
- [video-generator-api.ts:1-188](file://my-uniapp-vue3/src/utils/video-generator-api.ts#L1-L188)
- [auth.ts:1-81](file://server/src/middleware/auth.ts#L1-L81)
- [errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)
- [rate-limiter.ts:1-120](file://server/src/middleware/rate-limiter.ts#L1-L120)
- [cache.ts:1-98](file://server/src/middleware/cache.ts#L1-L98)
- [performance.ts:1-110](file://server/src/middleware/performance.ts#L1-L110)
- [tts.controller.ts:1-274](file://server/src/modules/tts/tts.controller.ts#L1-L274)
- [book-generator.controller.ts:1-199](file://server/src/modules/book-generator/book-generator.controller.ts#L1-L199)

章节来源
- [request.ts:1-207](file://my-uniapp-vue3/src/utils/request.ts#L1-L207)
- [auth.ts:1-81](file://server/src/middleware/auth.ts#L1-L81)
- [errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)
- [rate-limiter.ts:1-120](file://server/src/middleware/rate-limiter.ts#L1-L120)
- [cache.ts:1-98](file://server/src/middleware/cache.ts#L1-L98)
- [performance.ts:1-110](file://server/src/middleware/performance.ts#L1-L110)
- [tts.controller.ts:1-274](file://server/src/modules/tts/tts.controller.ts#L1-L274)
- [book-generator.controller.ts:1-199](file://server/src/modules/book-generator/book-generator.controller.ts#L1-L199)

## 性能考量
- 前端
  - 合理设置timeout与retry，避免长时间阻塞UI；对高频GET接口启用缓存降低网络开销。
  - 使用debug工具定位慢请求与错误高发接口。
- 后端
  - 使用性能监控中间件观察端点耗时与慢请求占比，结合Redis缓存与限流策略平衡吞吐与稳定性。
  - 对热点接口（如音色列表、热门书籍）配置长TTL缓存，减少数据库压力。

## 故障排查指南
- 常见错误与处理
  - 401未授权：前端清除本地token并跳转登录；后端抛出UnauthorizedError。
  - 429请求频繁：前端等待Retry-After秒数再试；后端设置Retry-After头。
  - 5xx服务器错误：前端弹Toast并记录错误日志；后端统一错误响应。
- 调试建议
  - 启用DEBUG开关，查看API请求/响应/错误日志与页面切换轨迹。
  - 使用性能监控指标定位慢请求与错误率异常端点。
- 限流与缓存
  - 若出现429，检查限流策略与客户端重试逻辑；若命中缓存但数据陈旧，考虑调整TTL或主动清理。

章节来源
- [request.ts:133-159](file://my-uniapp-vue3/src/utils/request.ts#L133-L159)
- [errorHandler.ts:39-67](file://server/src/middleware/errorHandler.ts#L39-L67)
- [rate-limiter.ts:60-71](file://server/src/middleware/rate-limiter.ts#L60-L71)
- [debug.ts:158-191](file://my-uniapp-vue3/src/utils/debug.ts#L158-L191)
- [performance.ts:29-75](file://server/src/middleware/performance.ts#L29-L75)

## 结论
本API集成方案通过前端统一请求封装与后端中间件体系，实现了认证、限流、缓存、性能监控与错误处理的横切能力，配合业务API模块覆盖了从书籍生成到视频发布的完整链路。建议在生产环境中合理配置缓存与限流策略，持续监控性能指标，并完善离线与断网重连策略以提升用户体验。

## 附录

### API接口文档与最佳实践

- 统一响应格式
  - 成功：{ code: 0, message: "success", data: any }
  - 失败：{ code: number, message: string, data: null }
  - 特殊：429包含retryAfter字段；401触发前端登录跳转
- 参数校验
  - 前端：request封装自动注入Authorization与Content-Type；业务API需在调用侧确保必填参数齐全。
  - 后端：控制器内进行参数校验与业务规则检查，必要时抛出对应错误类型。
- 响应处理
  - 前端：根据code与success字段判断成功与否；401清理token并跳转登录；429提示重试；5xx弹Toast。
  - 后端：错误处理中间件统一格式化；开发环境返回stack便于定位。
- 超时与重试
  - 前端：合理设置timeout与retry；对幂等GET启用缓存；对非幂等操作谨慎重试。
  - 后端：结合限流与熔断策略，避免雪崩效应。
- 离线与断网
  - 建议：对关键写操作增加本地队列与重放机制；对读操作启用缓存与降级策略。
- 性能监控
  - 建议：定期查看性能指标，识别慢端点与异常波动，优化热点接口与数据库查询。