# 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<br/>API定义层]
        A2[xtools-boot-core<br/>核心工具层]
    end

    subgraph 数据模块
        B1[xtools-boot-db<br/>数据库模块]
        B2[xtools-boot-cache<br/>缓存模块]
        B3[xtools-boot-elasticsearch<br/>搜索引擎模块]
    end

    subgraph 中间件模块
        C1[xtools-boot-mq<br/>消息队列模块]
        C2[xtools-boot-task<br/>任务管理模块]
        C3[xtools-boot-job<br/>任务调度模块]
        C4[xtools-boot-thread<br/>线程管理模块]
    end

    subgraph 功能模块
        D1[xtools-boot-log<br/>日志模块]
        D2[xtools-boot-web<br/>Web模块]
        D3[xtools-boot-knife4j<br/>API文档模块]
        D4[xtools-boot-ip<br/>IP定位模块]
        D5[xtools-boot-mask<br/>数据脱敏模块]
        D6[xtools-boot-storage<br/>存储模块]
    end

    B1 --> B1a[xtools-boot-db-mybatis<br/>MyBatis集成]
    B1 --> B1b[xtools-boot-db-mybatis-plus<br/>MyBatis-Plus集成]
    B2 --> B2a[xtools-boot-cache-redis<br/>Redis缓存]
    C1 --> C1a[xtools-boot-mq-base<br/>消息总线]
    C1 --> C1b[xtools-boot-mq-rabbit<br/>RabbitMQ实现]
    C3 --> C3a[xtools-boot-job-xxl<br/>XXL-JOB集成]
    D6 --> D6a[xtools-boot-storage-base<br/>存储基础]
    D6 --> D6b[xtools-boot-storage-file<br/>文件存储]
    D6 --> D6c[xtools-boot-storage-s3<br/>S3对象存储]
    D2 --> D2a[xtools-boot-web-base<br/>Web基础]
    D2 --> D2b[xtools-boot-web-filter<br/>Web过滤器]
