yiciheng/workutils

Fork 0

Files

T

张家训 a641796a0b 代码提交

2026-06-16 17:41:14 +08:00

21 KiB

Raw Permalink Blame History

项目目录结构说明

项目名称: workutils
技术栈: Spring Boot 2.7.18 + Java 8 + Maven
项目类型: Java 工作工具集项目（金融科技 FinTech 开发和维护工具集）

一、项目顶层目录

workutils/
├── docs/                            # 项目文档
│   ├── 项目说明.md
│   └── 项目目录结构说明.md
├── scripts/                         # 构建/启动脚本
│   ├── build_release.bat            # 生产构建脚本
│   ├── start.bat                    # 快速启动入口
│   └── start-jar.bat                # jar 启动脚本（UTF-8）
├── src/                             # 源代码目录
├── lib/                             # Maven 本地文件仓库（jfxrt.jar 等）
├── target/                          # Maven 编译输出
├── mvnw                             # Maven Wrapper（Unix/Mac）
├── mvnw.cmd                         # Maven Wrapper（Windows）
├── pom.xml                          # Maven 项目配置文件
├── .gitignore                       # Git 忽略规则
│
├── (运行时生成，已 gitignore)
├── data/                            # 运行时配置文件和数据
│   ├── workutils.config             # 外部配置
│   ├── project_paths.txt            # 项目路径数据
│   └── damaged_repos.cache          # 损坏仓库缓存
├── logs/                            # 运行时日志
├── export/                          # 运行时导出文件（按日期子目录）
└── build.log                        # 构建日志

文件/目录	说明
`docs/`	项目文档目录
`scripts/`	构建/启动脚本目录，包含构建打包、启动入口等
`lib/`	Maven 本地文件仓库，存放 jfxrt.jar 等外部依赖
`pom.xml`	Maven 项目配置，定义依赖（Spring Boot、MyBatis、EasyExcel、JGit、Dubbo、Redis Jedis、OpenCSV 等）
`mvnw` / `mvnw.cmd`	Maven Wrapper 脚本，无需本地安装 Maven 即可构建项目
`logs/`	应用程序运行时日志输出目录
`export/`	运行工具后输出的结果文件目录，按日期分子目录（如 `20260608/`）
`target/`	Maven 编译产物，包含编译后的 `.class` 文件和资源文件副本
`data/`	运行时配置文件和数据目录
`data/workutils.config`	外部配置文件，首次运行时从 `application.yml` 自动生成
`data/project_paths.txt`	项目路径配置，首次运行时从模板 `templates/project_paths.txt` 复制
`data/damaged_repos.cache`	损坏仓库缓存，首次运行时从模板复制

二、源码目录结构（`src/main/java/com/example/workutils/`）

