audio_codebuddy/.qoder/repowiki/zh/content/前端架构/API集成.md

API集成

本文引用的文件

• request.ts
• config.ts
• debug.ts
• book-generator-api.ts
• publish-api.ts
• video-generator-api.ts
• auth.ts
• errorHandler.ts
• cache.ts
• rate-limiter.ts
• performance.ts
• tts.controller.ts
• book-generator.controller.ts

目录

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

简介

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

项目结构

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

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
• request.ts:1-207
• debug.ts:1-305
• book-generator-api.ts:1-571
• publish-api.ts:1-140
• video-generator-api.ts:1-188
• auth.ts:1-81
• errorHandler.ts:1-67
• cache.ts:1-98
• rate-limiter.ts:1-120
• performance.ts:1-110
• tts.controller.ts:1-274
• book-generator.controller.ts:1-199

章节来源

• config.ts:1-80
• request.ts:1-207
• debug.ts:1-305
• book-generator-api.ts:1-571
• publish-api.ts:1-140
• video-generator-api.ts:1-188
• auth.ts:1-81
• errorHandler.ts:1-67
• cache.ts:1-98
• rate-limiter.ts:1-120
• performance.ts:1-110
• tts.controller.ts:1-274
• book-generator.controller.ts:1-199

核心组件

• 前端请求封装与拦截器
  • 统一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
• config.ts:26-66
• debug.ts:158-191
• auth.ts:7-49
• errorHandler.ts:3-24
• cache.ts:13-47
• rate-limiter.ts:49-71
• performance.ts:29-75
• book-generator-api.ts:138-571
• publish-api.ts:42-140
• video-generator-api.ts:78-188

架构总览

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

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
• config.ts:44-66
• debug.ts:158-191
• tts.controller.ts:12-127
• auth.ts:7-49
• rate-limiter.ts:49-71
• cache.ts:13-47
• performance.ts:29-75

详细组件分析

前端请求封装与拦截器

• 统一入口
  • 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输出详细日志。

    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

章节来源

• request.ts:34-168

配置与环境适配

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

章节来源

• config.ts:26-72

调试与可观测性

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

章节来源

• debug.ts:158-278

后端中间件体系

认证中间件

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

章节来源

• auth.ts:7-81

错误处理中间件

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

章节来源

• errorHandler.ts:3-67

缓存中间件

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

章节来源

• cache.ts:13-98

限流中间件

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

章节来源

• rate-limiter.ts:17-120

性能监控中间件

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

章节来源

• performance.ts:29-110

业务API模块

书籍生成API

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

章节来源

• book-generator-api.ts:138-571
• request.ts:34-168

发布API

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

章节来源

• publish-api.ts:42-140

视频生成API

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

章节来源

• video-generator-api.ts:78-188

依赖关系分析

• 前端依赖
  • request.ts依赖config.ts与debug.ts；业务API模块依赖request.ts。

• 后端依赖

  • 控制器依赖中间件；中间件依赖redisService与rate-limiter-flexible；控制器依赖数据库与业务服务。

    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
• config.ts:1-80
• debug.ts:1-305
• book-generator-api.ts:1-571
• publish-api.ts:1-140
• video-generator-api.ts:1-188
• auth.ts:1-81
• errorHandler.ts:1-67
• rate-limiter.ts:1-120
• cache.ts:1-98
• performance.ts:1-110
• tts.controller.ts:1-274
• book-generator.controller.ts:1-199

章节来源

• request.ts:1-207
• auth.ts:1-81
• errorHandler.ts:1-67
• rate-limiter.ts:1-120
• cache.ts:1-98
• performance.ts:1-110
• tts.controller.ts:1-274
• book-generator.controller.ts:1-199

性能考量

• 前端
  • 合理设置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
• errorHandler.ts:39-67
• rate-limiter.ts:60-71
• debug.ts:158-191
• performance.ts:29-75

结论

本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启用缓存；对非幂等操作谨慎重试。
  • 后端：结合限流与熔断策略，避免雪崩效应。
• 离线与断网
  • 建议：对关键写操作增加本地队列与重放机制；对读操作启用缓存与降级策略。
• 性能监控
  • 建议：定期查看性能指标，识别慢端点与异常波动，优化热点接口与数据库查询。