添加字幕接口
目录
简介
添加字幕接口：说明该接口在草稿自动化里的用途、依赖模块与常见报错。具体方法、路径、字段和校验请以 OpenAPI 为准。
依赖关系分析
核心依赖关系
graph TB
subgraph "外部依赖"
FastAPI[FastAPI框架]
Pydantic[数据验证]
Logger[日志记录]
end
subgraph "内部模块"
Router[路由模块]
Service[服务模块]
Schema[模式模块]
Utils[工具模块]
end
subgraph "核心引擎"
PyJianYing[剪映草稿引擎]
DraftCache[草稿缓存]
Exceptions[异常处理]
end
FastAPI --> Router
Pydantic --> Schema
Logger --> Service
Router --> Service
Service --> PyJianYing
Service --> DraftCache
Service --> Exceptions
Schema --> Service
Utils --> Service
模块间交互
系统采用松耦合的设计，各模块间通过清晰的接口进行交互：
sequenceDiagram
participant API as "API调用者"
participant Router as "路由层"
participant Service as "服务层"
participant Engine as "引擎层"
participant Cache as "缓存层"
API->>Router : 发送请求
Router->>Service : 参数验证和转换
Service->>Cache : 获取资源
Cache-->>Service : 返回资源
Service->>Engine : 执行业务逻辑
Engine-->>Service : 返回结果
Service-->>Router : 处理结果
Router-->>API : 返回响应
性能考虑
性能优化策略
- 缓存机制：使用草稿缓存减少重复加载开销
- 批量处理：支持批量字幕添加，减少API调用次数
- 异步处理：对于大型字幕文件采用异步处理方式
- 内存管理：及时释放不再使用的草稿实例
性能监控指标
| 指标类型 | 目标值 | 监控方法 |
|---|---|---|
| 响应时间 | < 2 秒 | API响应时间监控 |
| 并发处理 | 支持 10+ 请求 | 并发测试 |
| 内存使用 | < 100MB | 内存监控 |
| CPU使用率 | < 80% | 性能分析 |
故障排除指南
常见问题及解决方案
草稿相关问题
问题：INVALID_DRAFT_URL 错误
原因：草稿URL无效或草稿不存在
解决方案：
- 验证草稿URL格式是否正确
- 确认草稿ID是否存在于系统中
- 检查草稿是否已被删除或过期
字幕数据问题
问题：INVALID_CAPTION_INFO 错误
原因：字幕数据格式不正确或缺少必填字段
解决方案：
- 验证JSON格式是否正确
- 检查必填字段是否完整
- 确认时间参数的合理性
样式设置问题
问题：样式设置不生效
原因：颜色格式不正确或参数范围超出限制
解决方案：
- 确认颜色值使用十六进制格式
- 验证参数范围是否在允许范围内
- 检查字体是否被系统支持
调试技巧
- 启用详细日志：查看详细的请求和响应日志
- 参数验证：使用OpenAPI规范验证请求参数
- 分步调试：逐步执行字幕添加流程定位问题
- 单元测试：运行测试用例验证功能正常
更多信息
字段说明、校验规则与示例以 OpenAPI 为准；需要对照源码时请查看 schemas/、service/ 与路由注册处。
