yiciheng/workutils

Fork 0

Files

T

张家训 75a1049d8e 稳定版本-0609

2026-06-09 09:32:34 +08:00

16 KiB

Raw Blame History

项目目录结构说明

项目名称: 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`	待扫描的代码仓库绝对路径列表，每行格式 `路径

五、设计模式与架构特点

模式/特点	应用位置	说明
策略模式	`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 重构建议

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

16 KiB Raw Blame History Unescape Escape

项目目录结构说明

一、项目顶层目录

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

三、核心文件详解

3.1 入口层

WorkUtilsApplication.java

3.2 系统框架层（system/）

system/tool/Tool.java

system/tool/ToolRegistry.java

system/support/ConsoleHelper.java

system/support/FileOperationService.java

system/support/OutputService.java

system/config/WorkUtilsProperties.java

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/batch/）

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

五、设计模式与架构特点

六、依赖关系图

七、问题与改进建议

7.1 已知问题

7.2 重构建议

16 KiB

Raw Blame History

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

`WorkUtilsApplication.java`

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

`system/tool/Tool.java`

`system/tool/ToolRegistry.java`

`system/support/ConsoleHelper.java`

`system/support/FileOperationService.java`

`system/support/OutputService.java`

`system/config/WorkUtilsProperties.java`

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/batch/`）

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