张家训
276 lines
16 KiB
Markdown
276 lines
16 KiB
Markdown
# 项目目录结构说明
|
||
|
||
> **项目名称**: workutils
|
||
> **技术栈**: Spring Boot 2.7.18 + Java 8 + Maven
|
||
> **项目类型**: Java 工作工具集项目（金融科技 FinTech 开发和维护工具集）
|
||
|
||
---
|
||
|
||
## 一、项目顶层目录
|
||
|
||
```
|
||
workutils/
|
||
├── export/ # 导出文件目录（运行结果输出）
|
||
├── logs/ # 日志文件目录
|
||
├── src/ # 源代码目录
|
||
├── target/ # Maven 编译输出目录（67个.class文件）
|
||
├── generator.rar # MyBatis Generator 压缩包
|
||
├── mvnw # Maven Wrapper（Unix/Mac）
|
||
├── mvnw.cmd # Maven Wrapper（Windows）
|
||
├── pom.xml # Maven 项目配置文件
|
||
├── 项目说明.md # 项目概述文档
|
||
└── 项目目录结构说明.md # 本文件
|
||
```
|
||
|
||
| 文件/目录 | 说明 |
|
||
|-----------|------|
|
||
| `pom.xml` | Maven 项目配置，定义依赖（Spring Boot、MyBatis、EasyExcel、JGit、Dubbo、Redis Jedis、OpenCSV 等） |
|
||
| `mvnw` / `mvnw.cmd` | Maven Wrapper 脚本，无需本地安装 Maven 即可构建项目 |
|
||
| `generator.rar` | MyBatis Generator 相关资源压缩包 |
|
||
| `export/` | 运行工具后输出的结果文件目录，按日期分子目录（如 `20260608/`） |
|
||
| `logs/` | 应用程序日志输出目录 |
|
||
| `target/` | Maven 编译产物，包含编译后的 `.class` 文件和资源文件副本 |
|
||
|
||
---
|
||
|
||
## 二、源码目录结构（`src/main/java/com/example/workutils/`）
|
||
|
||
```
|
||
src/main/java/com/example/workutils/
|
||
├── WorkUtilsApplication.java # 应用启动入口
|
||
├── system/ # 系统框架层（平台规范定义 + 共享基础设施）
|
||
│ ├── config/
|
||
│ │ └── WorkUtilsProperties.java # 全局配置属性类
|
||
│ ├── support/ # 共享基础设施
|
||
│ │ ├── ConsoleHelper.java # 控制台交互工具类
|
||
│ │ ├── FileOperationService.java# 文件操作服务（读取/扫描/写入/路径管理）
|
||
│ │ └── OutputService.java # 输出服务（CSV/Excel）
|
||
│ └── tool/ # Tool 契约与注册中心
|
||
│ ├── Tool.java # 工具契约接口（所有 biz 模块必须实现）
|
||
│ └── ToolRegistry.java # 工具注册中心（主菜单循环 + 按命令分发）
|
||
└── biz/ # 业务工具层（各模块是独立 Tool）
|
||
├── batch/ # 批量处理工具
|
||
│ └── BatchTool.java # 批量检查入口（实现 Tool）
|
||
├── git/ # Git 操作工具
|
||
│ ├── GitTool.java # Git 工具入口（实现 Tool）
|
||
│ └── service/ # 服务实现层
|
||
│ ├── GitService.java # Git 服务接口
|
||
│ ├── GitServiceImpl.java # Git 服务实现
|
||
│ ├── config/
|
||
│ │ └── GitOptimizationConfig.java # Git 性能优化配置
|
||
│ ├── model/
|
||
│ │ └── GitCommand.java # Git 命令传输对象
|
||
│ └── internal/ # 内部实现（不对外暴露）
|
||
│ ├── GitCommandController.java # Git 命令控制器（异步/中断）
|
||
│ ├── GitCommandExecutor.java # Git 命令执行器（核心）
|
||
│ ├── GitRepositoryManager.java # Git 仓库管理器
|
||
│ ├── GitResultCache.java # Git 结果缓存管理器
|
||
│ └── strategy/ # 策略模式实现
|
||
│ ├── GitCommandStrategy.java # 策略接口
|
||
│ ├── GitStrategyFactory.java # 策略工厂
|
||
│ ├── CheckBranchChangesStrategy.java
|
||
│ └── CheckoutAndPullStrategy.java
|
||
├── mybatisexport/ # MyBatis SQL导出工具（独立插件）
|
||
│ ├── MyBatisExportTool.java # SQL 导出入口（实现 Tool）
|
||
│ └── service/
|
||
│ ├── MyBatisExportService.java # SQL 导出服务
|
||
│ └── model/
|
||
│ └── MybatisTag.java # MyBatis 标签数据对象
|
||
├── mybatisgenerator/ # MyBatis逆向工程工具（独立插件）
|
||
│ ├── MyBatisGeneratorTool.java # 逆向工程入口（实现 Tool）
|
||
│ └── service/generator/
|
||
│ ├── MyBatisGeneratorService.java # 逆向工程服务
|
||
│ ├── CustomCommentGenerator.java # 自定义注释生成器
|
||
│ ├── LombokPlugin.java # Lombok 插件（@Data）
|
||
│ └── SelectiveOnlyPlugin.java # 只保留 Selective 方法插件
|
||
└── scanner/ # 扫描工具
|
||
├── ScannerTool.java # 扫描工具入口（实现 Tool）
|
||
└── service/ # 服务实现层
|
||
├── ScannerService.java # 扫描服务
|
||
└── config/
|
||
└── ScanConfig.java # 扫描配置
|
||
```
|
||
|
||
---
|
||
|
||
## 三、核心文件详解
|
||
|
||
### 3.1 入口层
|
||
|
||
#### `WorkUtilsApplication.java`
|
||
- **作用**: Spring Boot 应用启动类，实现 `CommandLineRunner`
|
||
- **功能**:
|
||
- 支持交互式菜单模式（无参数启动），委托 `ToolRegistry.runMainMenu()`
|
||
- 支持命令行模式，通过 `ToolRegistry.getToolByCommand()` 按命令名分发
|
||
- 不依赖任何具体业务 Service，完全解耦
|
||
|
||
---
|
||
|
||
### 3.2 系统框架层（`system/`）
|
||
|
||
#### `system/tool/Tool.java`
|
||
- **作用**: 工具契约接口，所有 biz 工具模块必须实现此接口
|
||
- **核心方法**: `getId()`、`getName()`、`getMenuOptions()`、`execute()`（模板方法，含默认实现）、`getCommandName()`（命令行模式）、`executeCommand()`（命令行模式执行）
|
||
|
||
#### `system/tool/ToolRegistry.java`
|
||
- **作用**: 工具注册中心，Spring 自动发现 `Tool` Bean，提供主菜单循环
|
||
- **功能**: 根据配置过滤启用/禁用工具，支持白名单（enabled）和黑名单（disabled）模式，维护按命令名的索引，支持命令行模式按命令名分发
|
||
|
||
#### `system/support/ConsoleHelper.java`
|
||
- **作用**: 控制台交互工具类（静态方法），统一控制台 I/O
|
||
|
||
#### `system/support/FileOperationService.java`
|
||
- **作用**: 文件操作服务，提供文件读取、扫描、写入、项目路径管理等基础能力
|
||
|
||
#### `system/support/OutputService.java`
|
||
- **作用**: 输出服务，负责将数据输出为 CSV（OpenCSV）或 Excel（EasyExcel）格式，支持单Sheet/多Sheet、追加写入等
|
||
|
||
#### `system/config/WorkUtilsProperties.java`
|
||
- **作用**: 全局配置属性类，绑定 `application.yml` 中 `workutils` 前缀的配置
|
||
- **功能**: 管理基础目录、配置目录、导出目录路径，提供带日期时间戳的导出文件路径生成，管理工具启用/禁用白名单和黑名单
|
||
|
||
---
|
||
|
||
### 3.3 业务工具层（`biz/`）
|
||
|
||
> **架构约定**: 每个 biz 模块的 Tool 类（如 `GitTool.java`）放在模块根目录作为入口，所有服务实现及附属文件（config/model/internal/generator）收在 `service/` 子包下，内部细节用 `internal/` 隔离。
|
||
|
||
#### 3.3.1 扫描工具（`biz/scanner/`）
|
||
|
||
| 文件 | 作用 |
|
||
|------|------|
|
||
| `ScannerTool.java` | 扫描工具入口（实现 Tool），负责菜单交互，委托 ScannerService 执行业务逻辑 |
|
||
| `service/ScannerService.java` | 扫描服务，支持关键词扫描、Redis Key 扫描、Dubbo 接口扫描三种类型，支持并发多项目扫描 |
|
||
| `service/config/ScanConfig.java` | 扫描配置，定义文件扩展名、排除目录、最大文件大小等参数 |
|
||
|
||
#### 3.3.2a MyBatis SQL导出工具（`biz/mybatisexport/`）
|
||
|
||
| 文件 | 作用 |
|
||
|------|------|
|
||
| `MyBatisExportTool.java` | SQL 导出工具入口（实现 Tool），负责菜单交互，委托 MyBatisExportService 执行 |
|
||
| `service/MyBatisExportService.java` | SQL 导出核心服务，从 XML 文件中提取 select/insert/update/delete 标签，支持按表名/关键字/标签ID 过滤导出为 CSV |
|
||
| `service/model/MybatisTag.java` | MyBatis 标签数据对象，封装 tagId、tagName、parameterType、resultMap、namespace |
|
||
|
||
#### 3.3.2b MyBatis逆向工程工具（`biz/mybatisgenerator/`）
|
||
|
||
| 文件 | 作用 |
|
||
|------|------|
|
||
| `MyBatisGeneratorTool.java` | 逆向工程工具入口（实现 Tool），负责菜单交互，委托 MyBatisGeneratorService 执行 |
|
||
| `service/generator/MyBatisGeneratorService.java` | MyBatis 逆向工程服务，根据数据库表生成 PO、Mapper 接口、XML 映射文件 |
|
||
| `service/generator/CustomCommentGenerator.java` | 自定义注释生成器，生成简洁中文注释 |
|
||
| `service/generator/LombokPlugin.java` | Lombok 插件，为 PO 类添加 `@Data` 注解 |
|
||
| `service/generator/SelectiveOnlyPlugin.java` | 自定义插件，只保留 `insertSelective` 和 `updateByPrimaryKeySelective` |
|
||
|
||
> **设计说明**: 原 `biz/mybatis/` 已按工具维度拆分为 `mybatisexport` 和 `mybatisgenerator` 两个独立包，为后续**插件化设计**做准备——每个工具将独立打包、独立加载。
|
||
|
||
#### 3.3.3 Git 工具（`biz/git/`）
|
||
|
||
| 文件 | 作用 |
|
||
|------|------|
|
||
| `GitTool.java` | Git 工具入口（实现 Tool），负责菜单交互，委托 GitService 执行 |
|
||
| `service/GitService.java` | Git 服务接口，定义分支变更检查、切换拉取、健康检测、修复仓库等方法 |
|
||
| `service/GitServiceImpl.java` | Git 服务实现，协调各策略执行仓库健康检测和修复逻辑 |
|
||
| `service/config/GitOptimizationConfig.java` | Git 性能优化配置，管理超时、线程池、缓存、批处理、Fetch、网络等参数 |
|
||
| `service/model/GitCommand.java` | Git 命令传输对象，定义命令类型枚举（CHECK_BRANCH_CHANGES、CHECKOUT_AND_PULL 等6种） |
|
||
| `service/internal/GitCommandExecutor.java` | **核心执行器**，封装原生 git 命令执行（跨平台），提供超时控制、并发线程池、命令批处理 |
|
||
| `service/internal/GitCommandController.java` | Git 命令控制器，管理命令的异步执行、跳过、中断 |
|
||
| `service/internal/GitRepositoryManager.java` | Git 仓库管理器，提供仓库发现、分支操作、批量操作等高级封装 |
|
||
| `service/internal/GitResultCache.java` | Git 结果缓存管理器，缓存仓库信息/分支信息/提交ID，减少重复 git 命令 |
|
||
| `service/internal/strategy/GitCommandStrategy.java` | Git 命令策略接口 |
|
||
| `service/internal/strategy/GitStrategyFactory.java` | Git 策略工厂，注册和管理所有策略实现 |
|
||
| `service/internal/strategy/CheckBranchChangesStrategy.java` | 分支变更检查策略，比较两个分支的差异 |
|
||
| `service/internal/strategy/CheckoutAndPullStrategy.java` | 切换并拉取策略，批量切换分支并拉取最新代码 |
|
||
|
||
#### 3.3.4 批量工具（`biz/batch/`）
|
||
|
||
| 文件 | 作用 |
|
||
|------|------|
|
||
| `BatchTool.java` | 批量处理工具入口（实现 Tool），显示批量检查选项，委托各 Service 执行 |
|
||
|
||
---
|
||
|
||
## 四、资源配置文件（`src/main/resources/`）
|
||
|
||
```
|
||
src/main/resources/
|
||
├── application.yml # Spring Boot 主配置文件
|
||
├── logback.xml # 日志框架配置
|
||
├── mybatis-generator.xml # MyBatis Generator 配置文件
|
||
├── mybatis-generator.properties # MyBatis Generator 数据库连接配置
|
||
└── config/
|
||
└── 代码仓库项目路径.txt # 要扫描的代码仓库路径列表（含状态标记）
|
||
```
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `application.yml` | 配置应用名、`workutils` 路径配置、工具启用/禁用、日志级别 |
|
||
| `logback.xml` | Logback 日志配置，控制台输出格式为 `HH:mm:ss.SSS [线程] 级别 Logger - 消息` |
|
||
| `mybatis-generator.xml` | MyBatis Generator 配置，引用自定义插件（LombokPlugin、SelectiveOnlyPlugin、CustomCommentGenerator），配置模型/Mapper/XML 生成路径 |
|
||
| `mybatis-generator.properties` | 数据库连接信息（MySQL），JDBC URL/用户名/密码/驱动路径，以及生成的包路径 |
|
||
| `代码仓库项目路径.txt` | 待扫描的代码仓库绝对路径列表，每行格式 `路径|状态`（NORMAL/CORRUPTED），共约72个项目 |
|
||
|
||
---
|
||
|
||
## 五、设计模式与架构特点
|
||
|
||
| 模式/特点 | 应用位置 | 说明 |
|
||
|-----------|---------|------|
|
||
| **策略模式** | `Tool` 接口 + 各 biz Tool 实现 | 各工具通过实现 `Tool` 接口注册到 `ToolRegistry`，可插拔扩展，支持交互和命令行双模式 |
|
||
| **策略模式** | `GitCommandStrategy` + 各 Strategy 实现 | Git 命令执行策略，`GitStrategyFactory` 管理注册 |
|
||
| **工厂模式** | `ToolRegistry`、`GitStrategyFactory` | Spring 自动发现和注入 Bean |
|
||
| **命令模式** | `GitCommand` + `GitCommandController` | 封装 Git 命令的异步执行、中断、跳过 |
|
||
| **缓存模式** | `GitResultCache` | 缓存 Git 查询结果，减少重复命令执行 |
|
||
| **并发处理** | `GitCommandExecutor`、`ScannerService` | 线程池并发执行 Git 命令和多项目扫描 |
|
||
| **过滤器模式** | `MyBatisExportService` 内部类 | `SqlFilter` 接口实现表名/关键字/标签ID 过滤 |
|
||
| **模板回调** | `FileOperationService.scanFilesRecursively` | 使用 `SimpleFileVisitor` 实现文件遍历回调 |
|
||
| **分层架构** | `system/` vs `biz/` | system 定义平台契约与共享基础设施，biz 实现具体工具 |
|
||
| **内部隔离** | `biz/*/service/internal/` | 内部实现类用 `internal/` 隔离，不对外暴露 |
|
||
|
||
---
|
||
|
||
## 六、依赖关系图
|
||
|
||
```
|
||
WorkUtilsApplication (入口)
|
||
├── 交互模式 → ToolRegistry.runMainMenu()
|
||
│ └── ToolRegistry.getEnabledTools()
|
||
│ ├── ScannerTool ────────────→ ScannerService
|
||
│ ├── MyBatisExportTool ──────→ MyBatisExportService
|
||
│ ├── MyBatisGeneratorTool ───→ MyBatisGeneratorService
|
||
│ ├── GitTool ────────────────→ GitService → GitStrategyFactory
|
||
│ └── BatchTool ──────────────→ ScannerService + MyBatisExportService
|
||
│
|
||
└── 命令行模式 → ToolRegistry.getToolByCommand(command)
|
||
├── "scan" → ScannerTool.executeCommand(args)
|
||
├── "sql" → MyBatisExportTool.executeCommand(args)
|
||
├── "batch" → BatchTool.executeCommand(args)
|
||
└── "git" → GitTool.executeCommand(args)
|
||
（启动类不依赖任何具体业务 Service）
|
||
|
||
核心依赖链:
|
||
ScannerService → FileOperationService + OutputService
|
||
MyBatisExportService → FileOperationService + OutputService
|
||
GitService → FileOperationService + GitCommandExecutor
|
||
OutputService → FileOperationService + WorkUtilsProperties
|
||
FileOperationService → WorkUtilsProperties
|
||
```
|
||
|
||
---
|
||
|
||
## 七、问题与改进建议
|
||
|
||
### 7.1 已知问题
|
||
|
||
| 问题 | 位置 | 说明 |
|
||
|------|------|------|
|
||
| 配置文件硬编码 | `mybatis-generator.properties` | 包含明文密码 |
|
||
| pom.xml 重复依赖 | `fastjson` 1.2.83 和 2.0.57 | 两个版本的 fastjson 同时存在 |
|
||
| 项目说明版本不匹配 | `项目说明.md` | 描述为 Spring Boot 3.2.3 + Java 21，实际为 Spring Boot 2.7.18 + Java 8 |
|
||
|
||
### 7.2 重构建议
|
||
|
||
1. **统一 fastjson 版本**，建议只保留 2.0.57
|
||
2. **将数据库密码移到外部配置文件**或使用环境变量
|
||
3. **更新 `项目说明.md`** 使其与实际技术栈一致
|
||
4. **增加单元测试**，目前无测试代码
|