xtools-boot 项目设计文档

开源地址: https://gitee.com/jun-xtools/xtools-boot.git

一、功能和用途

1.1 项目概述

1.2 技术特点

• 采用最新的 JDK 25 版本，充分利用虚拟线程（Virtual Threads）、ScopedValue等新特性
• 基于 Spring Boot 4.0.6 构建，支持自动配置和快速开发
• 使用 MyBatis-Plus 3.5.16 简化数据访问层开发
• 使用 MyBatis 4.0.1 提供灵活的SQL映射能力
• 使用 Druid 1.2.28 数据库连接池，内置SQL监控
• 集成 Elasticsearch 9.2.8 实现日志存储和检索
• 支持 Knife4j 4.5.0 自动生成 API 文档
• 集成 Spring AMQP 4.0.3 实现 RabbitMQ 异步消息处理
• 集成 Spring Data Redis 实现分布式缓存
• 集成 XXL-JOB 3.4.0 实现分布式任务调度
• 集成 Spring Boot Admin 4.0.4 实现应用监控
• 使用 Jackson 3.1.2 进行 JSON 序列化/反序列化
• 使用 FastJSON2 2.0.60 处理JSON数据
• 使用 Lombok 1.18.46 简化Java代码
• 使用 MapStruct 1.6.3 进行对象映射转换
• 支持 S3 2.42.41 对象存储
• 使用 ip2region 3.3.7 实现IP地址定位

1.3 核心功能

1.4 功能层次结构

1.5 功能关系图

二、项目结构设计

2.1 整体架构

2.2 分层架构

2.3 模块职责

2.4 包结构设计

xtools.boot.{module}
├── {Module}Configuration          # 模块配置类（@Import ImportSelector）
├── selector
│   └── {Module}ImportSelector      # 自动导入选择器
├── config                           # 模块配置属性
├── constant                         # 常量定义
├── enums                            # 枚举定义
├── interfaces                       # 接口定义
│   ├── BusInterface                # 总线接口（LogBusInterface, TaskBusInterface, MqEnums）
│   └── BaseType                    # 基础类型接口（BaseEnum, BaseTaskType）
├── model
│   └── dto                         # 数据传输对象
├── utils                            # 工具类
├── handle                          # 处理器
├── filter                           # 过滤器
├── init                             # 初始化（ApplicationRunner）
├── monitor                          # 监控组件
├── holder                           # 持有器（ScopedValue）
├── service                          # 服务接口和实现
└── annotation                       # 自定义注解

2.5 模块自动装配设计

所有模块采用统一的自动装配模式：

设计原则：

• 每个模块通过 @Configuration + @Import(ImportSelector) 实现按需加载
• ImportSelector 指定模块的根包路径，自动注册所有 @Component、@Configuration 等注解的类
• 业务应用只需引入对应模块的 Maven 依赖，无需手动配置

三、项目功能设计

3.1 统一响应与异常设计

统一响应模型

public final class Result<T> {
    private boolean success;  // 是否成功
    private int code;         // 响应代码
    private Object msg;       // 提示信息
    private T data;           // 响应数据
}

异常体系

全局异常处理流程

3.2 日志管理设计

日志总线架构

日志追踪设计

日志类型枚举

3.3 缓存设计

Redis服务架构

3.4 消息队列设计

消息总线架构

消息初始化流程

3.5 存储设计

存储抽象架构

StorageService接口方法：

3.6 数据脱敏设计

脱敏注解

3.7 过滤器链设计

3.8 任务总线设计

任务状态枚举：

3.9 虚拟线程设计

四、编码规范设计

4.1 命名规范

类命名

方法命名

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/01/01 09:30
 */

方法注释格式

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

4.3 代码风格

• Lombok简化代码：使用 @Data、@Slf4j、@Resource 等注解减少样板代码
• 构造器注入：通过 @Resource 进行依赖注入
• 统一返回格式：所有Controller方法返回 Result<T>
• 统一异常处理：通过 @RestControllerAdvice 全局捕获异常
• ScopedValue：使用JDK 21的ScopedValue替代ThreadLocal，用于线程间上下文传递
• 虚拟线程：日志保存、消息处理等使用虚拟线程异步执行
• 链式调用：LogBus、TaskBus、MqBus支持链式API调用
• 接口驱动：LogBusInterface、TaskBusInterface、BaseMqHandle、StorageService均通过接口定义，业务层实现