```

```mermaid
mindmap
    root((xtools-boot<br/>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<br/>父模块] --> API[xtools-boot-api<br/>API定义模块]
    App --> Core[xtools-boot-core<br/>核心工具模块]
    App --> DB[xtools-boot-db<br/>数据库模块]
    App --> Cache[xtools-boot-cache<br/>缓存模块]
    App --> ES[xtools-boot-elasticsearch<br/>搜索引擎模块]
    App --> MQ[xtools-boot-mq<br/>消息队列模块]
    App --> Task[xtools-boot-task<br/>任务管理模块]
    App --> Job[xtools-boot-job<br/>任务调度模块]
    App --> Thread[xtools-boot-thread<br/>线程管理模块]
    App --> Log[xtools-boot-log<br/>日志模块]
    App --> Web[xtools-boot-web<br/>Web模块]
    App --> Knife4j[xtools-boot-knife4j<br/>API文档模块]
    App --> IP[xtools-boot-ip<br/>IP定位模块]
    App --> Mask[xtools-boot-mask<br/>数据脱敏模块]
    App --> Storage[xtools-boot-storage<br/>存储模块]
    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<br/>自动配置注册]
        A2[ImportSelector<br/>导入选择器]
        A3[Configuration<br/>配置类]
    end

    subgraph 接口定义层
        B1[BaseEnum<br/>统一枚举接口]
        B2[BaseEntity<br/>基础实体]
        B3[LogBusInterface<br/>日志处理接口]
        B4[StorageService<br/>存储服务接口]
        B5[JobInterface<br/>任务执行接口]
        B6[BaseTaskType<br/>任务类型接口]
        B7[MaskCustom<br/>自定义脱敏接口]
    end

    subgraph 基础功能层
        C1[SpringContextUtils<br/>Spring上下文工具]
        C2[TreeUtils<br/>树形结构工具]
        C3[EnumUtils<br/>枚举工具]
        C4[RedisUtils<br/>Redis工具]
        C5[EsUtils/EsQueryUtils<br/>ES工具]
        C6[MqBus<br/>消息总线]
        C7[LogBus<br/>日志总线]
        C8[TaskBus<br/>任务总线]
    end

    subgraph 扩展功能层
        D1[MySqlMonitor<br/>MySQL监控]
        D2[RedisMonitor<br/>Redis监控]
        D3[ElasticsearchMonitor<br/>ES监控]
        D4[DefaultMaskHandle<br/>默认脱敏处理]
        D5[BaseMqHandle<br/>消息处理基类]
        D6[BaseErrorHandle<br/>错误处理基类]
    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扫描<br/>META-INF/spring/*.imports]
    B --> C[加载自动配置类<br/>BootModuleConfiguration]
    C --> D[执行构造函数<br/>ModuleLoadUtils.loadSuccess]
    D --> E["@Import导入<br/>XXXImportSelector"]
    E --> F[ImportBeanDefinitionRegistrar<br/>注册Bean定义]
    F --> G["@ConditionalOnProperty<br/>条件化创建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<br/>枚举编码]
    A --> C[String desc<br/>枚举描述]
    A --> D["BaseEnum[] all()<br/>获取所有枚举"]
    B --> E[StatusEnum<br/>状态枚举]
    B --> F[DeleteEnum<br/>删除枚举]
    B --> G[ThreadType<br/>线程类型]
    B --> H[FileDataType<br/>文件类型]
    B --> I[TaskStatus<br/>任务状态]
    B --> J[MaskType<br/>脱敏类型]
    B --> K[MySqlMonitorEnums<br/>MySQL监控枚举]
    B --> L[ElasticsearchMonitorEnums<br/>ES监控枚举]
```

**枚举规范**：

- 所有业务枚举实现 `BaseEnum` 接口
- 提供 `code()` 和 `desc()` 方法
- 提供静态 `valueOf(int code)` 和 `valueOfDesc(String desc)` 方法
- 使用 `EnumUtils` 工具类进行枚举转换

### 3.3 异常处理设计

```mermaid
flowchart TD
    A[CommonException<br/>基础异常] --> B[BizError<br/>业务异常]
    A --> C[BizWarning<br/>业务警告]
    A --> D[UnauthorizedError<br/>未授权异常]
    A --> E[BizPublicKeyError<br/>公钥异常]
    F[BootError<br/>错误码枚举] --> F1[code<br/>错误编码]
    F --> F2[type<br/>错误类型]
    F --> F3[module<br/>所属模块]
    F --> F4[messageTemplate<br/>消息模板]
    G[BootErrorModule<br/>错误模块枚举] --> G1[API<br/>API模块]
    G --> G2[CORE<br/>核心模块]
    G --> G3[LOG<br/>日志模块]
    G --> G4[MQ<br/>消息队列模块]
```

**异常体系**：

- `CommonException`：基础异常（来自xtools-core）
- `BizError`：业务逻辑异常，使用错误码和消息模板
- `BizWarning`：业务警告异常
- `UnauthorizedError`：认证授权异常
- `BizPublicKeyError`：公钥相关异常
- `BootError`：错误码枚举，包含code、type、module、messageTemplate
- `BootErrorModule`：错误模块枚举，用于错误分类

### 3.4 日志管理设计

```mermaid
flowchart TD
    A[业务代码] --> B[LogBus.createLog<br/>创建日志]
    B --> C[LogBody<br/>日志体]
    C --> C1[title<br/>日志主题]
    C --> C2[level<br/>日志级别]
    C --> C3[type<br/>日志类型]
    C --> C4[logTrack<br/>链路追踪]
    C --> C5[runInfo<br/>运行环境]
    C --> C6[stackTrace<br/>堆栈信息]
    C --> C7[logData<br/>日志数据]
    C --> C8[err<br/>异常文本]
    B --> D[LogBusInterface实现类<br/>日志处理器]
    D --> E[写入Elasticsearch]
    D --> F[写入数据库]
    D --> G[发送到消息队列]
```

```mermaid
flowchart LR
    A[HTTP请求] --> B[LogTrackConfig<br/>生成LogTrack]
    B --> C[LogTrackHolder<br/>线程绑定]
    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<br/>发布消息]
    B --> C[MessageDto<br/>消息体]
    C --> C1[log<br/>LogTrack链路追踪]
    C --> C2[data<br/>消息数据]
    B --> D[RabbitMQ Exchange]
    D --> E[Queue]
    E --> F["@RabbitListener<br/>消息监听器"]
    F --> G[BaseMqHandle<br/>消息处理基类]
    G --> H{处理是否成功?}
    H -->|成功| I[记录处理结果]
    H -->|失败| J[BaseErrorHandle<br/>错误处理]
    J --> K[重试/记录错误日志]
```

**消息队列功能**：

- **MqBus**：消息总线，统一的消息发布入口
- **BaseMqHandle**：消息处理基类，定义消息处理模板
- **BaseErrorHandle**：错误处理基类，定义错误处理策略
- **InitMq**：自动初始化，启动时扫描并注册消息监听器
- **MessageDto**：消息体，包含LogTrack链路追踪和消息数据
- **MqEnums**：消息队列相关枚举
- **RabbitMqParams**：RabbitMQ参数配置
- 支持虚拟线程消费消息
- 消息序列化使用FastJSON2

### 3.6 任务管理设计

```mermaid
flowchart TD
    A[TaskBus] --> B["new TaskBus()<br/>创建任务总线"]
    B --> C["taskType(BaseTaskType)<br/>设置任务类型"]
    C --> D["taskData(Object)<br/>设置任务数据"]
    D --> E["execute()<br/>执行任务"]
    E --> F{任务执行}
    F --> G[TaskStatus.ING<br/>执行中]
    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<br/>XXL-JOB配置]
    B --> C["@ConditionalOnProperty<br/>条件化加载"]
    C --> D[InitXxlJob<br/>初始化XXL-JOB]
    D --> E[扫描JobHandler]
    E --> F[注册到XXL-JOB调度中心]
    F --> G[调度中心触发任务]
    G --> H[JobInterface实现类<br/>执行任务]
```

**任务调度功能**：

- **BootXxlJobConfiguration**：XXL-JOB自动配置
- **InitXxlJob**：XXL-JOB初始化，自动扫描和注册任务处理器
- **JobInterface**：任务执行接口，定义任务执行契约
- 通过 `@ConditionalOnProperty` 条件化加载
- 支持分布式任务调度

### 3.8 线程管理设计

```mermaid
flowchart TD
    A[BootThreadConfiguration<br/>线程配置] --> B[虚拟线程支持]
    A --> C[VirtualThreadTaskCallback<br/>虚拟线程任务回调]
    B --> D[MQ消息消费使用虚拟线程]
    B --> E[异步任务使用虚拟线程]
    C --> F[任务执行前回调]
    C --> G[任务执行后回调]
    C --> H[异常处理回调]
```

**线程管理功能**：

- **BootThreadConfiguration**：线程配置，注册虚拟线程相关Bean
- **VirtualThreadTaskCallback**：虚拟线程任务回调接口，提供执行前、执行后、异常处理回调
- 支持在消息消费和异步任务中使用虚拟线程

### 3.9 缓存设计

```mermaid
flowchart LR
    A[业务代码] --> B[RedisUtils<br/>Redis工具类]
    B --> C{Redis操作}
    C --> D[RedisMonitor<br/>缓存监控]
    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<br/>MyBatis配置]
        A2[MySqlMonitor<br/>MySQL监控]
        A3[MonitorDatabasesMapper<br/>监控Mapper]
        A4[Druid连接池]
    end

    subgraph xtools-boot-db-mybatis-plus
        B1[MybatisPlusConfig<br/>MP配置]
        B2[QueryUtils<br/>查询工具]
    end

    A1 --> C[MyBatis 4.0.1]
    B1 --> D[MyBatis-Plus 3.5.16]
    A4 --> E[Druid 1.2.28]
    B2 --> F[分页插件<br/>时间范围过滤]
```

**数据库功能**：

- **MyBatisConfig**：MyBatis核心配置
- **MybatisPlusConfig**：MyBatis-Plus配置，注册分页插件
- **QueryUtils**：查询工具类，提供时间范围过滤等通用查询方法
- **MySqlMonitor**：MySQL监控，检测数据库连接、慢查询等
- **MonitorDatabasesMapper**：数据库监控Mapper
- **MySqlMonitorEnums**：监控指标枚举
- 使用Druid连接池管理数据库连接

### 3.11 搜索引擎设计

```mermaid
flowchart TD
    A[业务代码] --> B[EsUtils<br/>ES HTTP工具]
    A --> C[EsQueryUtils<br/>ES查询工具]
    B --> D[索引操作]
    B --> E[文档操作]
    B --> F[集群操作]
    C --> G[构建查询]
    C --> H[聚合查询]
    C --> I[分页查询]
    J[ElasticsearchMonitor<br/>ES监控] --> K[集群健康]
    J --> L[索引状态]
    J --> M[节点信息]
    J --> N[ElasticsearchMonitorEnums<br/>监控枚举]
```

**搜索引擎功能**：

- **BootElasticsearchConfiguration**：ES自动配置
- **EsUtils**：Elasticsearch HTTP客户端工具，提供索引、文档、集群操作
- **EsQueryUtils**：ES查询工具，提供通用查询构建
- **ElasticsearchMonitor**：ES集群监控
- **ElasticsearchMonitorEnums**：监控指标枚举

### 3.12 数据脱敏设计

```mermaid
flowchart TD
    A["实体类字段<br/>@Mask注解"] --> B[MaskType<br/>脱敏类型]
    B --> B1[CHINESE_NAME<br/>中文姓名]
    B --> B2[ID_CARD<br/>身份证号]
    B --> B3[MOBILE_PHONE<br/>手机号]
    B --> B4[EMAIL<br/>邮箱]
    B --> B5[BANK_CARD<br/>银行卡]
    B --> B6[PASSWORD<br/>密码]
    B --> B7[ADDRESS<br/>地址]
    B --> B8[CUSTOM<br/>自定义]
    A --> C["配置参数<br/>prefixNoMaskLen<br/>suffixNoMaskLen<br/>maskChar"]
    C --> D[DefaultMaskHandle<br/>默认脱敏处理]
    D --> E[MaskCustom<br/>自定义脱敏接口]
    E --> F[Jackson序列化时<br/>自动脱敏]
```

**数据脱敏功能**：

- **BootMaskConfiguration**：脱敏模块自动配置
- **MaskType**：脱敏类型枚举，支持8种内置类型
- **DefaultMaskHandle**：默认脱敏处理器，根据类型自动脱敏
- **MaskCustom**：自定义脱敏接口，支持自定义脱敏逻辑
- 基于Jackson序列化，在JSON输出时自动脱敏
- 支持配置前缀保留长度、后缀保留长度、脱敏字符

### 3.13 存储设计

```mermaid
flowchart TD
    A[StorageService<br/>统一存储接口] --> A1[exists<br/>文件是否存在]
    A --> A2[save<br/>保存文件]
    A --> A3[get<br/>获取文件]
    A --> A4[del<br/>删除文件]
    B[StorageServiceFileImpl<br/>文件存储实现] --> C[本地文件系统]
    D[BootStorageS3Configuration<br/>S3存储配置] --> E[AWS S3]
    F["@ConditionalOnProperty<br/>storage.type=file"] --> B
    G["@ConditionalOnProperty<br/>storage.type=s3"] --> D
    A2 --> A2a[bucket<br/>桶名称]
    A2 --> A2b[fileName<br/>文件名]
    A2 --> A2c[inputStream<br/>输入流]
    A2 --> A2d[contentLength<br/>内容长度]
```

**存储功能**：

- **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<br/>Web基础配置]
    B --> B2[CommonFilter<br/>通用过滤器]
    B --> B3[MvcConverterConfig<br/>MVC转换器配置]
    B --> B4[LogTrackConfig<br/>日志链路配置]
    C --> C1[BootWebFilterConfiguration<br/>过滤器配置]
    C --> C2[BootWebFilterImportSelector<br/>过滤器导入选择器]
    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
/**
 * <p>Title : 类名称</p>
 * <p>Description : 类描述</p>
 * <p>DevelopTools : Idea_x64_v2026.1</p>
 * <p>DevelopSystem : macOS Sequoia 15.7.5</p>
 * <p>Company : org.xujun</p>
 *
 * @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
