MyTool/开发文档/00-开发前后端格式.md at main

Template

Files

liu 197ce5e7ea Remove outdated documentation files for audio processing modules, including development guidelines, audio file aggregation, format conversion, deduplication, metadata conversion, organization, and library integration. This cleanup enhances project maintainability and clarity.

2026-01-30 00:18:42 +08:00

5.1 KiB

Raw Permalink Blame History

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. 前后端整体架构

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. 项目目录结构

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。

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）：

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 前端测试