项目名称：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 核心功能

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过滤器]

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 功能关系图

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 整体架构

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 分层架构

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 模块依赖关系

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 自动配置机制

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 统一枚举设计

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 异常处理设计

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 日志管理设计

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[发送到消息队列]

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 消息队列设计

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 任务管理设计

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 任务调度设计

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 线程管理设计

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 缓存设计

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 数据库设计

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 搜索引擎设计

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 数据脱敏设计

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 存储设计

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模块设计

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 注释规范

类注释格式：

/**
 * <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
 */

方法注释格式：

/**
 * 方法描述
 *
 * @param param 参数说明
 * @return 返回值说明
 */

字段注释格式：

/**
 * 字段描述
 */
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

README.md Unescape Escape

xtools-boot 项目设计文档

一、功能和用途

1.1 项目概述