src/main/java/com/example/workutils/
├── WorkUtilsApplication.java        # 应用启动入口
├── system/                          # 系统框架层（平台规范定义 + 共享基础设施）
│   ├── config/
│   │   └── WorkUtilsProperties.java # 全局配置属性类
│   ├── support/                     # 共享基础设施
│   │   ├── ConsoleHelper.java       # 控制台交互工具类
│   │   ├── FileOperationHelper.java # 文件操作工具类（读取/扫描/写入/路径管理）
│   │   └── OutputHelper.java        # 输出工具类（CSV/Excel）
│   └── plugin/                      # 插件化框架
│       ├── Plugin.java              # 插件接口（生命周期 + 菜单 + 命令的统一契约）
│       ├── PluginDescriptor.java    # 插件描述符（id/name/version/description/dependencies）
│       ├── PluginContext.java       # 插件运行时上下文
│       ├── PluginManager.java       # 插件管理器（生命周期 + 注册 + 主菜单 + 命令分发）
│       └── PluginState.java         # 插件状态枚举（UNLOADED/LOADED/ACTIVE/DISABLED/ERROR）
└── biz/                             # 业务插件层（各模块实现 Plugin 接口）
    ├── diff/                        # 文本对比插件
    │   ├── DiffPlugin.java          # 文本差异对比（实现 Plugin），支持可视化窗口
    │   └── DiffWindow.java          # Swing 可视化对比窗口（左右粘贴文本，一键对比）
    ├── git/                         # Git 操作插件
    │   ├── GitPlugin.java           # Git 插件入口（实现 Plugin）
    │   └── 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导出插件
    │   ├── MyBatisExportPlugin.java # SQL 导出入口（实现 Plugin）
    │   └── service/
    │       ├── MyBatisExportService.java    # SQL 导出服务
    │       └── model/
    │           └── MybatisTag.java          # MyBatis 标签数据对象
    ├── mybatisgenerator/            # MyBatis逆向工程插件
    │   ├── MyBatisGeneratorPlugin.java     # 逆向工程入口（实现 Plugin）
    │   └── service/generator/
    │       ├── MyBatisGeneratorService.java # 逆向工程服务
    │       ├── CustomCommentGenerator.java  # 自定义注释生成器
    │       ├── LombokPlugin.java            # Lombok 插件（@Data）
    │       └── SelectiveOnlyPlugin.java     # 只保留 Selective 方法插件
    └── scanner/                     # 扫描插件
        ├── ScannerPlugin.java       # 扫描工具入口（实现 Plugin）
        └── service/                 # 服务实现层
            ├── ScannerService.java  # 扫描服务
            └── config/
                └── ScanConfig.java  # 扫描配置

三、核心文件详解

3.1 入口层

`WorkUtilsApplication.java`

作用: Spring Boot 应用启动类，实现 CommandLineRunner
功能:
- 支持交互式菜单模式（无参数启动），委托 PluginManager.runMainMenu()
- 支持命令行模式，通过 PluginManager.getPluginByCommand() 按命令名分发
- 不依赖任何具体业务 Service，完全解耦

3.2 系统框架层（`system/`）

3.2.1 插件化框架（`system/plugin/`）

文件	作用
`Plugin.java`	插件接口，定义 `getDescriptor()`、`getId()`、`getName()`、`getMenuOptions()`、`execute()`、`handleChoice()`、`getCommandName()`、`executeCommand()`、`onLoad(PluginContext)`、`onUnload()` 等完整契约
`PluginDescriptor.java`	插件描述符（不可变），包含 `id`、`name`、`version`、`description`、`dependencies`，通过 Builder 模式构建
`PluginContext.java`	插件运行时上下文，提供 `PluginManager` 引用和跨插件共享属性
`PluginManager.java`	插件管理器（`@Component`），负责：生命周期管理（load/enable/disable）、注册发现（按 id/command 查找）、启用过滤（白名单/黑名单）、主菜单交互循环、命令行分发
`PluginState.java`	插件状态枚举：`UNLOADED` → `LOADED` → `ACTIVE` / `DISABLED` / `ERROR`

3.2.3 共享基础设施（`system/support/`）

文件	作用
`ConsoleHelper.java`	控制台交互工具类（静态方法），统一控制台 I/O
`FileOperationHelper.java`	文件操作工具类，提供文件读取、扫描、写入、项目路径管理等基础能力
`OutputHelper.java`	输出工具类，负责将数据输出为 CSV（OpenCSV）或 Excel（EasyExcel）格式

3.2.4 全局配置（`system/config/`）

文件	作用
`WorkUtilsProperties.java`	全局配置属性类（`@ConfigurationProperties`），管理路径、工具启用/禁用（`ToolsConfig`）

3.3 业务插件层（`biz/`）

架构约定: 每个 biz 模块的 Plugin 类放在模块根目录，实现 Plugin 接口。通过静态 PluginDescriptor 声明插件元数据（id/name/version/description）。所有服务实现及附属文件收在 service/ 子包下，内部细节用 internal/ 隔离。

3.3.1 扫描插件（`biz/scanner/`）

