开发指南

本文引用的文件

README.md
API.md
app.ts
index.ts
errorHandler.ts
logger.service.ts
sentry.service.ts
queue.service.ts
storage.service.ts
tts.service.ts
book-generator.service.ts
main.ts
package.json
package.json

引言

本开发指南面向AI有声书生成平台的开发者与团队，提供统一的代码规范、开发流程、质量保障体系与协作实践。文档覆盖以下主题：

代码规范与最佳实践
开发流程与版本/分支管理
功能迭代策略与质量保证
代码评审、单元测试、集成测试与性能测试
新功能开发模板、Bug修复流程与文档更新规范
开发工具配置、调试技巧与性能分析方法

项目结构

项目采用前后端分离架构，后端基于Koa，前端基于uniapp+Vue3+TypeScript，数据库与存储通过配置化抽象支持本地与OSS两种模式。

graph TB
subgraph "前端(uniapp)"
FE_App["应用入口<br/>main.ts"]
FE_Packages["脚本与依赖<br/>package.json"]
end
subgraph "后端(Koa)"
BE_App["应用入口<br/>server/src/app.ts"]
BE_Config["配置中心<br/>server/src/config/index.ts"]
BE_MW_Error["错误处理中间件<br/>server/src/middleware/errorHandler.ts"]
BE_Services["服务层<br/>server/src/services/*"]
BE_Modules["业务模块<br/>server/src/modules/*"]
end
subgraph "文档与测试"
Docs_API["API文档<br/>docs/API.md"]
Repo_Readme["仓库说明<br/>README.md"]
end
FE_App --> BE_App
FE_Packages --> FE_App
BE_App --> BE_Config
BE_App --> BE_MW_Error
BE_App --> BE_Services
BE_App --> BE_Modules
Docs_API --> BE_Modules
Repo_Readme --> BE_App

图表来源

app.ts:1-194
index.ts:1-117
errorHandler.ts:1-67
logger.service.ts:1-114
API.md:1-499
README.md:1-168
main.ts:1-32
package.json:1-65

章节来源

README.md:1-168
API.md:1-499
app.ts:1-194
index.ts:1-117
main.ts:1-32
package.json:1-65

核心组件

应用入口与路由注册：后端通过Koa创建HTTP服务，集中注册认证、TTS、播放器、收藏、偏好、搜索、分类、评论、通知、BGM、音频编辑、书籍生成、播放列表、草稿、视频生成、签到、订阅、支付、发布、反馈等模块路由，并挂载静态资源与健康检查。
配置中心：集中管理端口、JWT、DashScope/TTS模型、上传目录与大小等配置，支持模型自动切换与默认模型选择。
中间件体系：统一错误处理、Sentry错误监控、性能监控、日志记录、CORS、安全防护（XSS/SQL注入）、速率限制等。
服务层：日志服务、Sentry服务、队列服务（Bull+Redis，降级至内存队列）、存储服务（OSS/本地无缝切换）、WebSocket服务等。
业务模块：TTS服务（多提供商、分段与合并、LRC歌词生成、AI摘要/标签）、书籍生成编排（LangGraph内容生成、音频/视频生成与合并、进度推送）、视频生成（FFmpeg封装）等。

章节来源

app.ts:1-194
index.ts:1-117
errorHandler.ts:1-67
logger.service.ts:1-114
sentry.service.ts:1-113
queue.service.ts:1-347
storage.service.ts:1-278
tts.service.ts:1-715
book-generator.service.ts:1-549

架构总览

下图展示后端核心组件交互与数据流：

graph TB
Client["客户端/前端"]
Koa["Koa 应用<br/>server/src/app.ts"]
Cfg["配置中心<br/>server/src/config/index.ts"]
MW_Err["错误处理中间件<br/>server/src/middleware/errorHandler.ts"]
Log["日志服务<br/>server/src/services/logger.service.ts"]
Sen["Sentry 服务<br/>server/src/services/sentry.service.ts"]
Q["队列服务<br/>server/src/services/queue.service.ts"]
Store["存储服务<br/>server/src/services/storage.service.ts"]
TTS["TTS 服务<br/>server/src/modules/tts/tts.service.ts"]
BG["书籍生成编排<br/>server/src/modules/book-generator/book-generator.service.ts"]
Client --> Koa
Koa --> MW_Err
Koa --> Log
Koa --> Sen
Koa --> Cfg
Koa --> TTS
Koa --> BG
TTS --> Q
TTS --> Store
BG --> Q
BG --> Store

