audio_codebuddy/.qoder/repowiki/zh/content/系统架构/模块架构/通信模式.md

通信模式

本文引用的文件

• server/src/app.ts
• server/src/services/websocket.service.ts
• server/src/modules/tts/tts.controller.ts
• server/src/modules/auth/auth.controller.ts
• server/src/middleware/auth.ts
• server/src/middleware/security.ts
• server/src/middleware/rate-limiter.ts
• server/src/services/queue.service.ts
• server/src/modules/book-generator/book-queue.processor.ts
• server/src/services/memory-queue.ts
• my-uniapp-vue3/src/utils/websocket.ts

目录

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

引言

本文件面向“AI有声书生成平台”的通信模式，系统化梳理平台内部的三类通信机制：同步通信（RESTful API）、异步通信（消息队列/Bull）与实时通信（WebSocket），并结合中间件管道（请求预处理、身份验证、权限检查、响应后处理）与事件驱动架构（事件发布订阅、消息路由、错误重试），给出架构图、流程图与最佳实践，帮助开发者与运维人员快速理解与优化系统通信。

项目结构

后端基于 Koa 应用，统一注册路由与中间件；前端采用 uni-app，内置 WebSocket 管理器，支持 H5 与小程序环境。平台围绕“异步任务 + 实时推送 + REST API”构建，形成高吞吐、低耦合的通信体系。

graph TB
subgraph "前端"
FE["uni-app 应用<br/>WebSocket 管理器"]
end
subgraph "后端"
APP["Koa 应用<br/>路由与中间件"]
WS["WebSocket 服务<br/>/ws 路径"]
Q["队列服务(Bull)<br/>Redis/内存回退"]
BKQ["书籍生成队列处理器"]
end
FE -- "HTTP REST API" --> APP
FE -- "WebSocket" --> WS
APP -- "异步任务入队" --> Q
Q -- "并发执行" --> BKQ
BKQ -- "事件广播" --> WS
WS -- "实时推送" --> FE

图表来源

• server/src/app.ts:57-130
• server/src/services/websocket.service.ts:102-133
• server/src/services/queue.service.ts:48-122
• server/src/modules/book-generator/book-queue.processor.ts:48-83

章节来源

• server/src/app.ts:57-130

核心组件

• REST API 层：以 Koa Router 注册各模块路由，统一处理 CORS、BodyParser、静态资源、健康检查与指标暴露。
• 中间件管道：错误处理、性能监控、日志、安全（XSS/SQL 注入）、速率限制、认证与可选认证。
• 异步队列：Bull 队列承载音频/视频/书籍生成等长耗时任务，具备 Redis 回退与并发控制。
• 实时通信：WebSocket 服务在 /ws 路径上建立连接，向客户端推送生成完成与进度事件。
• 前端 WebSocket 管理器：封装连接、订阅、重连与事件派发，适配 H5/小程序。

章节来源

• server/src/app.ts:63-130
• server/src/middleware/security.ts:6-27
• server/src/middleware/rate-limiter.ts:49-72
• server/src/middleware/auth.ts:7-49
• server/src/services/queue.service.ts:48-122
• server/src/services/websocket.service.ts:102-133
• my-uniapp-vue3/src/utils/websocket.ts:15-196

架构总览

下图展示三类通信模式在系统中的应用位置与数据流向：

graph TB
C["客户端/浏览器"] --> |REST API| R["Koa 路由"]
R --> M1["安全中间件<br/>XSS/SQL注入"]
R --> M2["速率限制中间件"]
R --> M3["认证中间件"]
R --> S["业务控制器<br/>如 tts.auth.book-generator"]
S --> |异步任务| Q["队列服务(Bull)"]
Q --> P["队列处理器<br/>并发执行"]
P --> E["领域服务/LLM"]
P --> W["WebSocket 服务"]
W --> |事件推送| C
subgraph "实时通道"
W
end
subgraph "异步通道"
Q
P
end
subgraph "同步通道"
R
M1
M2
M3
end

图表来源

• server/src/app.ts:63-130
• server/src/middleware/security.ts:6-27
• server/src/middleware/rate-limiter.ts:49-72
• server/src/middleware/auth.ts:7-49
• server/src/services/queue.service.ts:48-122
• server/src/services/websocket.service.ts:102-133

