代码结构说明
目录
简介
本项目为 CapCut Mate（剪映助手）的后端与桌面客户端一体化方案，采用“Python 后端 + Electron 前端”的混合架构。后端基于 FastAPI 提供 RESTful API，前端基于 Electron + React 构建桌面应用，二者通过 IPC（跨进程通信）进行协作。整体遵循分层架构：Router → Service → Controller → Utils，同时在前端采用 Electron 的主进程与渲染进程分离设计，通过预加载脚本暴露受控 API。
项目结构
项目采用模块化分层组织：
- 根目录：后端入口、配置、Docker 支持、测试与文档
- src：后端核心代码，包含路由、服务、中间件、工具与剪映草稿模型
- desktop-client：Electron 桌面应用，包含主进程、预加载脚本、React 前端与 Node API
- template：剪映草稿模板资源
- tests：后端接口与业务逻辑测试
- docs：功能使用文档
graph TB
subgraph "后端(Python)"
A_main["main.py<br/>FastAPI 应用入口"]
A_router["src/router/v1.py<br/>路由层"]
A_service["src/service/*<br/>服务层"]
A_middlewares["src/middlewares/*<br/>中间件"]
A_config["config.py<br/>全局配置"]
end
subgraph "桌面客户端(Electron)"
E_main["desktop-client/main.js<br/>主进程"]
E_preload["desktop-client/preload.js<br/>预加载脚本"]
E_ipc["desktop-client/nodeapi/ipcHandlers.js<br/>IPC 处理"]
E_ui["desktop-client/web/src/*<br/>React 前端"]
end
A_main --> A_router
A_router --> A_service
A_main --> A_middlewares
A_main --> A_config
E_main --> E_preload
E_main --> E_ipc
E_ui --> E_preload
E_ui --> E_ipc
核心组件
- 后端入口与路由
- FastAPI 应用在入口文件中创建，注册路由与中间件，启动服务
- 路由层集中定义 v1 版本的所有 API，每个路由对应一个服务方法
- 中间件
- 准备中间件：确保草稿与临时目录存在
- 统一响应中间件：标准化成功/失败响应与异常处理
- 服务层
- 聚合业务逻辑，封装对剪映草稿模型与工具的调用
- 示例：创建草稿、添加媒体、生成时间线、导出视频等
- 配置
- 定义项目根目录、草稿目录、下载 URL、模板路径、云存储参数等
- 桌面客户端
- 主进程负责窗口生命周期与 IPC 注册
- 预加载脚本通过 contextBridge 暴露受控 API
- React 页面通过 electronService 统一封装 IPC 调用
架构总览
后端采用经典的 MVC 分层：
- Router 层：接收请求，校验参数，调用服务层
- Service 层：封装业务规则与外部交互
- Utils 层：通用工具（日志、下载、缓存、媒体处理等）
前端采用 Electron 分层：
- 主进程：管理窗口、注册 IPC、调用 Node API
- 预加载脚本：通过 contextBridge 暴露受控 API
- 渲染进程：React 页面，调用 electronService 进行 IPC
graph TB
subgraph "后端"
R["Router(v1)"] --> S["Service"]
S --> U["Utils"]
M1["PrepareMiddleware"] --> R
M2["ResponseMiddleware"] --> R
end
subgraph "前端"
MP["Main Process"] --> PL["Preload Bridge"]
UI["React Pages"] --> ES["electronService"]
ES --> PL
PL --> MP
end
R <--> MP
详细组件分析
后端入口与路由
- 入口文件创建 FastAPI 应用，注册 v1 路由与中间件，打印路由表，启动服务
- 路由层集中定义草稿创建、保存、媒体添加、特效与字幕、时间线生成、导出视频等接口
- 每个路由函数只做参数透传与响应包装，核心逻辑在服务层
sequenceDiagram
participant C as "客户端"
participant F as "FastAPI 应用"
participant R as "Router(v1)"
participant S as "Service"
participant U as "Utils"
C->>F : "HTTP 请求"
F->>R : "路由分发"
R->>S : "调用业务方法"
S->>U : "执行工具/IO 操作"
U-->>S : "结果/异常"
S-->>R : "业务结果"
R-->>F : "响应模型"
F-->>C : "统一响应"
中间件体系
- 准备中间件：在请求进入前确保草稿与临时目录存在
- 统一响应中间件：处理非 200 响应、JSON 格式化、参数校验错误、自定义异常与通用异常
flowchart TD
Start(["请求进入"]) --> Prep["准备中间件<br/>创建目录"]
Prep --> Router["路由处理"]
Router --> Resp["响应中间件"]
Resp --> Status{"状态码=200?"}
Status --> |否| Non200["处理非200/422错误"]
Status --> |是| JsonFmt["JSON 格式化<br/>统一响应结构"]
Non200 --> End(["返回"])
JsonFmt --> End
服务层与业务流程
- 服务层聚合业务逻辑，示例：创建草稿（复制模板、修改画布尺寸、添加主轨道、缓存并返回 URL）
- 服务层与工具层解耦，便于单元测试与复用
flowchart TD
SStart(["服务入口"]) --> CopyTpl["复制模板到草稿目录"]
CopyTpl --> LoadTpl["加载草稿模板"]
LoadTpl --> ModifyCanvas["修改画布宽高"]
ModifyCanvas --> AddTrack["添加主轨道"]
AddTrack --> SaveDraft["保存草稿"]
SaveDraft --> Cache["更新缓存"]
Cache --> SEnd(["返回草稿URL"])
前端架构与 IPC 通信
- 主进程负责窗口创建、开发/生产模式加载、IPC 注册
- 预加载脚本通过 contextBridge 暴露受控 API（如保存文件、获取日志、打开外部链接等）
- electronService 在渲染进程中封装 IPC 调用，支持浏览器环境下的模拟实现
- 下载页与配置页分别演示了 IPC 的典型使用场景
sequenceDiagram
participant UI as "React 页面"
participant ES as "electronService"
participant PL as "Preload Bridge"
participant MP as "Main Process"
participant DL as "Node API(download)"
UI->>ES : "saveFile(options)"
ES->>PL : "ipcRenderer.invoke('save-file', options)"
PL->>MP : "ipcMain.handle('save-file')"
MP->>DL : "downloadFiles(...)"
DL-->>MP : "完成/异常"
MP-->>PL : "结果"
PL-->>ES : "结果"
ES-->>UI : "Promise 解析"
配置与模板
- 配置文件集中管理路径、URL、云存储参数与模板目录
- 模板目录包含默认草稿模板，服务层在创建草稿时复制并修改
依赖关系分析
- 后端内部依赖
- main.py 依赖 router、middlewares、utils、pyJianYingDraft 控制器
- router 依赖 service 与 schemas
- service 通过 utils 与模型库完成业务
- 前端内部依赖
- 主进程依赖 IPC 处理模块与日志模块
- 预加载脚本依赖 IPC 处理模块
- React 页面依赖 electronService 与组件库
graph LR
main_py["main.py"] --> router_v1["src/router/v1.py"]
router_v1 --> service_init["src/service/__init__.py"]
main_py --> middlewares_prepare["src/middlewares/prepare.py"]
main_py --> middlewares_response["src/middlewares/response.py"]
main_js["desktop-client/main.js"] --> preload_js["desktop-client/preload.js"]
main_js --> ipc_handlers["desktop-client/nodeapi/ipcHandlers.js"]
preload_js --> electron_service["desktop-client/web/src/services/electronService.js"]
electron_service --> download_page["desktop-client/web/src/pages/Download/index.jsx"]
性能考量
- 后端
- 中间件顺序：准备中间件在前，统一响应中间件在后，避免重复处理
- IO 优化：草稿与临时目录提前创建，减少运行时阻塞
- 日志与异常：统一异常处理降低错误传播成本
- 前端
- IPC 调用异步化，避免阻塞 UI
- 预加载脚本限制 API 暴露范围，提升安全性与可控性
- 浏览器环境模拟实现保证在非 Electron 环境可用性
故障排查指南
- 后端常见问题
- 参数校验失败：统一响应中间件会将 422 错误格式化为标准响应
- 自定义异常：抛出自定义异常时，统一响应中间件返回带 code/message 的结构
- 通用异常：捕获后转换为内部错误响应
- 前端常见问题
- IPC 未注册：确认主进程已调用 setupIpcHandlers
- 权限错误：主进程对未捕获异常进行记录并在 macOS 上弹窗提示
- 浏览器环境：electronService 在浏览器环境使用模拟实现，部分功能不可用
结论
本项目通过清晰的分层架构与前后端分离设计，实现了剪映草稿的自动化处理与桌面应用的便捷使用。后端以 FastAPI 为核心，路由与服务解耦，中间件统一处理；前端以 Electron 为基础，通过预加载脚本与 IPC 实现安全可控的原生能力调用。整体结构易于扩展与维护，适合进一步完善模板系统、增强云渲染能力与完善测试覆盖。
附录
- 代码导航建议
- 后端新增接口：在 router/v1.py 新增路由，编写对应服务方法，必要时扩展 schemas
- 业务逻辑变更：集中在 service/* 下修改，保持路由与中间件稳定
- 前端新增页面：在 web/src/pages 下创建组件，通过 electronService 调用 IPC
- 配置项变更：在 config.py 中集中管理，避免硬编码
