# 通信模式
**本文引用的文件**
- [server/src/app.ts](file://server/src/app.ts)
- [server/src/services/websocket.service.ts](file://server/src/services/websocket.service.ts)
- [server/src/modules/tts/tts.controller.ts](file://server/src/modules/tts/tts.controller.ts)
- [server/src/modules/auth/auth.controller.ts](file://server/src/modules/auth/auth.controller.ts)
- [server/src/middleware/auth.ts](file://server/src/middleware/auth.ts)
- [server/src/middleware/security.ts](file://server/src/middleware/security.ts)
- [server/src/middleware/rate-limiter.ts](file://server/src/middleware/rate-limiter.ts)
- [server/src/services/queue.service.ts](file://server/src/services/queue.service.ts)
- [server/src/modules/book-generator/book-queue.processor.ts](file://server/src/modules/book-generator/book-queue.processor.ts)
- [server/src/services/memory-queue.ts](file://server/src/services/memory-queue.ts)
- [my-uniapp-vue3/src/utils/websocket.ts](file://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”构建，形成高吞吐、低耦合的通信体系。
```mermaid
graph TB
subgraph "前端"
FE["uni-app 应用
WebSocket 管理器"]
end
subgraph "后端"
APP["Koa 应用
路由与中间件"]
WS["WebSocket 服务
/ws 路径"]
Q["队列服务(Bull)
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](file://server/src/app.ts#L57-L130)
- [server/src/services/websocket.service.ts:102-133](file://server/src/services/websocket.service.ts#L102-L133)
- [server/src/services/queue.service.ts:48-122](file://server/src/services/queue.service.ts#L48-L122)
- [server/src/modules/book-generator/book-queue.processor.ts:48-83](file://server/src/modules/book-generator/book-queue.processor.ts#L48-L83)
章节来源
- [server/src/app.ts:57-130](file://server/src/app.ts#L57-L130)
## 核心组件
- REST API 层：以 Koa Router 注册各模块路由，统一处理 CORS、BodyParser、静态资源、健康检查与指标暴露。
- 中间件管道：错误处理、性能监控、日志、安全（XSS/SQL 注入）、速率限制、认证与可选认证。
- 异步队列：Bull 队列承载音频/视频/书籍生成等长耗时任务，具备 Redis 回退与并发控制。
- 实时通信：WebSocket 服务在 /ws 路径上建立连接，向客户端推送生成完成与进度事件。
- 前端 WebSocket 管理器：封装连接、订阅、重连与事件派发，适配 H5/小程序。
章节来源
- [server/src/app.ts:63-130](file://server/src/app.ts#L63-L130)
- [server/src/middleware/security.ts:6-27](file://server/src/middleware/security.ts#L6-L27)
- [server/src/middleware/rate-limiter.ts:49-72](file://server/src/middleware/rate-limiter.ts#L49-L72)
- [server/src/middleware/auth.ts:7-49](file://server/src/middleware/auth.ts#L7-L49)
- [server/src/services/queue.service.ts:48-122](file://server/src/services/queue.service.ts#L48-L122)
- [server/src/services/websocket.service.ts:102-133](file://server/src/services/websocket.service.ts#L102-L133)
- [my-uniapp-vue3/src/utils/websocket.ts:15-196](file://my-uniapp-vue3/src/utils/websocket.ts#L15-L196)
## 架构总览
下图展示三类通信模式在系统中的应用位置与数据流向：
```mermaid
graph TB
C["客户端/浏览器"] --> |REST API| R["Koa 路由"]
R --> M1["安全中间件
XSS/SQL注入"]
R --> M2["速率限制中间件"]
R --> M3["认证中间件"]
R --> S["业务控制器
如 tts.auth.book-generator"]
S --> |异步任务| Q["队列服务(Bull)"]
Q --> P["队列处理器
并发执行"]
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](file://server/src/app.ts#L63-L130)
- [server/src/middleware/security.ts:6-27](file://server/src/middleware/security.ts#L6-L27)
- [server/src/middleware/rate-limiter.ts:49-72](file://server/src/middleware/rate-limiter.ts#L49-L72)
- [server/src/middleware/auth.ts:7-49](file://server/src/middleware/auth.ts#L7-L49)
- [server/src/services/queue.service.ts:48-122](file://server/src/services/queue.service.ts#L48-L122)
- [server/src/services/websocket.service.ts:102-133](file://server/src/services/websocket.service.ts#L102-L133)
## 详细组件分析
### 同步通信（RESTful API）
- 设计要点
- 统一使用 Koa Router 注册模块路由，集中处理 CORS、BodyParser、静态资源与健康检查。
- 控制器内进行参数校验、权限检查与配额校验，必要时调用订阅服务与数据库。
- 对外返回统一结构，便于前端消费。
- 典型流程（TTS 生成）
- 客户端发起 POST /api/tts/generate，携带文本、音色、可选书籍章节信息。
- 控制器执行 optionalAuth（可选认证）、参数校验、配额检查、调用服务生成异步任务。
- 立即返回任务创建结果，后续通过 WebSocket 推送状态。
- 安全与限流
- 安全中间件对请求体与查询参数进行 XSS/SQL 注入清洗，并设置安全响应头。
- 速率限制中间件按接口维度（API、登录、短信、TTS、上传）配置不同阈值。
- 认证中间件支持强制认证与可选认证两种模式，开发环境可跳过。
```mermaid
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](file://server/src/modules/tts/tts.controller.ts#L52-L127)
- [server/src/middleware/auth.ts:7-49](file://server/src/middleware/auth.ts#L7-L49)
- [server/src/middleware/rate-limiter.ts:49-72](file://server/src/middleware/rate-limiter.ts#L49-L72)
- [server/src/middleware/security.ts:6-27](file://server/src/middleware/security.ts#L6-L27)
- [server/src/services/queue.service.ts:131-160](file://server/src/services/queue.service.ts#L131-L160)
- [server/src/services/websocket.service.ts:66-86](file://server/src/services/websocket.service.ts#L66-L86)
章节来源
- [server/src/modules/tts/tts.controller.ts:52-127](file://server/src/modules/tts/tts.controller.ts#L52-L127)
- [server/src/middleware/auth.ts:7-49](file://server/src/middleware/auth.ts#L7-L49)
- [server/src/middleware/rate-limiter.ts:49-72](file://server/src/middleware/rate-limiter.ts#L49-L72)
- [server/src/middleware/security.ts:6-27](file://server/src/middleware/security.ts#L6-L27)
### 异步通信（消息队列/Bull）
- 设计原则
- 队列仅负责排队与并发控制，失败重试、超时管理与业务逻辑分别由容错层、AI 服务层与领域层承担。
- 优先使用 Redis 队列，若不可用则回退至内存队列，保证系统可用性。
- 关键能力
- 任务类型：音频生成、视频生成、书籍生成、邮件发送等。
- 任务状态：waiting/active/completed/failed/delayed。
- 进度回调：支持任务进度上报与回调触发。
- 统计与运维：提供队列统计、暂停/恢复、清空、优雅关闭等操作。
- 书籍生成处理器
- 初始化时优先使用 Redis 队列，最大并发 3；若 Redis 不可用则使用内存队列。
- 启动时扫描数据库中处于生成中的书籍，恢复中断任务并重新入队。
```mermaid
flowchart TD
Start(["提交任务"]) --> Add["入队(Redis/内存)"]
Add --> Consume{"Redis可用?"}
Consume --> |是| RedisProc["Redis队列处理器
并发执行"]
Consume --> |否| MemProc["内存队列处理器
并发执行"]
RedisProc --> Domain["领域服务/LLM生成"]
MemProc --> Domain
Domain --> Done{"完成?"}
Done --> |是| Push["推送完成事件"]
Done --> |否| Fail["标记失败/记录错误"]
Push --> End(["结束"])
Fail --> End
```
图表来源
- [server/src/services/queue.service.ts:48-122](file://server/src/services/queue.service.ts#L48-L122)
- [server/src/services/memory-queue.ts:17-99](file://server/src/services/memory-queue.ts#L17-L99)
- [server/src/modules/book-generator/book-queue.processor.ts:48-83](file://server/src/modules/book-generator/book-queue.processor.ts#L48-L83)
章节来源
- [server/src/services/queue.service.ts:48-122](file://server/src/services/queue.service.ts#L48-L122)
- [server/src/services/memory-queue.ts:17-99](file://server/src/services/memory-queue.ts#L17-L99)
- [server/src/modules/book-generator/book-queue.processor.ts:48-83](file://server/src/modules/book-generator/book-queue.processor.ts#L48-L83)
### 实时通信（WebSocket 双向通信）
- 服务端
- 在 HTTP 服务器上监听 upgrade，仅接受 /ws 路径，从查询参数提取 clientId 并维护连接映射。
- 提供客户端管理（添加/移除）、广播与定向推送，支持音频/视频生成完成与批量进度事件。
- 前端
- WebSocketManager 封装连接、订阅、重连与事件派发；支持 H5 与小程序。
- 自动重连（最多 3 次，间隔 3s），重连成功后自动重新订阅事件。
- 典型流程
- 客户端连接 /ws，接收 connected 事件。
- 服务端在书籍/音频/视频生成完成后，广播对应事件，前端按 bookId 过滤并更新 UI。
```mermaid
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](file://server/src/services/websocket.service.ts#L102-L133)
- [my-uniapp-vue3/src/utils/websocket.ts:25-82](file://my-uniapp-vue3/src/utils/websocket.ts#L25-L82)
- [server/src/services/websocket.service.ts:66-86](file://server/src/services/websocket.service.ts#L66-L86)
章节来源
- [server/src/services/websocket.service.ts:102-133](file://server/src/services/websocket.service.ts#L102-L133)
- [my-uniapp-vue3/src/utils/websocket.ts:25-82](file://my-uniapp-vue3/src/utils/websocket.ts#L25-L82)
### 中间件管道设计模式
- 请求预处理
- CORS、BodyParser、静态资源、健康检查与指标暴露。
- 身份验证
- 强制认证：要求 Bearer Token，开发环境可通过开关跳过。
- 可选认证：无 Token 时自动降级为测试用户，便于调试。
- 权限检查
- 控制器内结合用户上下文与订阅配额进行权限判断。
- 响应后处理
- 敏感数据脱敏（密码、token 等）与统一响应结构。
- 安全加固
- XSS/SQL 注入检测与清洗，设置安全响应头。
- 速率限制
- 多维度限流策略，避免滥用与攻击。
```mermaid
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](file://server/src/app.ts#L63-L83)
- [server/src/middleware/security.ts:6-27](file://server/src/middleware/security.ts#L6-L27)
- [server/src/middleware/rate-limiter.ts:49-72](file://server/src/middleware/rate-limiter.ts#L49-L72)
- [server/src/middleware/auth.ts:7-49](file://server/src/middleware/auth.ts#L7-L49)
章节来源
- [server/src/app.ts:63-83](file://server/src/app.ts#L63-L83)
- [server/src/middleware/security.ts:6-27](file://server/src/middleware/security.ts#L6-L27)
- [server/src/middleware/rate-limiter.ts:49-72](file://server/src/middleware/rate-limiter.ts#L49-L72)
- [server/src/middleware/auth.ts:7-49](file://server/src/middleware/auth.ts#L7-L49)
### 事件驱动架构与错误重试
- 事件发布订阅
- 书籍生成完成后，通过 WebSocket 广播事件；前端按需订阅。
- 消息路由
- 队列服务负责任务路由与并发调度；处理器根据任务类型路由到相应领域服务。
- 错误重试与恢复
- 队列层不负责失败重试，重试策略由容错层承担；超时与业务异常由 LLM/领域服务处理。
- 服务器启动时扫描数据库中处于生成中的书籍，自动恢复中断任务并重新入队。
```mermaid
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](file://server/src/modules/book-generator/book-queue.processor.ts#L88-L124)
- [server/src/services/queue.service.ts:131-160](file://server/src/services/queue.service.ts#L131-L160)
章节来源
- [server/src/modules/book-generator/book-queue.processor.ts:88-124](file://server/src/modules/book-generator/book-queue.processor.ts#L88-L124)
- [server/src/services/queue.service.ts:131-160](file://server/src/services/queue.service.ts#L131-L160)
## 依赖关系分析
- 应用层依赖
- 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 与配置。
```mermaid
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](file://server/src/app.ts#L133-L172)
- [server/src/services/websocket.service.ts:102-133](file://server/src/services/websocket.service.ts#L102-L133)
- [server/src/services/queue.service.ts:48-122](file://server/src/services/queue.service.ts#L48-L122)
- [server/src/modules/book-generator/book-queue.processor.ts:48-83](file://server/src/modules/book-generator/book-queue.processor.ts#L48-L83)
章节来源
- [server/src/app.ts:133-172](file://server/src/app.ts#L133-L172)
- [server/src/modules/book-generator/book-queue.processor.ts:48-83](file://server/src/modules/book-generator/book-queue.processor.ts#L48-L83)
## 性能考量
- 队列并发与超时
- 书籍生成任务最大并发 3，超时 2 小时；音频 5 分钟、视频 10 分钟，避免长时间占用资源。
- 限流策略
- 全局限流、登录限流、短信限流、TTS 限流、上传限流，按接口与用户维度精细化控制。
- 缓存与存储
- Redis 可用时优先使用；存储类型可切换（OSS/本地），启动时进行连通性检测。
- 前端重连与订阅
- WebSocketManager 自动重连与事件重订阅，降低弱网与断线影响。
章节来源
- [server/src/services/queue.service.ts:166-190](file://server/src/services/queue.service.ts#L166-L190)
- [server/src/middleware/rate-limiter.ts:77-120](file://server/src/middleware/rate-limiter.ts#L77-L120)
- [server/src/app.ts:142-151](file://server/src/app.ts#L142-L151)
- [my-uniapp-vue3/src/utils/websocket.ts:162-190](file://my-uniapp-vue3/src/utils/websocket.ts#L162-L190)
## 故障排查指南
- 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](file://server/src/services/websocket.service.ts#L102-L133)
- [server/src/services/queue.service.ts:53-59](file://server/src/services/queue.service.ts#L53-L59)
- [server/src/middleware/rate-limiter.ts:52-71](file://server/src/middleware/rate-limiter.ts#L52-L71)
- [server/src/middleware/security.ts:69-83](file://server/src/middleware/security.ts#L69-L83)
- [server/src/app.ts:174-187](file://server/src/app.ts#L174-L187)
## 结论
该平台通过“REST API + 队列 + WebSocket”的组合实现了高可用、可扩展的通信体系：同步 API 提供即时交互体验，异步队列承载长耗时任务并具备回退与恢复能力，实时 WebSocket 保障事件推送的及时性。配合完善的中间件管道（安全、限流、认证）与事件驱动架构，系统在安全性、性能与可靠性方面均具备良好基础。建议在生产环境中启用全局限流与认证开关，并持续监控队列与 WebSocket 的运行状态，以进一步提升稳定性与用户体验。