详细组件分析

同步通信（RESTful API）

• 设计要点
  • 统一使用 Koa Router 注册模块路由，集中处理 CORS、BodyParser、静态资源与健康检查。
  • 控制器内进行参数校验、权限检查与配额校验，必要时调用订阅服务与数据库。
  • 对外返回统一结构，便于前端消费。
• 典型流程（TTS 生成）
  • 客户端发起 POST /api/tts/generate，携带文本、音色、可选书籍章节信息。
  • 控制器执行 optionalAuth（可选认证）、参数校验、配额检查、调用服务生成异步任务。
  • 立即返回任务创建结果，后续通过 WebSocket 推送状态。

• 安全与限流

  • 安全中间件对请求体与查询参数进行 XSS/SQL 注入清洗，并设置安全响应头。
  • 速率限制中间件按接口维度（API、登录、短信、TTS、上传）配置不同阈值。

  • 认证中间件支持强制认证与可选认证两种模式，开发环境可跳过。

    sequenceDiagram
    participant Client as "客户端"
    participant Router as "Koa 路由(tts)"
    participant MW_Auth as "认证中间件"
    participant MW_Rate as "限流中间件"
    participant MW_Sec as "安全中间件"
    participant Ctrl as "TTS 控制器"
    participant Queue as "队列服务"
    participant WS as "WebSocket 服务"
    Client->>Router : "POST /api/tts/generate"
    Router->>MW_Sec : "XSS/SQL 注入清洗"
    Router->>MW_Rate : "速率限制检查"
    Router->>MW_Auth : "optionalAuth/强制认证"
    Router->>Ctrl : "进入控制器"
    Ctrl->>Ctrl : "参数校验/配额检查"
    Ctrl->>Queue : "异步生成任务"
    Ctrl-->>Client : "返回任务创建结果"
    Queue-->>WS : "完成后推送事件"
    WS-->>Client : "实时推送生成完成"
    

图表来源

• server/src/modules/tts/tts.controller.ts:52-127
• server/src/middleware/auth.ts:7-49
• server/src/middleware/rate-limiter.ts:49-72
• server/src/middleware/security.ts:6-27
• server/src/services/queue.service.ts:131-160
• server/src/services/websocket.service.ts:66-86

章节来源

• server/src/modules/tts/tts.controller.ts:52-127
• server/src/middleware/auth.ts:7-49
• server/src/middleware/rate-limiter.ts:49-72
• server/src/middleware/security.ts:6-27

异步通信（消息队列/Bull）

• 设计原则
  • 队列仅负责排队与并发控制，失败重试、超时管理与业务逻辑分别由容错层、AI 服务层与领域层承担。
  • 优先使用 Redis 队列，若不可用则回退至内存队列，保证系统可用性。
• 关键能力
  • 任务类型：音频生成、视频生成、书籍生成、邮件发送等。
  • 任务状态：waiting/active/completed/failed/delayed。
  • 进度回调：支持任务进度上报与回调触发。
  • 统计与运维：提供队列统计、暂停/恢复、清空、优雅关闭等操作。

• 书籍生成处理器

  • 初始化时优先使用 Redis 队列，最大并发 3；若 Redis 不可用则使用内存队列。

  • 启动时扫描数据库中处于生成中的书籍，恢复中断任务并重新入队。

    flowchart TD
    Start(["提交任务"]) --> Add["入队(Redis/内存)"]
    Add --> Consume{"Redis可用?"}
    Consume --> |是| RedisProc["Redis队列处理器<br/>并发执行"]
    Consume --> |否| MemProc["内存队列处理器<br/>并发执行"]
    RedisProc --> Domain["领域服务/LLM生成"]
    MemProc --> Domain
    Domain --> Done{"完成?"}
    Done --> |是| Push["推送完成事件"]
    Done --> |否| Fail["标记失败/记录错误"]
    Push --> End(["结束"])
    Fail --> End
    

图表来源

• server/src/services/queue.service.ts:48-122
• server/src/services/memory-queue.ts:17-99
• server/src/modules/book-generator/book-queue.processor.ts:48-83