4.4 设计规范

• 单一职责：每个模块专注单一功能领域（缓存、日志、消息队列等）
• 开闭原则：通过接口（LogBusInterface、TaskBusInterface、BaseMqHandle）支持扩展，无需修改框架代码
• 依赖倒置：高层模块通过接口依赖低层实现，如StorageService接口抽象文件存储和S3存储
• 按需加载：通过ImportSelector实现模块按需自动装配，引入依赖即生效
• 总线模式：LogBus、TaskBus、MqBus统一采用总线模式，通过Spring容器获取所有接口实现

4.5 安全规范

• XSS防护：@IgnoreXss 注解标记不需要XSS过滤的字段，Jackson的String反序列化器自动过滤XSS
• 数据脱敏：@Mask 注解在JSON序列化阶段自动脱敏敏感数据
• SQL监控：MyBatis拦截器记录慢查询和SQL日志
• 参数验证：使用 @Valid 注解进行参数校验，全局异常处理器统一处理校验失败

五、项目依赖设计

5.1 核心框架依赖

5.2 数据访问依赖

5.3 工具库依赖

5.4 扩展工具依赖

5.5 办公工具依赖

5.6 文档相关依赖

5.7 任务调度依赖

5.8 监控依赖

5.9 其他工具依赖

5.10 POM继承链

六、技术选型说明

6.1 JDK 25

• LTS版本：JDK 25是长期支持版本，提供长期稳定的安全更新
• 虚拟线程（Virtual Threads）：项目大量使用虚拟线程进行异步操作，如日志保存、消息处理，大幅简化并发编程
• ScopedValue：替代传统的ThreadLocal，用于线程间上下文传递（LogTrack、CommonHolder），性能更优且更安全
• Record模式匹配：枚举类型使用record定义，支持简洁的模式匹配语法
• Switch表达式：全局异常处理器等场景使用增强的switch表达式
• 文本块和String模板：日志格式化等场景使用文本块提升可读性

6.2 Spring Boot 4.0.6

• Spring Framework版本：7.0.7，提供最新的核心功能
• Jakarta EE 11：全面支持Jakarta EE 11规范（Jakarta Servlet 6.1.0）
• 自动配置：所有模块基于Spring Boot自动配置机制，引入依赖即生效
• Actuator：内置应用监控端点
• 嵌入式容器：Tomcat 11.0.21

6.3 MyBatis-Plus 3.5.16

• 简化CRUD：通过BaseMapper提供通用增删改查
• 分页插件：内置分页拦截器，配合QueryUtils实现分页查询
• 代码生成：配合xtools-app-gen模块实现代码生成
• SQL解析：通过mybatis-plus-jsqlparser支持SQL解析和优化
• 支持MyBatis版本：4.0.1

6.4 Elasticsearch 9.2.8

• Spring Data Elasticsearch：通过Spring Data BOM 2025.1.5管理
• 全文搜索：用于日志检索和全文查询
• 高性能：基于Lucene的分布式搜索引擎
• EsUtils：封装ES的GET/POST操作
• EsQueryUtils：封装常用查询条件（matchPhrase、wildcard、timeRange）

6.5 Redis

• Spring Data Redis：通过Spring Boot 4.0.6管理（Lettuce 6.8.2客户端）
• RedisService：封装String、Hash、分布式锁等操作
• FastJSON2序列化：使用FastJSON2进行Redis值的序列化/反序列化
• 分布式锁：基于RedisTemplate的setIfAbsent + Lua脚本实现

6.6 RabbitMQ

• Spring AMQP：4.0.3版本，提供RabbitMQ集成
• RabbitMQ Client：5.27.1版本
• 消息总线：通过MqBus统一消息推送接口
• 消息编解码：MqMessageUtils提供消息的打包/解包

6.7 其他重要技术选型

文档版本：v1.0
编写日期：2026-06-09
项目版本：5.0.0
父POM版本：xtools-parent-boot:5.0.0
顶级父POM：xtools-parent:5.0.0
JDK版本：25
维护团队：xujun.org