图表来源

app.ts:1-194
index.ts:1-117
errorHandler.ts:1-67
logger.service.ts:1-114
sentry.service.ts:1-113
queue.service.ts:1-347
storage.service.ts:1-278
tts.service.ts:1-715
book-generator.service.ts:1-549

详细组件分析

TTS 服务（文本转音频）

多提供商支持：阿里云百炼、MiniMax、Mock，具备自动切换与降级能力。
文本分段与合并：针对不同提供商特性进行分段与并发生成，最后统一合并输出。
LRC歌词生成：基于文本与时长生成时间轴歌词。
AI摘要/标签：异步生成标题、摘要与标签，提升内容可发现性。

存储与回退：优先上传OSS，失败时回退到本地存储；支持云端URL下载后上传OSS。

sequenceDiagram
participant C as "客户端"
participant T as "TTS服务<br/>tts.service.ts"
participant P as "TTS提供商"
participant M as "音频合并器"
participant S as "存储服务<br/>storage.service.ts"
C->>T : "提交文本与参数"
T->>P : "分段并行合成"
P-->>T : "返回音频片段"
T->>M : "合并片段"
M-->>T : "输出MP3"
T->>S : "上传到OSS或本地"
S-->>T : "返回访问URL"
T-->>C : "返回音频ID/URL/时长"

图表来源

tts.service.ts:1-715
storage.service.ts:1-278

章节来源

tts.service.ts:1-715
storage.service.ts:1-278

书籍生成编排（批量内容/音频/视频生成）

步骤编排：内容生成（LangGraph）、音频生成、音频合并、视频生成、视频合并。
进度推送：通过WebSocket向客户端推送实时进度。
取消机制：支持任务取消标志，避免浪费资源。

超时与轮询：对长耗时步骤采用轮询检查与最大等待时间控制。

flowchart TD
Start(["开始"]) --> Init["加载书籍信息"]
Init --> Step1["内容生成<br/>LangGraph"]
Step1 --> Step2["音频生成<br/>并发分段合成"]
Step2 --> MergeA["音频合并<br/>按父章节聚合"]
MergeA --> Step3["视频生成<br/>创建项目并生成"]
Step3 --> MergeV["视频合并<br/>简化处理"]
MergeV --> Done(["完成"])
Step1 --> |失败| Fail["返回失败并记录错误"]
Step2 --> |失败| Fail
Step3 --> |失败| Fail
MergeA --> |失败| Fail
MergeV --> |失败| Fail

图表来源

book-generator.service.ts:1-549

章节来源

book-generator.service.ts:1-549

队列服务（任务调度与并发控制）

职责边界：仅负责排队与并发控制，失败重试与超时由容错层与AI服务层处理。
降级策略：Redis不可用时自动降级到内存队列，保证基本可用。

超时与统计：为不同类型任务设置合理超时，提供队列统计与暂停/恢复能力。

classDiagram
class QueueService {
+addTask(queueType, data, options) Promise<string|null>
+addAudioGenerationTask(data) Promise<string|null>
+addVideoGenerationTask(data) Promise<string|null>
+addBookGenerationTask(data) Promise<string|null>
+getTaskStatus(queueType, jobId) Promise<status>
+updateProgress(queueType, jobId, progress, data) Promise<void>
+getQueueStats(queueType) Promise<counts>
+pauseQueue(queueType) Promise<void>
+resumeQueue(queueType) Promise<void>
+clearQueue(queueType) Promise<void>
+closeAll() Promise<void>
}

图表来源

queue.service.ts:1-347

章节来源

queue.service.ts:1-347

存储服务（OSS/本地无缝切换）

统一接口：提供音频、视频、封面与通用文件的上传/下载/删除/签名URL能力。
环境切换：通过环境变量在OSS与本地存储之间切换。

本地测试：提供连接测试与目录写入测试，便于开发环境自检。