章节来源

• server/src/services/queue.service.ts:48-122
• server/src/services/memory-queue.ts:17-99
• server/src/modules/book-generator/book-queue.processor.ts:48-83

实时通信（WebSocket 双向通信）

• 服务端
  • 在 HTTP 服务器上监听 upgrade，仅接受 /ws 路径，从查询参数提取 clientId 并维护连接映射。
  • 提供客户端管理（添加/移除）、广播与定向推送，支持音频/视频生成完成与批量进度事件。
• 前端
  • WebSocketManager 封装连接、订阅、重连与事件派发；支持 H5 与小程序。
  • 自动重连（最多 3 次，间隔 3s），重连成功后自动重新订阅事件。

• 典型流程

  • 客户端连接 /ws，接收 connected 事件。

  • 服务端在书籍/音频/视频生成完成后，广播对应事件，前端按 bookId 过滤并更新 UI。

    sequenceDiagram
    participant FE as "前端 WebSocketManager"
    participant HTTP as "HTTP 服务器"
    participant WS as "WebSocket 服务"
    participant BKQ as "书籍生成处理器"
    FE->>HTTP : "发起 upgrade /ws?clientId=..."
    HTTP->>WS : "交由 WebSocket 服务处理"
    WS-->>FE : "发送 connected 事件"
    BKQ-->>WS : "生成完成事件"
    WS-->>FE : "广播事件(音频/视频/书籍完成)"
    FE->>FE : "根据 bookId 过滤并更新 UI"
    

图表来源

• server/src/services/websocket.service.ts:102-133
• my-uniapp-vue3/src/utils/websocket.ts:25-82
• server/src/services/websocket.service.ts:66-86

章节来源

• server/src/services/websocket.service.ts:102-133
• my-uniapp-vue3/src/utils/websocket.ts:25-82

中间件管道设计模式

• 请求预处理
  • CORS、BodyParser、静态资源、健康检查与指标暴露。
• 身份验证
  • 强制认证：要求 Bearer Token，开发环境可通过开关跳过。
  • 可选认证：无 Token 时自动降级为测试用户，便于调试。
• 权限检查
  • 控制器内结合用户上下文与订阅配额进行权限判断。
• 响应后处理
  • 敏感数据脱敏（密码、token 等）与统一响应结构。
• 安全加固
  • XSS/SQL 注入检测与清洗，设置安全响应头。

• 速率限制

  • 多维度限流策略，避免滥用与攻击。

    flowchart TD
    Req["请求到达"] --> CORS["CORS/BodyParser/静态资源"]
    CORS --> SEC["安全中间件(XSS/SQL)"]
    SEC --> RL["速率限制"]
    RL --> AUTH["认证(强制/可选)"]
    AUTH --> CTRL["控制器处理"]
    CTRL --> RESP["统一响应/脱敏"]
    RESP --> End["返回客户端"]
    

图表来源

• server/src/app.ts:63-83
• server/src/middleware/security.ts:6-27
• server/src/middleware/rate-limiter.ts:49-72
• server/src/middleware/auth.ts:7-49

章节来源

• server/src/app.ts:63-83
• server/src/middleware/security.ts:6-27
• server/src/middleware/rate-limiter.ts:49-72
• server/src/middleware/auth.ts:7-49

事件驱动架构与错误重试

• 事件发布订阅
  • 书籍生成完成后，通过 WebSocket 广播事件；前端按需订阅。
• 消息路由
  • 队列服务负责任务路由与并发调度；处理器根据任务类型路由到相应领域服务。

• 错误重试与恢复

  • 队列层不负责失败重试，重试策略由容错层承担；超时与业务异常由 LLM/领域服务处理。

  • 服务器启动时扫描数据库中处于生成中的书籍，自动恢复中断任务并重新入队。

    flowchart TD
    Scan["启动时扫描中断任务"] --> ReEnq["重新入队"]
    ReEnq --> Proc["队列处理器执行"]
    Proc --> OK{"成功?"}
    OK --> |是| Notify["推送完成事件"]
    OK --> |否| FT["容错层重试/告警"]
    Notify --> End["结束"]
    FT --> End
    

