# xtools-boot 项目设计文档
## 一、功能和用途
### 1.1 项目概述
- **项目名称**：xtools-boot
- **项目版本**：5.0.0
- **父POM**：org.xujun:xtools-parent-boot:5.0.0
- **项目定位**：低调大师工具箱，SpringBoot工具模块，适配JDK25。提供企业级应用开发所需的通用功能模块，涵盖缓存、数据库、搜索、消息队列、任务调度、日志、存储、脱敏等核心能力，以Spring
Boot Starter形式封装，支持按需引入。
### 1.2 技术特点
- 采用最新的 JDK 25 版本，充分利用新特性（虚拟线程、结构化并发等）
- 基于 Spring Boot 4.0.5 构建，支持自动配置和快速开发
- 集成 Spring Framework 7.0.6 核心框架
- 使用 MyBatis 4.0.1 + MyBatis-Plus 3.5.16 简化数据访问层开发
- 集成 Spring Data Elasticsearch 6.0.4 + Elasticsearch Client 9.2.6 实现日志存储和检索
- 集成 Spring AMQP 4.0.2 + RabbitMQ AMQP Client 5.27.1 实现异步消息处理
- 使用 Spring Data Redis 4.0.4 + Lettuce 6.8.2.RELEASE 实现分布式缓存
- 集成 XXL-JOB 3.4.0 实现分布式任务调度
- 集成 AWS S3 SDK 2.42.34 实现对象存储
- 集成 Knife4j 4.5.0 自动生成 API 文档
- 使用 BouncyCastle 1.84 提供加密支持
- 使用 Druid 1.2.28 数据库连接池
- 使用 FastJSON2 2.0.60 进行 JSON 序列化
- 使用 MapStruct 1.6.3 进行对象映射
- 使用 Lombok 1.18.44 简化代码
- 使用 Velocity 2.4.1 模板引擎
- 使用 Caffeine 3.2.3 本地缓存
- 使用 ip2region 3.3.7 实现IP地址定位
- 使用 OSHI 6.11.1 实现系统监控
- 使用 Fesod Sheet 2.0.1-incubating 处理Excel
### 1.3 核心功能
```mermaid
graph TB
subgraph 基础模块
A1[xtools-boot-api
API定义层]
A2[xtools-boot-core
核心工具层]
end
subgraph 数据模块
B1[xtools-boot-db
数据库模块]
B2[xtools-boot-cache
缓存模块]
B3[xtools-boot-elasticsearch
搜索引擎模块]
end
subgraph 中间件模块
C1[xtools-boot-mq
消息队列模块]
C2[xtools-boot-task
任务管理模块]
C3[xtools-boot-job
任务调度模块]
C4[xtools-boot-thread
线程管理模块]
end
subgraph 功能模块
D1[xtools-boot-log
日志模块]
D2[xtools-boot-web
Web模块]
D3[xtools-boot-knife4j
API文档模块]
D4[xtools-boot-ip
IP定位模块]
D5[xtools-boot-mask
数据脱敏模块]
D6[xtools-boot-storage
存储模块]
end
B1 --> B1a[xtools-boot-db-mybatis
MyBatis集成]
B1 --> B1b[xtools-boot-db-mybatis-plus
MyBatis-Plus集成]
B2 --> B2a[xtools-boot-cache-redis
Redis缓存]
C1 --> C1a[xtools-boot-mq-base
消息总线]
C1 --> C1b[xtools-boot-mq-rabbit
RabbitMQ实现]
C3 --> C3a[xtools-boot-job-xxl
XXL-JOB集成]
D6 --> D6a[xtools-boot-storage-base
存储基础]
D6 --> D6b[xtools-boot-storage-file
文件存储]
D6 --> D6c[xtools-boot-storage-s3
S3对象存储]
D2 --> D2a[xtools-boot-web-base
Web基础]
D2 --> D2b[xtools-boot-web-filter
Web过滤器]
```
```mermaid
mindmap
root((xtools-boot
SpringBoot工具箱))
基础模块
xtools-boot-api
基础实体BaseEntity
统一枚举BaseEnum
异常体系
日志链路追踪
xtools-boot-core
Spring上下文工具
树形结构工具
枚举工具
任务执行接口
模块加载追踪
数据模块
数据库
MyBatis集成
MyBatis-Plus集成
Druid连接池
数据库监控
缓存
Redis缓存
缓存监控
搜索引擎
Elasticsearch集成
ES查询工具
ES集群监控
中间件模块
消息队列
消息总线MqBus
RabbitMQ集成
虚拟线程消费
错误处理
任务管理
TaskBus任务总线
任务状态追踪
异步任务执行
任务调度
XXL-JOB集成
自动注册执行器
线程管理
虚拟线程支持
线程回调机制
功能模块
日志
LogBus日志总线
链路追踪LogTrack
多级别日志
主子线程区分
Web
MVC配置
请求过滤器
日志链路集成
API文档
Knife4j增强UI
OpenAPI 3集成
IP定位
ip2region离线查询
数据脱敏
注解式脱敏
多类型敏感数据
自定义脱敏策略
存储
本地文件存储
AWS S3对象存储
统一存储接口
```
### 1.4 功能关系图
```mermaid
graph LR
Client[客户端请求] --> Web[xtools-boot-web]
Web --> Filter[请求过滤器]
Filter --> LogTrack[日志链路追踪]
LogTrack --> Log[xtools-boot-log]
Log --> LogBus[LogBus日志总线]
Web --> Controller[业务Controller]
Controller --> Cache[xtools-boot-cache]
Controller --> DB[xtools-boot-db]
Cache --> Redis[Redis]
DB --> MySQL[MySQL]
Controller --> MQ[xtools-boot-mq]
MQ --> RabbitMQ[RabbitMQ]
MQ --> Thread[xtools-boot-thread]
Thread --> VThread[虚拟线程]
Controller --> Task[xtools-boot-task]
Task --> TaskBus[TaskBus任务总线]
Job[xtools-boot-job] --> XXLJob[XXL-JOB]
Controller --> ES[xtools-boot-elasticsearch]
ES --> Elasticsearch[Elasticsearch]
Controller --> Storage[xtools-boot-storage]
Storage --> File[本地文件/S3]
Controller --> Mask[xtools-boot-mask]
Log --> Doc[xtools-boot-knife4j]
```
## 二、项目结构设计
### 2.1 整体架构
```mermaid
graph TD
App[xtools-boot
父模块] --> API[xtools-boot-api
API定义模块]
App --> Core[xtools-boot-core
核心工具模块]
App --> DB[xtools-boot-db
数据库模块]
App --> Cache[xtools-boot-cache
缓存模块]
App --> ES[xtools-boot-elasticsearch
搜索引擎模块]
App --> MQ[xtools-boot-mq
消息队列模块]
App --> Task[xtools-boot-task
任务管理模块]
App --> Job[xtools-boot-job
任务调度模块]
App --> Thread[xtools-boot-thread
线程管理模块]
App --> Log[xtools-boot-log
日志模块]
App --> Web[xtools-boot-web
Web模块]
App --> Knife4j[xtools-boot-knife4j
API文档模块]
App --> IP[xtools-boot-ip
IP定位模块]
App --> Mask[xtools-boot-mask
数据脱敏模块]
App --> Storage[xtools-boot-storage
存储模块]
DB --> DBMybatis[xtools-boot-db-mybatis]
DB --> DBMP[xtools-boot-db-mybatis-plus]
Cache --> CacheRedis[xtools-boot-cache-redis]
MQ --> MQBase[xtools-boot-mq-base]
MQ --> MQRabbit[xtools-boot-mq-rabbit]
Job --> JobXXL[xtools-boot-job-xxl]
Web --> WebBase[xtools-boot-web-base]
Web --> WebFilter[xtools-boot-web-filter]
Storage --> StorageBase[xtools-boot-storage-base]
Storage --> StorageFile[xtools-boot-storage-file]
Storage --> StorageS3[xtools-boot-storage-s3]
```
### 2.2 分层架构
```mermaid
flowchart TB
subgraph 自动配置层
A1[AutoConfiguration
自动配置注册]
A2[ImportSelector
导入选择器]
A3[Configuration
配置类]
end
subgraph 接口定义层
B1[BaseEnum
统一枚举接口]
B2[BaseEntity
基础实体]
B3[LogBusInterface
日志处理接口]
B4[StorageService
存储服务接口]
B5[JobInterface
任务执行接口]
B6[BaseTaskType
任务类型接口]
B7[MaskCustom
自定义脱敏接口]
end
subgraph 基础功能层
C1[SpringContextUtils
Spring上下文工具]
C2[TreeUtils
树形结构工具]
C3[EnumUtils
枚举工具]
C4[RedisUtils
Redis工具]
C5[EsUtils/EsQueryUtils
ES工具]
C6[MqBus
消息总线]
C7[LogBus
日志总线]
C8[TaskBus
任务总线]
end
subgraph 扩展功能层
D1[MySqlMonitor
MySQL监控]
D2[RedisMonitor
Redis监控]
D3[ElasticsearchMonitor
ES监控]
D4[DefaultMaskHandle
默认脱敏处理]
D5[BaseMqHandle
消息处理基类]
D6[BaseErrorHandle
错误处理基类]
end
A1 --> A2
A2 --> A3
A3 --> B1
B1 --> C1
C1 --> D1
```
### 2.3 模块职责
| 模块 | 职责 | 核心类 |
|-----------------------------|--------------------------------|-------------------------------------------|
| xtools-boot-api | API定义层，提供基础实体、枚举、异常、日志链路等公共定义 | BaseEntity、BaseEnum、BizError、LogTrack |
| xtools-boot-core | 核心工具层，提供Spring上下文、树形结构、枚举等通用工具 | SpringContextUtils、TreeUtils、EnumUtils |
| xtools-boot-db-mybatis | MyBatis集成，提供数据库访问、监控、慢查询检测 | MyBatisConfig、MySqlMonitor |
| xtools-boot-db-mybatis-plus | MyBatis-Plus集成，提供分页插件、查询工具 | MybatisPlusConfig、QueryUtils |
| xtools-boot-cache-redis | Redis缓存，提供缓存操作、监控 | RedisUtils、RedisMonitor |
| xtools-boot-elasticsearch | ES集成，提供搜索、查询、集群监控 | EsUtils、EsQueryUtils、ElasticsearchMonitor |
| xtools-boot-mq-base | 消息总线，提供消息发布、处理、错误处理 | MqBus、BaseMqHandle、BaseErrorHandle |
| xtools-boot-mq-rabbit | RabbitMQ实现，提供消息监听、消费 | BootRabbitMqConfiguration |
| xtools-boot-task | 任务管理，提供任务总线、状态追踪 | TaskBus、TaskInfo、TaskStatus |
| xtools-boot-job-xxl | XXL-JOB集成，提供分布式任务调度 | BootXxlJobConfiguration、InitXxlJob |
| xtools-boot-thread | 线程管理，提供虚拟线程、回调机制 | BootThreadConfiguration |
| xtools-boot-log | 日志模块，提供日志总线、链路追踪 | LogBus、LogTrackHolder、LogBody |
| xtools-boot-web-base | Web基础，提供MVC配置、过滤器、转换器 | BootWebBaseConfiguration、CommonFilter |
| xtools-boot-web-filter | Web过滤器，提供过滤器扫描注册 | BootWebFilterConfiguration |
| xtools-boot-knife4j | API文档，提供Knife4j/OpenAPI3集成 | BootKnife4jConfiguration |
| xtools-boot-ip | IP定位，提供离线IP地址查询 | BootIpConfiguration |
| xtools-boot-mask | 数据脱敏，提供注解式敏感数据处理 | DefaultMaskHandle、MaskType |
| xtools-boot-storage-base | 存储基础，提供统一存储接口 | StorageService |
| xtools-boot-storage-file | 文件存储，提供本地文件系统存储 | StorageServiceFileImpl |
| xtools-boot-storage-s3 | S3存储，提供AWS S3对象存储 | BootStorageS3Configuration |
### 2.4 包结构设计
```
xtools.boot.{module}
├── Boot{Module}Configuration.java # 配置类（自动配置入口）
├── selector/ # 导入选择器
│ └── Boot{Module}ImportSelector.java
├── config/ # 配置
├── interfaces/ # 接口定义
│ ├── *Interface.java # 功能接口
│ └── *Type.java # 类型接口
├── model/ # 数据模型
│ ├── dto/ # 数据传输对象
│ └── entity/ # 实体类
├── enums/ # 枚举类
├── utils/ # 工具类
├── handle/ # 处理器
├── monitor/ # 监控
├── holder/ # 线程持有者
├── callback/ # 回调
├── init/ # 初始化
├── service/ # 服务
│ └── impl/ # 服务实现
└── filter/ # 过滤器
```
### 2.5 模块依赖关系
```mermaid
graph LR
API[xtools-boot-api] --> Extend[xtools-extend]
API --> WebCore[xtools-web]
Core[xtools-boot-core] --> API
Core --> Extend
DBMybatis[xtools-boot-db-mybatis] --> Core
DBMybatis --> Log[xtools-boot-log]
DBMybatis --> Thread[xtools-boot-thread]
DBMP[xtools-boot-db-mybatis-plus] --> Core
CacheRedis[xtools-boot-cache-redis] --> Core
ES[xtools-boot-elasticsearch] --> Extend
ES --> Core
ES --> Log
MQBase[xtools-boot-mq-base] --> Core
MQBase --> Log
MQBase --> Thread
MQRabbit[xtools-boot-mq-rabbit] --> Core
MQRabbit --> MQBase
Task[xtools-boot-task] --> Core
JobXXL[xtools-boot-job-xxl] --> Core
Log --> Core
Thread --> Core
IP[xtools-boot-ip] --> Extend
IP --> Core
Knife4j[xtools-boot-knife4j] --> Core
Mask[xtools-boot-mask] --> Core
StorageBase[xtools-boot-storage-base] --> Core
StorageFile[xtools-boot-storage-file] --> Core
StorageFile --> StorageBase
StorageS3[xtools-boot-storage-s3] --> Extend
StorageS3 --> Core
StorageS3 --> StorageBase
WebBase[xtools-boot-web-base] --> WebCore
WebBase --> Core
WebBase --> Log
WebBase --> WebFilter[xtools-boot-web-filter]
WebFilter --> Core
```
## 三、项目功能设计
### 3.1 自动配置机制
```mermaid
flowchart TD
A[应用启动] --> B[Spring Boot扫描
META-INF/spring/*.imports]
B --> C[加载自动配置类
BootModuleConfiguration]
C --> D[执行构造函数
ModuleLoadUtils.loadSuccess]
D --> E["@Import导入
XXXImportSelector"]
E --> F[ImportBeanDefinitionRegistrar
注册Bean定义]
F --> G["@ConditionalOnProperty
条件化创建Bean"]
G --> H[模块就绪]
```
**自动配置设计**：
- 每个模块通过 `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` 注册自动配置类
- 配置类通过 `@Import(XXXImportSelector.class)` 导入自定义选择器
- 选择器实现 `ImportBeanDefinitionRegistrar` 接口，按包名扫描注册Bean
- 使用 `@ConditionalOnProperty` 实现条件化Bean创建
- 构造函数中调用 `ModuleLoadUtils.loadSuccess()` 记录模块加载状态
### 3.2 统一枚举设计
```mermaid
flowchart TD
A[BaseEnum接口] --> B[int code
枚举编码]
A --> C[String desc
枚举描述]
A --> D["BaseEnum[] all()
获取所有枚举"]
B --> E[StatusEnum
状态枚举]
B --> F[DeleteEnum
删除枚举]
B --> G[ThreadType
线程类型]
B --> H[FileDataType
文件类型]
B --> I[TaskStatus
任务状态]
B --> J[MaskType
脱敏类型]
B --> K[MySqlMonitorEnums
MySQL监控枚举]
B --> L[ElasticsearchMonitorEnums
ES监控枚举]
```
**枚举规范**：
- 所有业务枚举实现 `BaseEnum` 接口
- 提供 `code()` 和 `desc()` 方法
- 提供静态 `valueOf(int code)` 和 `valueOfDesc(String desc)` 方法
- 使用 `EnumUtils` 工具类进行枚举转换
### 3.3 异常处理设计
```mermaid
flowchart TD
A[CommonException
基础异常] --> B[BizError
业务异常]
A --> C[BizWarning
业务警告]
A --> D[UnauthorizedError
未授权异常]
A --> E[BizPublicKeyError
公钥异常]
F[BootError
错误码枚举] --> F1[code
错误编码]
F --> F2[type
错误类型]
F --> F3[module
所属模块]
F --> F4[messageTemplate
消息模板]
G[BootErrorModule
错误模块枚举] --> G1[API
API模块]
G --> G2[CORE
核心模块]
G --> G3[LOG
日志模块]
G --> G4[MQ
消息队列模块]
```
**异常体系**：
- `CommonException`：基础异常（来自xtools-core）
- `BizError`：业务逻辑异常，使用错误码和消息模板
- `BizWarning`：业务警告异常
- `UnauthorizedError`：认证授权异常
- `BizPublicKeyError`：公钥相关异常
- `BootError`：错误码枚举，包含code、type、module、messageTemplate
- `BootErrorModule`：错误模块枚举，用于错误分类
### 3.4 日志管理设计
```mermaid
flowchart TD
A[业务代码] --> B[LogBus.createLog
创建日志]
B --> C[LogBody
日志体]
C --> C1[title
日志主题]
C --> C2[level
日志级别]
C --> C3[type
日志类型]
C --> C4[logTrack
链路追踪]
C --> C5[runInfo
运行环境]
C --> C6[stackTrace
堆栈信息]
C --> C7[logData
日志数据]
C --> C8[err
异常文本]
B --> D[LogBusInterface实现类
日志处理器]
D --> E[写入Elasticsearch]
D --> F[写入数据库]
D --> G[发送到消息队列]
```
```mermaid
flowchart LR
A[HTTP请求] --> B[LogTrackConfig
生成LogTrack]
B --> C[LogTrackHolder
线程绑定]
C --> D[业务处理]
D --> E{是否异步线程?}
E -->|是| F[传递LogTrack到子线程]
E -->|否| G[直接使用]
F --> H[子线程处理]
G --> I[响应返回]
H --> I
```
**日志功能**：
- **LogBus**：日志总线，统一的日志创建和管理入口
- **LogTrack**：链路追踪信息，包含traceId、spanId、线程类型等
- **HolderLogTrack**：线程持有者的链路追踪，支持主子线程传递
- **LogBusInterface**：日志处理接口，支持自定义日志处理器
- **LogBusType**：日志类型接口，定义日志基础编码
- **LogBody**：日志体，包含主题、级别、类型、链路、环境、堆栈、数据、异常
- **LogBusConfig**：日志总线配置，控制日志打印和堆栈包含
- **RunInfoConfig**：运行环境信息配置
- **LogLevel**：日志级别（来自xtools-core）
### 3.5 消息队列设计
```mermaid
flowchart TD
A[业务代码] --> B[MqBus.publish
发布消息]
B --> C[MessageDto
消息体]
C --> C1[log
LogTrack链路追踪]
C --> C2[data
消息数据]
B --> D[RabbitMQ Exchange]
D --> E[Queue]
E --> F["@RabbitListener
消息监听器"]
F --> G[BaseMqHandle
消息处理基类]
G --> H{处理是否成功?}
H -->|成功| I[记录处理结果]
H -->|失败| J[BaseErrorHandle
错误处理]
J --> K[重试/记录错误日志]
```
**消息队列功能**：
- **MqBus**：消息总线，统一的消息发布入口
- **BaseMqHandle**：消息处理基类，定义消息处理模板
- **BaseErrorHandle**：错误处理基类，定义错误处理策略
- **InitMq**：自动初始化，启动时扫描并注册消息监听器
- **MessageDto**：消息体，包含LogTrack链路追踪和消息数据
- **MqEnums**：消息队列相关枚举
- **RabbitMqParams**：RabbitMQ参数配置
- 支持虚拟线程消费消息
- 消息序列化使用FastJSON2
### 3.6 任务管理设计
```mermaid
flowchart TD
A[TaskBus] --> B["new TaskBus()
创建任务总线"]
B --> C["taskType(BaseTaskType)
设置任务类型"]
C --> D["taskData(Object)
设置任务数据"]
D --> E["execute()
执行任务"]
E --> F{任务执行}
F --> G[TaskStatus.ING
执行中]
G --> H{执行结果}
H -->|成功| I[TaskStatus.SUCCESS]
H -->|失败| J[TaskStatus.ERROR]
```
**任务管理功能**：
- **TaskBus**：任务总线，提供Builder模式创建和管理任务
- **TaskInfo**：任务信息，包含任务类型、任务数据、状态等
- **TaskStatus**：任务状态枚举（ING、SUCCESS、ERROR）
- **BaseTaskType**：任务类型接口，定义任务类型
- **TaskBusInterface**：任务总线接口
### 3.7 任务调度设计
```mermaid
flowchart TD
A[应用启动] --> B[BootXxlJobConfiguration
XXL-JOB配置]
B --> C["@ConditionalOnProperty
条件化加载"]
C --> D[InitXxlJob
初始化XXL-JOB]
D --> E[扫描JobHandler]
E --> F[注册到XXL-JOB调度中心]
F --> G[调度中心触发任务]
G --> H[JobInterface实现类
执行任务]
```
**任务调度功能**：
- **BootXxlJobConfiguration**：XXL-JOB自动配置
- **InitXxlJob**：XXL-JOB初始化，自动扫描和注册任务处理器
- **JobInterface**：任务执行接口，定义任务执行契约
- 通过 `@ConditionalOnProperty` 条件化加载
- 支持分布式任务调度
### 3.8 线程管理设计
```mermaid
flowchart TD
A[BootThreadConfiguration
线程配置] --> B[虚拟线程支持]
A --> C[VirtualThreadTaskCallback
虚拟线程任务回调]
B --> D[MQ消息消费使用虚拟线程]
B --> E[异步任务使用虚拟线程]
C --> F[任务执行前回调]
C --> G[任务执行后回调]
C --> H[异常处理回调]
```
**线程管理功能**：
- **BootThreadConfiguration**：线程配置，注册虚拟线程相关Bean
- **VirtualThreadTaskCallback**：虚拟线程任务回调接口，提供执行前、执行后、异常处理回调
- 支持在消息消费和异步任务中使用虚拟线程
### 3.9 缓存设计
```mermaid
flowchart LR
A[业务代码] --> B[RedisUtils
Redis工具类]
B --> C{Redis操作}
C --> D[RedisMonitor
缓存监控]
C --> E[读写缓存]
C --> F[设置过期时间]
E --> G[Lettuce客户端]
F --> G
G --> H[Redis Server]
```
**缓存功能**：
- **BootCacheRedisConfiguration**：Redis自动配置
- **RedisUtils**：Redis工具类，封装常用Redis操作
- **RedisMonitor**：Redis监控，提供缓存统计和健康检查
- 使用Lettuce作为Redis客户端
### 3.10 数据库设计
```mermaid
flowchart TD
subgraph xtools-boot-db-mybatis
A1[MyBatisConfig
MyBatis配置]
A2[MySqlMonitor
MySQL监控]
A3[MonitorDatabasesMapper
监控Mapper]
A4[Druid连接池]
end
subgraph xtools-boot-db-mybatis-plus
B1[MybatisPlusConfig
MP配置]
B2[QueryUtils
查询工具]
end
A1 --> C[MyBatis 4.0.1]
B1 --> D[MyBatis-Plus 3.5.16]
A4 --> E[Druid 1.2.28]
B2 --> F[分页插件
时间范围过滤]
```
**数据库功能**：
- **MyBatisConfig**：MyBatis核心配置
- **MybatisPlusConfig**：MyBatis-Plus配置，注册分页插件
- **QueryUtils**：查询工具类，提供时间范围过滤等通用查询方法
- **MySqlMonitor**：MySQL监控，检测数据库连接、慢查询等
- **MonitorDatabasesMapper**：数据库监控Mapper
- **MySqlMonitorEnums**：监控指标枚举
- 使用Druid连接池管理数据库连接
### 3.11 搜索引擎设计
```mermaid
flowchart TD
A[业务代码] --> B[EsUtils
ES HTTP工具]
A --> C[EsQueryUtils
ES查询工具]
B --> D[索引操作]
B --> E[文档操作]
B --> F[集群操作]
C --> G[构建查询]
C --> H[聚合查询]
C --> I[分页查询]
J[ElasticsearchMonitor
ES监控] --> K[集群健康]
J --> L[索引状态]
J --> M[节点信息]
J --> N[ElasticsearchMonitorEnums
监控枚举]
```
**搜索引擎功能**：
- **BootElasticsearchConfiguration**：ES自动配置
- **EsUtils**：Elasticsearch HTTP客户端工具，提供索引、文档、集群操作
- **EsQueryUtils**：ES查询工具，提供通用查询构建
- **ElasticsearchMonitor**：ES集群监控
- **ElasticsearchMonitorEnums**：监控指标枚举
### 3.12 数据脱敏设计
```mermaid
flowchart TD
A["实体类字段
@Mask注解"] --> B[MaskType
脱敏类型]
B --> B1[CHINESE_NAME
中文姓名]
B --> B2[ID_CARD
身份证号]
B --> B3[MOBILE_PHONE
手机号]
B --> B4[EMAIL
邮箱]
B --> B5[BANK_CARD
银行卡]
B --> B6[PASSWORD
密码]
B --> B7[ADDRESS
地址]
B --> B8[CUSTOM
自定义]
A --> C["配置参数
prefixNoMaskLen
suffixNoMaskLen
maskChar"]
C --> D[DefaultMaskHandle
默认脱敏处理]
D --> E[MaskCustom
自定义脱敏接口]
E --> F[Jackson序列化时
自动脱敏]
```
**数据脱敏功能**：
- **BootMaskConfiguration**：脱敏模块自动配置
- **MaskType**：脱敏类型枚举，支持8种内置类型
- **DefaultMaskHandle**：默认脱敏处理器，根据类型自动脱敏
- **MaskCustom**：自定义脱敏接口，支持自定义脱敏逻辑
- 基于Jackson序列化，在JSON输出时自动脱敏
- 支持配置前缀保留长度、后缀保留长度、脱敏字符
### 3.13 存储设计
```mermaid
flowchart TD
A[StorageService
统一存储接口] --> A1[exists
文件是否存在]
A --> A2[save
保存文件]
A --> A3[get
获取文件]
A --> A4[del
删除文件]
B[StorageServiceFileImpl
文件存储实现] --> C[本地文件系统]
D[BootStorageS3Configuration
S3存储配置] --> E[AWS S3]
F["@ConditionalOnProperty
storage.type=file"] --> B
G["@ConditionalOnProperty
storage.type=s3"] --> D
A2 --> A2a[bucket
桶名称]
A2 --> A2b[fileName
文件名]
A2 --> A2c[inputStream
输入流]
A2 --> A2d[contentLength
内容长度]
```
**存储功能**：
- **StorageService**：统一存储接口，定义exists、save、get、del操作
- **BootStorageBaseConfiguration**：存储基础配置
- **StorageServiceFileImpl**：本地文件系统存储实现
- **BootStorageS3Configuration**：AWS S3对象存储配置
- **FileStorageConfig**：文件存储配置，支持配置存储路径
- 通过 `@ConditionalOnProperty` 选择存储实现
### 3.14 Web模块设计
```mermaid
flowchart TD
A[xtools-boot-web] --> B[xtools-boot-web-base]
A --> C[xtools-boot-web-filter]
B --> B1[BootWebBaseConfiguration
Web基础配置]
B --> B2[CommonFilter
通用过滤器]
B --> B3[MvcConverterConfig
MVC转换器配置]
B --> B4[LogTrackConfig
日志链路配置]
C --> C1[BootWebFilterConfiguration
过滤器配置]
C --> C2[BootWebFilterImportSelector
过滤器导入选择器]
B4 --> D[生成LogTrack]
D --> E[绑定到ThreadLocal]
E --> F[请求处理]
F --> G[清除ThreadLocal]
```
**Web模块功能**：
- **BootWebBaseConfiguration**：Web基础配置，集成xtools-web
- **CommonFilter**：通用请求过滤器，处理请求上下文
- **MvcConverterConfig**：MVC转换器配置
- **LogTrackConfig**：日志链路配置，为HTTP请求生成和管理LogTrack
- **BootWebFilterConfiguration**：Web过滤器配置
### 3.15 API文档设计
- **BootKnife4jConfiguration**：Knife4j自动配置
- 集成 springdoc-openapi-starter-webmvc-ui 3.0.3
- 集成 knife4j-openapi3-jakarta-spring-boot-starter 4.5.0
- 使用 Swagger Annotations 2.2.48 定义API文档
- 使用 `@Schema` 注解标注实体字段描述
### 3.16 IP定位设计
- **BootIpConfiguration**：IP定位自动配置
- 使用 ip2region 3.3.7 离线IP地址库
- 内置 `ip/ip2region_v4.xdb` 数据文件
- 支持IPv4地址的地理定位查询
## 四、编码规范设计
### 4.1 命名规范
**类命名**：
| 类型 | 命名规则 | 示例 |
|-------|-------------------------------------|---------------------------------------|
| 配置类 | Boot{Module}Configuration | BootCoreConfiguration |
| 导入选择器 | Boot{Module}ImportSelector | BootCoreImportSelector |
| 工具类 | {功能}Utils | SpringContextUtils |
| 监控类 | {组件}Monitor | MySqlMonitor |
| 枚举类 | {功能}Enum / {功能}Enums | StatusEnum、MySqlMonitorEnums |
| 异常类 | Biz{类型}Error | BizError、BizWarning |
| 接口 | Base{类型} / {功能}Interface / {功能}Type | BaseEnum、LogBusInterface、BaseTaskType |
| DTO类 | {功能}Dto / {功能}Info / {功能}Body | MessageDto、TaskInfo、LogBody |
| 回调类 | {功能}Callback | VirtualThreadTaskCallback |
| 初始化类 | Init{功能} | InitMq、InitXxlJob |
| 处理器 | {功能}Handle / Default{功能}Handle | BaseMqHandle、DefaultMaskHandle |
**方法命名**：
| 操作 | 命名规则 | 示例 |
|-----|-------------------------|----------------------------|
| 查询 | get / find / query | getBean、findById、queryList |
| 创建 | create / save / publish | createLog、save、publish |
| 删除 | delete / del / remove | deleteById、del |
| 判断 | is / has / exists | exists、isValid |
| 转换 | to / convert / of | valueOf、convert |
| 初始化 | init | init |
| 加载 | load | loadSuccess |
| 执行 | execute / run | execute |
**变量命名**：
| 类型 | 命名规则 | 示例 |
|---------|------------------|--------------------------|
| 普通变量 | camelCase | logTrack、taskInfo |
| 常量 | UPPER_SNAKE_CASE | CP_NUM0、CP_NUM50 |
| Boolean | is/has前缀 | isValid、hasChildren |
| 集合 | 复数形式 | items、list |
| 配置属性 | camelCase | prefixNoMaskLen、maskChar |
### 4.2 注释规范
**类注释格式**：
```java
/**
* Title : 类名称
* Description : 类描述
* DevelopTools : Idea_x64_v2026.1
* DevelopSystem : macOS Sequoia 15.7.5
* Company : org.xujun
*
* @author : XuJun
* @version : 5.0.0
* @date : 2026/1/17 18:50
*/
```
**方法注释格式**：
```java
/**
* 方法描述
*
* @param param 参数说明
* @return 返回值说明
*/
```
**字段注释格式**：
```java
/**
* 字段描述
*/
private String fieldName;
```
### 4.3 代码风格
- 使用 **Lombok** 简化代码（@Data、@Getter、@RequiredArgsConstructor）
- 使用 **MapStruct** 进行对象转换
- 使用 **FastJSON2** 进行JSON序列化
- 使用 **构造器注入**（通过Lombok的@RequiredArgsConstructor）
- 使用 **@Schema** 注解标注API文档
- 使用 **@ConfigurationProperties** 进行配置绑定
- 使用 **@ConditionalOnProperty** 进行条件化配置
- 使用 **@Import + ImportSelector** 实现自动配置
- 模块化设计，每个功能独立成模块
### 4.4 设计规范
- **分层原则**：接口定义层 → 基础功能层 → 扩展功能层
- **单一职责**：每个模块专注单一功能领域
- **开闭原则**：通过接口（LogBusInterface、StorageService、MaskCustom）支持扩展
- **依赖倒置**：面向接口编程，通过配置选择实现
- **模块化**：功能独立封装，按需引入
### 4.5 安全规范
- 数据脱敏：支持身份证、手机号、邮箱、银行卡等敏感数据自动脱敏
- 加密支持：集成BouncyCastle加密库
- SQL安全：使用MyBatis参数化查询，防止SQL注入
- 数据验证：集成Jakarta Validation（@NotNull、@Valid）
- JWT支持：集成java-jwt 4.5.1
## 五、项目依赖设计
### 5.1 核心框架依赖
| 依赖 | 版本 | 用途 |
|---------------------------|----------|-----------------|
| Spring Boot | 4.0.5 | 应用框架 |
| Spring Framework | 7.0.6 | 核心框架 |
| Spring Security | 7.0.4 | 安全框架 |
| Spring AMQP | 4.0.2 | RabbitMQ集成 |
| Spring Data BOM | 2025.1.4 | Spring Data版本管理 |
| Spring Data Redis | 4.0.4 | Redis集成 |
| Spring Data Elasticsearch | 6.0.4 | Elasticsearch集成 |
| Jakarta Servlet | 6.1.0 | Servlet API |
| Jakarta Validation | 3.1.1 | 参数校验 |
### 5.2 数据库相关依赖
| 依赖 | 版本 | 用途 |
|-----------------------------|--------|-----------|
| MyBatis Spring Boot Starter | 4.0.1 | MyBatis集成 |
| MyBatis-Plus | 3.5.16 | ORM增强工具 |
| Druid | 1.2.28 | 数据库连接池 |
### 5.3 搜索引擎依赖
| 依赖 | 版本 | 用途 |
|----------------------|-------|------------|
| Elasticsearch Client | 9.2.6 | ES Java客户端 |
### 5.4 消息队列依赖
| 依赖 | 版本 | 用途 |
|----------------------|--------|------------------|
| RabbitMQ AMQP Client | 5.27.1 | RabbitMQ Java客户端 |
### 5.5 缓存依赖
| 依赖 | 版本 | 用途 |
|----------|---------------|----------|
| Lettuce | 6.8.2.RELEASE | Redis客户端 |
| Caffeine | 3.2.3 | 本地缓存 |
### 5.6 工具库依赖
| 依赖 | 版本 | 用途 |
|----------------|----------|--------|
| Lombok | 1.18.44 | 代码简化 |
| MapStruct | 1.6.3 | 对象映射 |
| FastJSON2 | 2.0.60 | JSON处理 |
| Velocity | 2.4.1 | 模板引擎 |
| Jackson BOM | 3.1.0 | JSON处理 |
| Commons Lang3 | 3.20.0 | 通用工具 |
| Commons IO | 2.21.0 | IO工具 |
| Commons Text | 1.15.0 | 文本处理 |
| AspectJ Weaver | 1.9.25.1 | AOP支持 |
### 5.7 安全相关依赖
| 依赖 | 版本 | 用途 |
|--------------|-------|-------|
| BouncyCastle | 1.84 | 加密库 |
| Easy Captcha | 1.6.2 | 验证码 |
| java-jwt | 4.5.1 | JWT令牌 |
### 5.8 文档相关依赖
| 依赖 | 版本 | 用途 |
|---------------------|--------|-------------|
| Knife4j OpenAPI3 | 4.5.0 | API文档增强 |
| Springdoc OpenAPI | 3.0.3 | OpenAPI 3集成 |
| Swagger Annotations | 2.2.48 | API文档注解 |
### 5.9 任务调度依赖
| 依赖 | 版本 | 用途 |
|--------------|-------|---------|
| XXL-JOB Core | 3.4.0 | 分布式任务调度 |
### 5.10 系统监控依赖
| 依赖 | 版本 | 用途 |
|-----------|--------|--------|
| OSHI Core | 6.11.1 | 系统监控 |
| ip2region | 3.3.7 | IP地址定位 |
### 5.11 存储依赖
| 依赖 | 版本 | 用途 |
|------------|---------|--------|
| AWS S3 SDK | 2.42.34 | S3对象存储 |
### 5.12 办公工具依赖
| 依赖 | 版本 | 用途 |
|-------------|------------------|---------|
| Fesod Sheet | 2.0.1-incubating | Excel处理 |
| PDFBox | 3.0.7 | PDF处理 |
### 5.13 其他工具依赖
| 依赖 | 版本 | 用途 |
|---------------------|--------------|---------|
| UserAgentUtils | 1.21 | 浏览器标识解析 |
| Pinyin4j | 2.5.1 | 拼音转换 |
| Thumbnailator | 0.4.21 | 图片压缩 |
| mmseg4j-core | 1.10.0 | 中文分词 |
| ZXing | 3.5.4 | 二维码/条形码 |
| Jsoup | 1.22.1 | HTML解析 |
| Hibernate Validator | 9.0.1.Final | 参数校验 |
| Netty | 4.2.12.Final | 网络通信 |
### 5.14 测试依赖
| 依赖 | 版本 | 用途 |
|---------------|-------|------|
| JUnit Jupiter | 6.0.3 | 单元测试 |
### 5.15 xtools内部框架依赖
| 模块 | 版本 | 用途 |
|---------------------|-------|----------|
| xtools-core | 5.0.0 | 核心工具库 |
| xtools-web | 5.0.0 | Web工具库 |
| xtools-extend | 5.0.0 | 扩展工具库 |
| xtools-api | 5.0.0 | API定义库 |
| xtools-parent-boot | 5.0.0 | Boot父POM |
| xtools-parent | 5.0.0 | 基础父POM |
| xtools-dependencies | 5.0.0 | 依赖管理POM |
## 六、技术选型说明
### 6.1 JDK 25
- **选择原因**：采用最新JDK版本，充分利用Java新特性
- **关键特性**：
- **虚拟线程（Virtual Threads）**：轻量级线程，大幅提升高并发场景下的吞吐量，项目在消息队列消费和异步任务中使用虚拟线程
- **结构化并发（Structured Concurrency）**：简化多线程编程模型
- **作用域值（Scoped Values）**：替代ThreadLocal，更安全地在线程间共享数据
- **ZGC/Shenandoah GC**：低延迟垃圾回收器，适合微服务场景
- **Record Classes**：简化不可变数据类的定义
- **Pattern Matching**：增强的模式匹配，简化类型判断
- **Sealed Classes**：密封类，增强类型安全
### 6.2 Spring Boot 4.0.5
- **Spring Framework版本**：7.0.6
- **Spring Security版本**：7.0.4
- **主要特性**：
- 全面支持JDK 17+，推荐使用JDK 25
- 原生支持虚拟线程，通过配置即可启用
- 支持Jakarta EE 11规范
- 改进的可观测性（Observability），集成Micrometer
- 优化启动时间和内存占用
- 支持GraalVM Native Image
- 增强的自动配置机制
### 6.3 MyBatis 4.0.1 + MyBatis-Plus 3.5.16
- **选择原因**：MyBatis提供灵活的SQL控制，MyBatis-Plus简化CRUD操作
- **主要特性**：
- MyBatis 4.0.1 提供基础的SQL映射和参数化查询
- MyBatis-Plus 3.5.16 提供通用Mapper、分页插件、代码生成器
- 内置分页插件，简化分页查询
- 条件构造器，简化复杂查询
- 支持Lambda表达式查询
### 6.4 Elasticsearch 9.2.6
- **Spring Data Elasticsearch版本**：6.0.4
- **主要特性**：
- 全文搜索，支持中文分词（mmseg4j-core 1.10.0）
- 高性能分布式搜索和分析引擎
- 支持复杂的聚合查询
- 近实时搜索
- 集群健康监控
### 6.5 Redis
- **Spring Data Redis版本**：4.0.4
- **Lettuce客户端版本**：6.8.2.RELEASE
- **主要特性**：
- 高性能内存缓存
- 丰富的数据结构（String、Hash、List、Set、ZSet）
- 支持分布式锁
- Lettuce基于Netty的异步非阻塞客户端
- 支持集群模式和哨兵模式
### 6.6 RabbitMQ
- **Spring AMQP版本**：4.0.2
- **RabbitMQ AMQP Client版本**：5.27.1
- **主要特性**：
- 可靠的消息传递机制
- 灵活的路由规则
- 支持消息确认和重试
- 高可用集群支持
- 与Spring Boot深度集成
### 6.7 XXL-JOB 3.4.0
- **选择原因**：轻量级分布式任务调度平台
- **主要特性**：
- 可视化任务管理界面
- 支持多种任务类型（Bean、GLUE等）
- 弹性扩容
- 失败重试和告警
- 任务分片广播
### 6.8 其他重要依赖版本
| 依赖 | 版本 | 用途 |
|--------------|---------|------------|
| FastJSON2 | 2.0.60 | 高性能JSON序列化 |
| Lombok | 1.18.44 | 代码简化 |
| MapStruct | 1.6.3 | 编译期对象映射 |
| Velocity | 2.4.1 | 模板引擎（代码生成） |
| Knife4j | 4.5.0 | API文档增强 |
| BouncyCastle | 1.84 | 国密算法支持 |
| OSHI | 6.11.1 | 系统信息采集 |
| ip2region | 3.3.7 | 离线IP定位 |
| Druid | 1.2.28 | 数据库连接池监控 |
| AWS S3 SDK | 2.42.34 | S3对象存储 |
| Caffeine | 3.2.3 | 高性能本地缓存 |
| Jackson | 3.1.0 | JSON处理 |
---
**文档版本**：v1.0
**编写日期**：2026-04-16
**项目版本**：5.0.0
**父POM版本**：xtools-parent-boot:5.0.0
**JDK版本**：25
**维护团队**：xujun.org