文件	作用
`ScannerPlugin.java`	扫描插件入口（实现 Plugin），版本 `1.0.0`，负责菜单交互，委托 ScannerService 执行业务逻辑
`service/ScannerService.java`	扫描服务，支持关键词扫描、Redis Key 扫描、Dubbo 接口扫描三种类型，支持并发多项目扫描
`service/config/ScanConfig.java`	扫描配置，定义文件扩展名、排除目录、最大文件大小等参数

3.3.2a MyBatis SQL导出插件（`biz/mybatisexport/`）

文件	作用
`MyBatisExportPlugin.java`	SQL 导出插件入口（实现 Plugin），版本 `1.0.0`，负责菜单交互
`service/MyBatisExportService.java`	SQL 导出核心服务，从 XML 文件中提取 select/insert/update/delete 标签
`service/model/MybatisTag.java`	MyBatis 标签数据对象

3.3.2b MyBatis逆向工程插件（`biz/mybatisgenerator/`）

文件	作用
`MyBatisGeneratorPlugin.java`	逆向工程插件入口（实现 Plugin），版本 `1.0.0`
`service/generator/MyBatisGeneratorService.java`	MyBatis 逆向工程服务
`service/generator/CustomCommentGenerator.java`	自定义注释生成器
`service/generator/LombokPlugin.java`	Lombok 插件（@Data）
`service/generator/SelectiveOnlyPlugin.java`	只保留 Selective 方法插件

3.3.3 Git 插件（`biz/git/`）

文件	作用
`GitPlugin.java`	Git 插件入口（实现 Plugin），版本 `1.0.0`
`service/GitService.java`	Git 服务接口
`service/GitServiceImpl.java`	Git 服务实现
`service/config/GitOptimizationConfig.java`	Git 性能优化配置
`service/model/GitCommand.java`	Git 命令传输对象
`service/internal/GitCommandExecutor.java`	核心执行器，跨平台 git 命令执行
`service/internal/GitCommandController.java`	Git 命令控制器（异步/中断）
`service/internal/GitRepositoryManager.java`	Git 仓库管理器
`service/internal/GitResultCache.java`	Git 结果缓存管理器
`service/internal/strategy/*`	策略模式实现

3.3.4 文本对比插件（`biz/diff/`）

文件	作用
`DiffPlugin.java`	文本对比插件入口（实现 Plugin），版本 `1.0.0`，基于 LCS 算法行级精确对比，支持粘贴可视化窗口、文件对比、目录对比三种模式
`DiffWindow.java`	JavaFX 可视化对比窗口。上半区粘贴原文/对比文，下半区 WebView 渲染字符级差异（浅红背景=删除字符，浅绿背景=新增字符，无色=相同），支持行+字符两级 LCS 算法

功能	快捷键	说明
开始对比	`Ctrl+Enter`	将左右文本区的内容进行行级对比
交换左右	`Ctrl+L`	交换左右两侧文本
粘贴	点击按钮	从系统剪贴板粘贴到对应文本区
复制结果	点击按钮	将对比结果复制到剪贴板
保存报告	点击按钮	保存为 `export/yyyyMMdd/diff_paste_时间戳.txt`

四、资源配置文件（`src/main/resources/`）

src/main/resources/
├── application.yml                  # Spring Boot 主配置文件
├── logback.xml                      # 日志框架配置
├── mybatis-generator.xml            # MyBatis Generator 配置文件
├── mybatis-generator.properties     # MyBatis Generator 数据库连接配置
├── config/                          # 旧配置文件（已废弃，保留兼容）
└── templates/                       # 数据文件模板（首次运行时复制到 user.dir）
    ├── project_paths.txt            # 项目路径配置模板
    └── damaged_repos.cache          # 损坏仓库缓存模板