图表来源

• server/src/modules/book-generator/book-queue.processor.ts:88-124
• server/src/services/queue.service.ts:131-160

章节来源

• server/src/modules/book-generator/book-queue.processor.ts:88-124
• server/src/services/queue.service.ts:131-160

依赖关系分析

• 应用层依赖
  • app.ts 统一注册路由与中间件，启动时初始化 Sentry、数据库、Redis、存储、WebSocket、书籍生成队列与中断任务恢复。
• 控制器依赖
  • tts.controller.ts 依赖订阅服务与数据库进行配额与存在性校验。
  • auth.controller.ts 依赖认证服务与数据库进行用户信息读取与更新。
• 服务层依赖
  • queue.service.ts 依赖 redis.service 与 memory-queue；book-queue.processor.ts 依赖 langGraphGenerator、bookStore、prisma。

• 实时通信依赖

  • websocket.service.ts 依赖 ws；前端 websocket.ts 依赖 uni.connectSocket 与配置。

    graph LR
    APP["app.ts"] --> WS["websocket.service.ts"]
    APP --> Q["queue.service.ts"]
    APP --> BKQ["book-queue.processor.ts"]
    BKQ --> LG["langGraphGenerator"]
    BKQ --> BS["book-store"]
    BKQ --> PRISMA["prisma"]
    TTS["tts.controller.ts"] --> SUB["subscription.service.ts"]
    AUTHC["auth.controller.ts"] --> AUTHS["auth.service.ts"]
    

图表来源

• server/src/app.ts:133-172
• server/src/services/websocket.service.ts:102-133
• server/src/services/queue.service.ts:48-122
• server/src/modules/book-generator/book-queue.processor.ts:48-83

章节来源

• server/src/app.ts:133-172
• server/src/modules/book-generator/book-queue.processor.ts:48-83

性能考量

• 队列并发与超时
  • 书籍生成任务最大并发 3，超时 2 小时；音频 5 分钟、视频 10 分钟，避免长时间占用资源。
• 限流策略
  • 全局限流、登录限流、短信限流、TTS 限流、上传限流，按接口与用户维度精细化控制。
• 缓存与存储
  • Redis 可用时优先使用；存储类型可切换（OSS/本地），启动时进行连通性检测。
• 前端重连与订阅
  • WebSocketManager 自动重连与事件重订阅，降低弱网与断线影响。

章节来源

• server/src/services/queue.service.ts:166-190
• server/src/middleware/rate-limiter.ts:77-120
• server/src/app.ts:142-151
• my-uniapp-vue3/src/utils/websocket.ts:162-190

故障排查指南

• WebSocket 连接问题
  • 检查 /ws 路径与 clientId 参数；确认服务端升级处理逻辑与客户端重连策略。
  • 查看服务端日志与客户端 onOpen/onError/onClose 回调。
• 队列不可用
  • Redis 不可用时会回退到内存队列；检查 Redis 连接与队列可用性标志。
  • 关注队列错误事件与处理器的 completed/failed 回调。
• 认证与限流
  • 确认 Authorization 头格式与 Token 有效性；检查限流中间件返回的 Retry-After。
• 安全拦截
  • 若出现 400 非法字符提示，检查请求体与查询参数是否包含 SQL 注入特征。
• 优雅关闭
  • 服务端监听 SIGTERM/SIGINT，确保队列与 Redis 正常关闭。

章节来源

• server/src/services/websocket.service.ts:102-133
• server/src/services/queue.service.ts:53-59
• server/src/middleware/rate-limiter.ts:52-71
• server/src/middleware/security.ts:69-83
• server/src/app.ts:174-187

结论

该平台通过“REST API + 队列 + WebSocket”的组合实现了高可用、可扩展的通信体系：同步 API 提供即时交互体验，异步队列承载长耗时任务并具备回退与恢复能力，实时 WebSocket 保障事件推送的及时性。配合完善的中间件管道（安全、限流、认证）与事件驱动架构，系统在安全性、性能与可靠性方面均具备良好基础。建议在生产环境中启用全局限流与认证开关，并持续监控队列与 WebSocket 的运行状态，以进一步提升稳定性与用户体验。