classDiagram
class StorageService {
+setStorageType(type) void
+getStorageType() StorageType
+uploadAudio(localPath, audioId) Promise<string>
+uploadVideo(localPath, videoId) Promise<string>
+uploadCover(localPath, bookId) Promise<string>
+uploadFile(localPath, category, id) Promise<string>
+uploadBuffer(buffer, objectKey, contentType) Promise<string>
+deleteFile(url) Promise<void>
+deleteDirectory(prefix, id) Promise<void>
+downloadFile(url) Promise<Buffer>
+getSignedUrl(url, expires) Promise<string>
+testConnection() Promise<boolean>
}

图表来源

storage.service.ts:1-278

章节来源

storage.service.ts:1-278

日志与错误监控

统一日志：Winston输出到控制台与文件，区分错误与HTTP请求日志。
错误处理：统一错误响应格式，开发环境返回堆栈，生产环境隐藏细节。

错误监控：Sentry初始化与错误捕获，支持用户上下文与标签设置。

sequenceDiagram
participant MW as "错误处理中间件"
participant LOG as "日志服务"
participant SEN as "Sentry服务"
MW->>LOG : "记录错误与请求信息"
MW->>SEN : "捕获异常并上报"
MW-->>MW : "返回统一错误响应"

图表来源

errorHandler.ts:1-67
logger.service.ts:1-114
sentry.service.ts:1-113

章节来源

errorHandler.ts:1-67
logger.service.ts:1-114
sentry.service.ts:1-113

依赖关系分析

组件耦合：服务层（日志、Sentry、队列、存储）被业务模块广泛依赖，形成清晰的基础设施层。
外部依赖：Redis（队列）、OSS（对象存储）、FFmpeg（视频处理）、阿里云/MiniMax（TTS）。

循环依赖：未见明显循环依赖，模块间通过服务接口解耦。

graph LR
TTS["TTS服务"] --> Q["队列服务"]
TTS --> Store["存储服务"]
BG["书籍生成编排"] --> Q
BG --> Store
App["应用入口"] --> MW["中间件"]
App --> Log["日志服务"]
App --> Sen["Sentry服务"]
App --> Cfg["配置中心"]

图表来源

app.ts:1-194
queue.service.ts:1-347
storage.service.ts:1-278
tts.service.ts:1-715
book-generator.service.ts:1-549
logger.service.ts:1-114
sentry.service.ts:1-113
index.ts:1-117

章节来源

app.ts:1-194
queue.service.ts:1-347
storage.service.ts:1-278
tts.service.ts:1-715
book-generator.service.ts:1-549
logger.service.ts:1-114
sentry.service.ts:1-113
index.ts:1-117

性能考虑

并发与限流：TTS分段并发控制，队列为不同类型任务设置超时；全局限流中间件可按需启用。
存储与网络：优先OSS上传，失败回退本地；云端URL下载后统一上传OSS，减少跨域与带宽波动影响。
日志与监控：Winston结构化日志，Sentry性能采样与错误过滤，结合HTTP请求日志定位瓶颈。
前端调试：H5环境可选vConsole，生产环境保持精简。

章节来源

tts.service.ts:1-715
queue.service.ts:1-347
logger.service.ts:1-114
sentry.service.ts:1-113
main.ts:1-32

故障排查指南

常见错误与处理
- 401/403/404：检查认证与资源存在性，查看统一错误响应。
- 429：额度/限流，等待或切换提供商；查看模型自动切换逻辑。
- 500：查看Sentry错误与Winston错误日志，定位具体模块。
存储问题
- OSS连接失败：检查AK/SK与Bucket配置；切换STORAGE_TYPE为local进行本地验证。
队列问题
- Redis不可用：确认Redis服务；队列会自动降级到内存队列；关注队列统计与暂停/恢复。
TTS生成异常
- 分段失败：检查文本清理与分段策略；确认提供商可用性与API Key。
- 合并失败：检查音频文件完整性与时长计算；确认存储上传成功。
健康检查
- 访问 /health 与 /api/metrics，确认服务与指标正常。

章节来源

errorHandler.ts:1-67
sentry.service.ts:1-113
logger.service.ts:1-114
storage.service.ts:1-278
queue.service.ts:1-347
tts.service.ts:1-715
app.ts:1-194

结论

本指南提供了从架构、组件到流程与质量保障的完整开发参考。建议团队在日常开发中严格遵循统一的代码规范与评审流程，结合完善的日志与监控体系，持续优化TTS与生成链路的性能与稳定性。

附录

代码规范与最佳实践

