143 lines
5.1 KiB
Markdown
143 lines
5.1 KiB
Markdown
## 00 - 开发前后端格式
|
||
|
||
### 1. 项目概述
|
||
|
||
**MangTool** 是一个基于 **Java Spring Boot + Vue 3** 的个人开发工具箱，专注于音乐库管理和日志处理两大核心模块，特点是：**开箱即用、模块化扩展、安全可靠**。
|
||
|
||
- **后端技术栈**：Spring Boot、WebSocket、异步任务、文件处理引擎（FFmpeg、Jaudiotagger、SVNKit 等）
|
||
- **前端技术栈**：Vue 3、Vite、Element Plus、组合式 API、基于组件的单页应用
|
||
|
||
### 1.1 开发环境版本
|
||
|
||
- **Node.js**：v20.19.5
|
||
- **npm**：10.8.2
|
||
- **Java**：1.8.0_472（OpenJDK 64-Bit Server VM）
|
||
- **Maven**：Apache Maven 3.8.7
|
||
|
||
### 2. 前后端整体架构
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "前端 (Vue 3)"
|
||
A[前端组件] --> B[API 封装层]
|
||
B --> C[WebSocket 客户端]
|
||
end
|
||
|
||
subgraph "后端 (Spring Boot)"
|
||
D[REST 控制器] --> E[业务服务层]
|
||
E --> F[文件处理引擎]
|
||
E --> G[WebSocket 服务]
|
||
F --> H[FFmpeg 集成]
|
||
F --> I[Jaudiotagger]
|
||
F --> J[SVNKit]
|
||
end
|
||
|
||
C -- WebSocket 实时进度 --> G
|
||
B -- HTTP REST API --> D
|
||
F --> K[本地文件系统]
|
||
```
|
||
|
||
- **HTTP API**：前端通过 axios 封装的请求模块调用后端 REST 接口
|
||
- **WebSocket**：用于长时间批处理任务的实时进度推送
|
||
- **文件系统访问**：所有音频、日志等文件操作都集中在后端完成，前端只处理路径和参数
|
||
|
||
### 3. 项目目录结构
|
||
|
||
```text
|
||
mangtool/
|
||
├── backend/ # Spring Boot 后端
|
||
│ ├── src/main/java/com/music/
|
||
│ │ ├── config/ # 配置类 (CORS, WebSocket, Async)
|
||
│ │ ├── controller/ # REST 控制器
|
||
│ │ ├── service/ # 业务服务层（核心逻辑）
|
||
│ │ ├── dto/ # 数据传输对象
|
||
│ │ ├── common/ # 通用工具 (Result, ErrorCode)
|
||
│ │ └── exception/ # 全局异常处理
|
||
│ └── pom.xml # Maven 依赖配置
|
||
├── frontend/ # Vue 3 前端
|
||
│ ├── src/
|
||
│ │ ├── components/ # 功能模块组件 (*Tab.vue)
|
||
│ │ ├── api/ # API 模块化封装
|
||
│ │ ├── composables/ # 组合式函数 (useWebSocket)
|
||
│ │ └── App.vue # 主界面与导航
|
||
│ └── vite.config.js # Vite 配置
|
||
└── docker/ # 容器化部署配置
|
||
```
|
||
|
||
### 4. 统一后端返回格式
|
||
|
||
- **强制要求**：所有后端接口统一返回 `Result<T>`，禁止直接返回实体类或 `ResponseEntity`。
|
||
|
||
```java
|
||
public class Result<T> {
|
||
private int code; // 0=成功，非0=错误
|
||
private String message; // 提示信息
|
||
private T data; // 业务数据
|
||
}
|
||
```
|
||
|
||
- **全局异常处理**：通过 `GlobalExceptionHandler` 捕获 `BusinessException`，并转换为统一的 `Result` 响应
|
||
|
||
### 5. 前端 API 调用规范
|
||
|
||
- **模块划分**：`frontend/src/api/` 下按功能拆分：`aggregate.js`, `convert.js`, `dedup.js` 等
|
||
- **统一请求实例**：所有 API 模块都通过封装好的 axios 实例 `request` 发送请求
|
||
|
||
**响应拦截器约定**：
|
||
|
||
- 后端只返回 `Result<T>` 格式
|
||
- 前端拦截器自动判断 `code`：
|
||
- `code === 0`：直接返回 `data`
|
||
- 其他：弹出错误信息，并返回 `Promise.reject`
|
||
|
||
### 6. WebSocket 进度推送规范
|
||
|
||
**消息结构（ProgressMessage DTO）**：
|
||
|
||
```java
|
||
public class ProgressMessage {
|
||
private String taskId; // 任务 ID
|
||
private String type; // 任务类型
|
||
private int total; // 总数
|
||
private int processed; // 已处理
|
||
private int success; // 成功数
|
||
private int failed; // 失败数
|
||
private String currentFile; // 当前处理文件
|
||
private String message; // 进度消息
|
||
private boolean completed; // 是否完成
|
||
}
|
||
```
|
||
|
||
- **服务端**:通过 WebSocket 节流推送进度,避免频繁推送导致前端卡顿
|
||
- **前端**:统一封装 `useWebSocket` 组合式函数,在各个 Tab 组件中复用,用于展示进度条 / 当前文件 / 完成状态
|
||
|
||
### 7. 测试用例需求
|
||
|
||
#### 7.1 后端测试
|
||
|
||
**单元测试**:
|
||
- 测试统一返回格式 `Result<T>` 的构建与序列化
|
||
- 测试全局异常处理器对 `BusinessException` 的捕获与转换
|
||
- 测试 WebSocket 消息推送的节流机制
|
||
- 测试路径验证拦截器的安全规则
|
||
|
||
**集成测试**:
|
||
- 测试完整的 HTTP 请求响应流程(包含正常与异常情况)
|
||
- 测试 WebSocket 连接建立、消息推送、断开重连
|
||
- 测试 CORS 配置是否正确允许前端跨域访问
|
||
|
||
#### 7.2 前端测试
|
||
|
||
**单元测试**:
|
||
- 测试 API 响应拦截器对不同 code 值的处理逻辑
|
||
- 测试 `useWebSocket` 组合式函数的连接管理与消息接收
|
||
- 测试各个组件的参数校验与错误提示
|
||
|
||
**集成测试**:
|
||
- 测试前后端联调:完整的任务提交、进度推送、结果展示流程
|
||
- 测试异常场景:网络断开、后端服务异常、超时等情况的用户提示
|
||
|
||
**E2E 测试**:
|
||
- 模拟真实用户操作,验证完整的业务流程
|
||
- 测试不同浏览器的兼容性
|