MyTool/00-开发前后端格式.md at 981b4ecf42d5560ee18afb0f119b53080bb4af7c

LiuMangMang/MyTool

Template

Fork 0

Files

liu 981b4ecf42 Initial setup of project files and directory structure.

2026-01-29 10:29:58 +08:00

5.1 KiB

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