命名规范：模块/服务/控制器/类型使用清晰语义，避免缩写。
错误处理：统一使用AppError及其子类，明确状态码与业务含义。
日志规范：区分info/warn/error/debug/http，避免敏感信息泄露。
配置管理：通过config集中管理，支持环境变量与模型配置文件。
存储策略：优先OSS，提供本地回退；上传前校验与失败回退。

章节来源

errorHandler.ts:1-67
logger.service.ts:1-114
index.ts:1-117
storage.service.ts:1-278

开发流程与版本/分支管理

版本策略：采用语义化版本，主干稳定发布，hotfix紧急修复。
分支模型：主分支(main)用于稳定发布，开发分支(dev)，功能分支(feature-)，修复分支(hotfix-)。
提交规范：使用约定式提交，如 feat/fix/docs/chore等前缀。
合并与审核：Pull Request必须通过代码评审与自动化测试。

章节来源

README.md:1-168

功能迭代策略与质量保证

迭代节奏：两周冲刺，优先交付MVP核心能力，逐步完善TTS、播放器、历史与会员体系。
质量门禁：单元测试覆盖率不低于80%，集成测试覆盖关键流程，性能测试评估TTS与生成链路。
回归测试：每次发布前执行全链路回归，重点关注存储切换与队列降级场景。

章节来源

README.md:145-168

代码评审流程

评审清单：需求一致性、边界条件、错误处理、日志与监控、性能与资源占用、安全与权限。
工具与标准：使用PR模板与检查清单，强制通过自动化检查后再合并。

章节来源

API.md:1-499

单元测试、集成测试与性能测试

单元测试：覆盖核心算法（文本分段、LRC生成、队列状态查询）。
集成测试：覆盖TTS生成端到端流程、书籍生成编排、存储上传与下载。
性能测试：评估不同并发下的TTS吞吐、队列延迟与视频生成时延。

章节来源

tts.service.ts:1-715
book-generator.service.ts:1-549
queue.service.ts:1-347
storage.service.ts:1-278

新功能开发模板

需求评审：明确API契约、数据模型与边界条件。
设计文档：接口定义、流程图、错误码与返回格式。
开发实现：遵循模块化与服务化，新增控制器/服务/中间件（如需）。
测试用例：单元测试与集成测试，覆盖正常/异常/边界场景。
文档更新：API文档同步更新，README补充使用说明。

章节来源

API.md:1-499
README.md:1-168

Bug修复流程

重现与定位：使用Sentry与日志快速定位问题；必要时开启vConsole。
修复与验证：最小改动修复，补充测试用例；回归验证。
发布与观察：热修复分支合并主干，观察监控与告警。

章节来源

sentry.service.ts:1-113
logger.service.ts:1-114
main.ts:1-32

文档更新规范

API文档：接口变更需同步更新API.md，保持请求/响应与错误码一致。
README：新增功能或重大变更需更新README与开发计划。

章节来源

API.md:1-499
README.md:1-168

开发工具配置与调试技巧

前端
- H5开发：使用uni的H5脚本，按需启用vConsole。
- 多端构建：通过脚本统一管理H5与小程序构建。
后端
- 环境变量：复制.env.example并按需配置数据库、JWT、TTS与Sentry。
- 调试：结合Winston日志与Sentry错误追踪，必要时开启性能采样。
性能分析
- 使用Sentry Profiling与HTTP请求日志定位热点。
- 队列与存储：关注Redis可用性与OSS连接状态。

章节来源

main.ts:1-32
package.json:1-65
index.ts:1-117
logger.service.ts:1-114
sentry.service.ts:1-113

开发指南.md 21 KB Permanentný odkaz História Raw

开发指南

目录

引言

项目结构

核心组件

架构总览

详细组件分析

TTS 服务（文本转音频）

书籍生成编排（批量内容/音频/视频生成）

队列服务（任务调度与并发控制）

存储服务（OSS/本地无缝切换）

日志与错误监控

依赖关系分析

性能考虑

故障排查指南

结论

附录

代码规范与最佳实践

开发流程与版本/分支管理

功能迭代策略与质量保证

代码评审流程

单元测试、集成测试与性能测试

新功能开发模板

Bug修复流程

文档更新规范

开发工具配置与调试技巧

开发指南.md 21 KB

Permanentný odkaz História Raw