文件	说明
`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/用户名/密码/驱动路径，以及生成的包路径
`templates/`	数据文件模板目录，首次运行时自动复制到 `user.dir` 同级目录

五、设计模式与架构特点

模式/特点	应用位置	说明
插件架构	`Plugin` + `PluginManager` + `PluginDescriptor`	每个 biz 模块作为独立 Plugin，声明版本、描述，PluginManager 统一管理生命周期（load/enable/disable），可插拔扩展
策略模式	`Plugin` 接口 + 各 biz 实现	各插件通过实现 Plugin 接口注册到 PluginManager，支持交互和命令行双模式
策略模式	`GitCommandStrategy` + 各 Strategy 实现	Git 命令执行策略，`GitStrategyFactory` 管理注册
工厂模式	`PluginManager`、`GitStrategyFactory`	Spring 自动发现和注入 Bean
命令模式	`GitCommand` + `GitCommandController`	封装 Git 命令的异步执行、中断、跳过
缓存模式	`GitResultCache`	缓存 Git 查询结果，减少重复命令执行
并发处理	`GitCommandExecutor`、`ScannerService`	线程池并发执行 Git 命令和多项目扫描
过滤器模式	`MyBatisExportService` 内部类	`SqlFilter` 接口实现表名/关键字/标签ID 过滤
模板回调	`FileOperationHelper.scanFilesRecursively`	使用 `SimpleFileVisitor` 实现文件遍历回调
分层架构	`system/` vs `biz/`	system 定义平台契约与共享基础设施，biz 实现具体插件
内部隔离	`biz/*/service/internal/`	内部实现类用 `internal/` 隔离，不对外暴露
生命周期管理	`Plugin.onLoad()` / `Plugin.onUnload()`	插件加载/卸载回调，PluginContext 传递运行时上下文

六、依赖关系图

WorkUtilsApplication (入口)
  ├── 交互模式 → PluginManager.runMainMenu()
  │     └── PluginManager.getEnabledPlugins()
  │           ├── ScannerPlugin ────────────→ ScannerService
  │           ├── MyBatisExportPlugin ──────→ MyBatisExportService
  │           ├── MyBatisGeneratorPlugin ───→ MyBatisGeneratorService
  │           ├── GitPlugin ────────────────→ GitService → GitStrategyFactory
  │           └── DiffPlugin ───────────────→ (自含LCS算法，无外部依赖)
  │
  └── 命令行模式 → PluginManager.getPluginByCommand(command)
        ├── "scan"   → ScannerPlugin.executeCommand(args)
        ├── "sql"    → MyBatisExportPlugin.executeCommand(args)
        ├── "diff"   → DiffPlugin.executeCommand(args)
        └── "git"    → GitPlugin.executeCommand(args)
        （启动类不依赖任何具体业务 Service）

插件加载链路:
  PluginManager.init()
    ├── 遍历 Spring 中所有 Plugin Bean
    ├── 依次调用 plugin.onLoad(PluginContext)
    ├── 按 ToolsConfig 过滤启用/禁用
    └── 构建 pluginByIdMap / pluginByCommandMap / pluginStates

核心依赖链:
  ScannerService → FileOperationHelper + OutputHelper
  MyBatisExportService → FileOperationHelper + OutputHelper
  GitService → FileOperationHelper + GitCommandExecutor
  OutputHelper → FileOperationHelper + WorkUtilsProperties
  FileOperationHelper → 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 重构建议

统一 fastjson 版本，建议只保留 2.0.57
将数据库密码移到外部配置文件或使用环境变量
更新 项目说明.md 使其与实际技术栈一致
增加单元测试，目前无测试代码

八、插件化架构设计

8.1 核心概念

┌──────────────────────────────────────────────────────┐
│                   PluginManager                      │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────┐  │
│  │ 生命周期管理  │  │  注册与发现   │  │ 菜单/命令   │  │
│  │ load/unload │  │ id/command   │  │ 分发       │  │
│  └─────────────┘  └──────────────┘  └────────────┘  │
│                                                      │
│  pluginByIdMap    pluginByCommandMap   pluginStates  │
└──────────────────────┬───────────────────────────────┘
                       │ onLoad(PluginContext)
        ┌──────────────┼──────────────┬──────────────┐
        ▼              ▼              ▼              ▼
   ScannerPlugin   MyBatisExport  MyBatisGen    GitPlugin   DiffPlugin
   [v1.0.0]      [v1.0.0]       [v1.0.0]     [v1.0.0]  [v1.0.0]

8.2 接口层次

Plugin (system/plugin/)           ← 统一契约：getDescriptor/onLoad/onUnload/getMenuOptions/execute/...
  ↑
各 biz 模块                    ← 具体实现：@Component + PluginDescriptor

8.3 插件描述符（PluginDescriptor）

每个插件通过静态 PluginDescriptor 声明自身元数据：

字段	说明	示例
`id`	全局唯一标识	`"scan"`, `"mybatisexport"`
`name`	菜单显示名称	`"扫描功能"`
`version`	语义化版本	`"1.0.0"`
`description`	功能简述	`"关键词/Redis/Dubbo扫描工具"`
`dependencies`	依赖的插件 ID（预留）	`[]`

8.4 插件状态机

UNLOADED ──load──▶ LOADED ──enable──▶ ACTIVE ──disable──▶ DISABLED
  ▲                  │                    │                 │
  │                  │ error              │ error           │
  │                  ▼                    ▼                 │
  └──────────────── ERROR ◀──────────── ERROR ◀─────────────┘
                           unload ↻ UNLOADED

8.5 后续插件化方向

当前已完成插件化基础框架搭建，后续可进一步实现：

SPI 自动发现 — 通过 META-INF/services 或 Spring Factories 自动发现外部 jar 中的 Plugin 实现
独立打包 — 每个 biz 模块打成独立 jar，PluginManager 动态加载
热加载 — 基于自定义 ClassLoader 实现插件的动态加载/卸载/更新
依赖注入隔离 — 每个插件使用独立 Spring 子容器（ApplicationContext），避免 Bean 冲突
插件市场 — 插件仓库 + 版本管理 + 远程下载

21 KiB Raw Permalink Blame History Unescape Escape

项目目录结构说明

一、项目顶层目录

二、源码目录结构（src/main/java/com/example/workutils/）

三、核心文件详解

3.1 入口层

WorkUtilsApplication.java

3.2 系统框架层（system/）

3.2.1 插件化框架（system/plugin/）

3.2.3 共享基础设施（system/support/）

3.2.4 全局配置（system/config/）

3.3 业务插件层（biz/）

3.3.1 扫描插件（biz/scanner/）

3.3.2a MyBatis SQL导出插件（biz/mybatisexport/）

3.3.2b MyBatis逆向工程插件（biz/mybatisgenerator/）

3.3.3 Git 插件（biz/git/）

3.3.4 文本对比插件（biz/diff/）

四、资源配置文件（src/main/resources/）

五、设计模式与架构特点

六、依赖关系图

七、问题与改进建议

7.1 已知问题

7.2 重构建议

八、插件化架构设计

8.1 核心概念

8.2 接口层次

8.3 插件描述符（PluginDescriptor）

8.4 插件状态机

8.5 后续插件化方向

21 KiB

Raw Permalink Blame History

二、源码目录结构（`src/main/java/com/example/workutils/`）

`WorkUtilsApplication.java`

3.2 系统框架层（`system/`）

3.2.1 插件化框架（`system/plugin/`）

3.2.3 共享基础设施（`system/support/`）

3.2.4 全局配置（`system/config/`）

3.3 业务插件层（`biz/`）

3.3.1 扫描插件（`biz/scanner/`）

3.3.2a MyBatis SQL导出插件（`biz/mybatisexport/`）

3.3.2b MyBatis逆向工程插件（`biz/mybatisgenerator/`）

3.3.3 Git 插件（`biz/git/`）

3.3.4 文本对比插件（`biz/diff/`）

四、资源配置文件（`src/main/resources/`）