xtools-app 项目设计文档

一、功能和用途

1.1 项目概述

• 项目名称：xtools-app
• 项目版本：1.0.0
• 父POM：org.xujun:xtools-parent-cloud:5.0.0
• 项目定位：基础应用平台，提供企业级应用开发的核心功能和公共模块，支持单体部署和微服务部署两种模式
• 组织：org.xujun

1.2 技术特点

• 采用最新的 JDK 25 版本，充分利用新特性（ScopedValue、虚拟线程、Record等）
• 基于 Spring Boot 4.0.5 构建，支持自动配置和快速开发
• 集成 Spring Cloud 2025.1.1 微服务框架
• 使用 Spring Cloud Alibaba 2025.1.0.0 微服务组件
• 使用 MyBatis-Plus 3.5.16 简化数据访问层开发（基于 MyBatis 4.0.1）
• 使用 Spring Data Elasticsearch（基于 Elasticsearch Client 9.2.6）实现日志存储和检索
• 支持 Nacos 3.1.1 服务注册与发现、配置中心
• 集成 Sentinel 1.8.9 实现流量控制和熔断降级
• 使用 Spring Data Redis（基于 Lettuce 6.8.2）实现分布式缓存
• 使用 Spring AMQP 4.0.2（RabbitMQ Client 5.27.1）实现异步消息处理
• 支持 Knife4j 4.5.0（基于 SpringDoc OpenAPI 3.0.3）自动生成 API 文档
• 使用 Druid 1.2.28 数据库连接池
• 使用 SM2/SM3 国密算法保障密码和数据安全

1.3 核心功能

graph TB
    subgraph 系统管理模块
        A1[用户管理<br/>用户增删改查,角色分配,密码管理]
        A2[角色管理<br/>角色配置,权限分配,菜单分配]
        A3[菜单管理<br/>树形结构,动态加载,按钮权限]
        A4[部门管理<br/>树形结构,人员管理]
        A5[字典管理<br/>类型管理,字典项管理]
        A6[日志管理<br/>操作日志,登录日志,ES存储]
        A7[通知管理<br/>通知发布,用户通知,已读未读]
        A8[任务管理<br/>定时任务配置,任务监控]
        A9[系统监控<br/>服务器监控,JVM监控]
        A10[JAR管理<br/>JAR加载,JAR监控]
        A11[文件管理<br/>文件上传,S3存储]
        A12[参数管理<br/>系统参数配置]
        A13[风控管理<br/>IP限流,URI限流]
        A14[地址管理<br/>地址解析,IP归属]
    end

    subgraph 代码生成模块
        B1[数据源管理<br/>多数据源,连接测试]
        B2[表结构管理<br/>表查询,字段配置,同步]
        B3[代码生成<br/>参数配置,模板渲染,ZIP下载]
        B4[代码预览<br/>代码查看,多模板支持]
    end

    subgraph 公共模块
        C1[缓存模块<br/>Redis缓存,缓存枚举,AOP缓存]
        C2[远程调用<br/>OpenFeign,微服务通信]
        C3[JAR管理<br/>动态JAR加载,运行时扩展]
        C4[日志总线<br/>事件发布,MQ异步写入ES]
        C5[日志过滤<br/>请求拦截,操作日志采集]
        C6[消息队列<br/>RabbitMQ,异步处理,错误重试]
        C7[任务调度<br/>异步任务,定时任务,Redis分布式锁]
        C8[限流模块<br/>Sentinel集成,流量控制]
    end

    subgraph 监控模块
        D1[监控服务端<br/>Spring Boot Admin Server]
        D2[监控客户端<br/>Spring Boot Admin Client]
    end

mindmap
    root((xtools-app<br/>基础应用平台))
        系统管理
            用户管理
                增删改查
                角色分配
                密码管理
                状态管理
            角色管理
                角色配置
                权限分配
                菜单分配
            菜单管理
                树形结构
                动态加载
                按钮权限
            部门管理
                树形结构
                人员管理
            字典管理
                类型管理
                字典项管理
            日志管理
                操作日志
                ES存储检索
            通知管理
                通知发布
                用户通知
            文件管理
                本地上传
                S3存储
            风控管理
                IP限流
                URI限流
        代码生成
            数据源管理
                多数据源
                连接测试
            表结构管理
                表同步
                字段配置
            代码生成
                Velocity模板
                ZIP下载
            代码预览
                多模板预览
        公共模块
            缓存管理
                Redis缓存
                缓存枚举
            远程调用
                OpenFeign
            日志处理
                日志总线
                日志过滤
            消息队列
                RabbitMQ
            任务调度
                异步任务
                定时任务

graph LR
    User[用户] --> Login[登录认证]
    User --> Menu[菜单访问]
    User --> Data[数据操作]
    Login --> Auth[认证授权]
    Auth --> Token[Token管理]
    Auth --> Redis[Redis缓存]
    Menu --> Perm[权限验证]
    Role[角色] --> Perm
    Data --> LogFilter[日志过滤器]
    LogFilter --> LogBus[日志总线]
    LogBus --> MQ[RabbitMQ]
    MQ --> LogMq[日志消费者]
    LogMq --> ES[Elasticsearch]
    Cache[Redis缓存] --> Data
    Gen[代码生成] --> DB[数据库]
    Gen --> Velocity[Velocity模板]

二、项目结构设计

2.1 整体架构

graph TD
    xtools-app[xtools-app<br/>基础应用平台<br/>v1.0.0] --> common[xtools-app-common<br/>公共模块]
    xtools-app --> sys[xtools-app-sys<br/>系统管理模块]
    xtools-app --> gen[xtools-app-gen<br/>代码生成模块]
    xtools-app --> monitor[xtools-app-monitor<br/>监控模块]
    xtools-app --> standalone[xtools-app-standalone<br/>单体部署模块]
    common --> cache[common-cache<br/>缓存模块]
    common --> call[common-call<br/>远程调用模块]
    common --> jar[common-jar<br/>JAR管理模块]
    common --> job[common-job<br/>任务调度模块]
    common --> log[common-log<br/>日志模块]
    common --> mq[common-mq<br/>消息队列模块]
    common --> sentinel[common-sentinel<br/>限流模块]
    common --> task[common-task<br/>异步任务模块]
    log --> log-bus[log-bus<br/>日志总线]
    log --> log-filter[log-filter<br/>日志过滤器]
    sys --> sys-api[sys-api<br/>系统API接口]
    sys --> sys-auth[sys-auth<br/>认证授权]
    sys --> sys-biz[sys-biz<br/>系统业务逻辑]
    sys --> sys-boot[sys-boot<br/>系统微服务启动]
    sys --> sys-call[sys-call<br/>系统远程调用]
    sys --> sys-file[sys-file<br/>文件管理]
    sys --> sys-file-web[sys-file-web<br/>文件Web服务]
    sys --> sys-log-es[sys-log-bus-elasticsearch<br/>日志ES存储]
    sys --> sys-param[sys-param<br/>系统参数]
    sys --> sys-scheduled[sys-scheduled<br/>定时任务]
    sys --> sys-risk[sys-risk<br/>风控管理]
    gen --> gen-biz[gen-biz<br/>代码生成业务]
    gen --> gen-boot[gen-boot<br/>代码生成微服务启动]
    monitor --> monitor-boot[monitor-boot<br/>监控服务端]
    monitor --> monitor-client[monitor-client<br/>监控客户端]

2.2 分层架构

flowchart TB
    subgraph Controller层
        A1[接收HTTP请求]
        A2[参数验证<br/>Valid]
        A3[调用Service层]
        A4[返回统一响应<br/>Result]
    end

    subgraph Service层
        B1[业务逻辑处理]
        B2[事务控制<br/>Transactional]
        B3[调用Mapper层]
        B4[缓存操作<br/>Redis]
    end

    subgraph Mapper层
        C1[MyBatis-Plus<br/>BaseMapper]
        C2[数据库访问]
        C3[SQL执行]
    end

    subgraph 横切关注点
        D1[AuthFilter<br/>认证过滤器]
        D2[LogBus<br/>日志总线]
        D3[Sentinel<br/>流量控制]
        D4[MqErrorHandle<br/>消息错误处理]
    end

    A1 --> A2 --> A3 --> B1
    B1 --> B2 --> B3 --> C1
    C1 --> C2 --> C3
    A1 -.-> D1
    A1 -.-> D2
    A1 -.-> D3
    B1 -.-> D4

2.3 模块职责

层级	模块	职责说明
Controller层	SysUserController、SysLoginController等	接收HTTP请求、参数验证（@Valid）、调用Service层、返回统一响应（Result）
Service层	SysUserServiceImpl、SysLoginServiceImpl等	实现业务逻辑、事务控制（@Transactional）、调用Mapper层、缓存操作
BaseService层	SysUserBaseService等	继承MyBatis-Plus ServiceImpl，提供基础CRUD操作
Mapper层	SysUserMapper、SysRoleMapper等	继承MyBatis-Plus BaseMapper，数据库访问、SQL执行
Entity层	SysUser、SysRole、SysMenu等	数据库实体映射
DTO层	Req（请求）、Resp（响应）、Excel	数据传输对象
Convert层	SysUserConvert、SysRoleConvert等	MapStruct对象转换
Config层	SysConfig、ApiConfig等	配置类
MQ层	SysLogMq、SysTaskMq等	消息队列消费者
Job层	BaseJob、SysLogJob等	定时任务、异步任务
Utils层	PasswdUtils、AuthUtils等	工具类

2.4 包结构设计

xtools.app.{module}
├── controller          # 控制器层
├── service             # 服务接口
│   ├── base            # 基础服务（继承ServiceImpl）
│   └── impl            # 服务实现
├── mapper              # 数据访问层
├── model
│   ├── entity          # 实体类
│   ├── dto
│   │   ├── req         # 请求DTO（AddReq、UpdateReq、PageReq）
│   │   ├── resp        # 响应DTO
│   │   └── excel       # Excel导入导出DTO
│   └── vo              # 视图对象
├── convert             # MapStruct转换器
├── config              # 配置类
├── utils               # 工具类
├── mq                  # 消息队列处理
├── job                 # 定时任务
└── es                  # Elasticsearch相关

2.5 启动模块

项目支持两种部署模式：

模块	说明
xtools-app-standalone	单体部署模式，包含所有模块，通过 spring-boot-maven-plugin 打包为可执行JAR
xtools-app-sys-boot	微服务模式 - 系统管理服务
xtools-app-gen-boot	微服务模式 - 代码生成服务
xtools-app-monitor-boot	微服务模式 - 监控服务

三、项目功能设计

3.1 认证授权设计

认证流程

flowchart TD
    A[用户请求登录] --> B[前端获取SM2公钥]
    B --> C[用户输入账号密码<br/>使用SM2公钥加密]
    C --> D{验证验证码}
    D -->|验证码已过期| E[返回验证码已过期]
    D -->|验证码错误| F[返回验证码错误]
    D -->|验证成功| G[后端SM2解密密码]
    G --> H{查询账号}
    H -->|账户不存在| I[返回账户不存在]
    H -->|账户被禁用| J[返回账户被禁用]
    H -->|账户正常| K{SM3密码比对}
    K -->|密码错误| L[返回密码错误]
    K -->|密码正确| M[查询用户角色]
    M --> N[生成Token<br/>缓存用户信息到Redis]
    N --> O[返回TokenDto]

验证码机制

系统支持两种验证码模式（随机切换）：

• GIF动态验证码：基于 Easy Captcha 生成动态图片验证码
• 算术验证码：随机生成加减法算术题图片

验证码通过 Redis 缓存（AppCache.UID_CAPTCHA，过期时间60秒）。

RBAC权限模型

graph TD
    User[用户 SysUser] -->|多对多| UserRole[用户角色关联<br/>SysUserRole]
    UserRole -->|多对多| Role[角色 SysRole]
    Role -->|多对多| RoleMenu[角色菜单关联<br/>SysRoleMenu]
    RoleMenu -->|多对多| Menu[菜单权限 SysMenu]
    Menu --> M1[页面菜单]
    Menu --> M2[按钮权限]
    Menu --> M3[接口权限]

权限验证流程

flowchart TD
    A[用户发起请求] --> B{判断请求类型}
    B -->|微服务请求| C[验证Cloud Token]
    B -->|常规请求| D[获取请求URI]
    C --> C1{Token有效?}
    C1 -->|无效| C2[返回UNAUTHORIZED]
    C1 -->|有效| C3[传递头部信息]
    C3 --> C4[校验掩码设置]
    C4 --> C5[放行请求]
    D --> D1{URI在权限白名单?}
    D1 -->|是| D2[放行请求]
    D1 -->|否| D3{获取UID}
    D3 -->|UID为空| D4[返回METHOD_NOT_ALLOWED]
    D3 -->|UID存在| D5{URI在登录白名单?}
    D5 -->|是| D2
    D5 -->|否| D6{验证AccessToken}
    D6 -->|无效| D7[返回UNAUTHORIZED]
    D6 -->|有效| D8{校验URI访问权限}
    D8 -->|无权限| D9[返回FORBIDDEN]
    D8 -->|有权限| D10[设置上下文信息]
    D10 --> D11[校验掩码设置]
    D11 --> D2

认证模式

系统支持两种认证模式，通过请求头 Cloud 标识区分：

• 微服务认证：验证 Cloud Token（一次性令牌，Redis Hash存储）
• 常规认证：验证 UID + AccessToken + URI权限

3.2 日志管理设计

日志处理流程

flowchart LR
    A[HTTP请求] --> B[LogFilter<br/>日志过滤器]
    B --> C[采集请求信息<br/>URI,参数,IP,UserAgent]
    C --> D[LogBus<br/>日志总线]
    D --> E[RabbitMQ<br/>异步消息队列]
    E --> F[SysLogMq<br/>日志消费者]
    F --> G[LogBusService<br/>日志处理服务]
    G --> H[Elasticsearch<br/>日志存储]

日志类型

类型	说明	处理方式
操作日志	用户操作行为记录	LogFilter采集 -> MQ -> ES
系统日志	系统运行日志	LogBus记录 -> MQ -> ES
任务日志	定时任务执行日志	BaseJob记录 -> LogBus -> MQ -> ES
错误日志	异常和错误信息	异常捕获 -> LogBus -> MQ -> ES

日志配置

• 日志总线：基于 xtools-boot-log 封装，支持通过 LogBus.init() 链式调用记录日志
• 消息队列：使用 RabbitMQ 异步处理，并发度配置为 5-10
• 存储：日志存储到 Elasticsearch，通过 EsSysLogRepository 和 EsSysLogServiceImpl 实现
• 日志追踪：使用 LogTrackHolder（基于 ScopedValue）实现日志链路追踪

3.3 代码生成设计

代码生成流程

flowchart TD
    A[配置数据源] --> B[测试连接]
    B --> C[同步数据库]
    C --> D{读取表信息}
    D --> E[获取表列表<br/>DatabaseMetaData]
    E --> F[过滤排除表]
    F --> G[生成表信息<br/>GenTable]
    G --> H[获取字段信息<br/>DatabaseMetaData]
    H --> I[处理字段类型<br/>类型映射,表单类型]
    I --> J[生成字段信息<br/>GenTableColumn]
    J --> K[保存到数据库]
    K --> L{用户操作}
    L -->|预览代码| M[Velocity渲染模板]
    L -->|下载代码| N[Velocity渲染模板]
    L -->|修改配置| O[保存表和字段配置]
    M --> P[返回代码列表<br/>GenCodeDto]
    N --> Q[打包ZIP下载]

模板引擎

• 使用 Apache Velocity 2.4.1 模板引擎
• 通过 GenProperties 配置模板路径和生成参数
• 支持多种模板类型：Entity、Service、ServiceImpl、Mapper、Controller、Vue、TS API、SQL等
• 支持微服务 API 模块生成（可配置开关 openApi）
• 支持字典数据、脱敏数据等高级配置

代码生成特性

特性	说明
多数据源	支持 MySQL 等多种数据库类型
表结构同步	自动读取表和字段元数据
智能类型映射	自动将数据库类型映射为 Java 类型
表单类型推断	根据字段类型自动推断表单组件
查询方式推断	String类型默认LIKE，时间类型默认范围查询
模板配置	可配置后端和前端项目名称、模块路径等
ZIP下载	生成的代码打包为ZIP文件下载

3.4 任务调度设计

任务实现

flowchart TD
    A[任务触发] --> B[BaseJob.run]
    B --> C[初始化日志追踪<br/>ScopedValue]
    C --> D[获取Redis锁<br/>tryLock]
    D --> E{获取锁成功?}
    E -->|否| F[记录日志:已存在]
    E -->|是| G[执行runJob方法]
    G --> H{执行成功?}
    H -->|异常| I[记录错误日志]
    H -->|成功| J[记录成功日志]
    I --> K[释放锁<br/>releaseLock]
    J --> K

任务类型

类型	实现方式	说明
异步任务	BaseJob implements Runnable	支持分布式锁，防止重复执行
XXL-JOB	xtools-boot-job-xxl（可选）	分布式任务调度平台
定时任务	SysScheduled	Spring Task 定时任务管理
Spring任务	JobInterface.execute()	Spring 原生任务执行接口

任务调度特性

• 分布式锁：使用 Redis tryLock / releaseLock 实现分布式锁，防止多实例重复执行
• 日志追踪：通过 ScopedValue（JDK 25特性）实现任务执行上下文传递
• 异常处理：任务执行异常自动记录错误日志
• 超时控制：支持自定义锁超时时间

3.5 缓存设计

缓存策略

缓存Key	说明	过期时间
xtools-app:uid:{uid}:sm2	SM2公钥缓存	5分钟
xtools-app:uid:{uid}:captcha	验证码缓存	60秒
xtools-app:auth:sys:user:{token}	用户认证信息	1小时
xtools-app:auth:sys:uri	权限URI缓存	永不过期
xtools-app:auth:cloud:token	微服务Token	60秒
xtools-app:mq:msg:err:{id}	MQ消息错误次数	60秒
xtools-app:lock:job:{className}	任务分布式锁	5分钟
xtools-app:risk:ip:{ip}	风控IP	永不过期
xtools-app:risk:uri:{uri}	风控URI	永不过期
xtools-app:sys:cache:param:{key}	系统参数缓存	永不过期
xtools-app:sys:cache:jar:{name}	JAR包缓存	永不过期
xtools-app:sys:cache:addr:{key}	地址缓存	1小时

缓存架构

graph TD
    A[应用层] --> B[AppCache<br/>缓存枚举]
    B --> C[RedisService<br/>Redis操作服务]

    subgraph Redis缓存
        D1[认证缓存<br/>Token,用户信息]
        D2[业务缓存<br/>参数,地址,JAR]
        D3[风控缓存<br/>IP,URI限流]
        D4[分布式锁<br/>任务锁]
        D5[临时数据<br/>验证码,SM2密钥]
    end

    C --> D1
    C --> D2
    C --> D3
    C --> D4
    C --> D5

3.6 文件存储设计

项目支持多种文件存储方式（通过 xtools-app-standalone 可选配置）：

存储方式	模块	说明
S3存储	xtools-boot-storage-s3	兼容S3协议的对象存储
本地文件	xtools-boot-storage-file	本地文件系统存储（可选）

四、编码规范设计

4.1 命名规范

类命名

类型	命名规范	示例
实体类	Sys + 模块名	SysUser、SysRole、SysMenu
请求DTO	模块名 + Req	SysUserAddReq、SysUserPageReq
响应DTO	模块名 + Resp	GenTableInfoResp
Excel DTO	模块名 + Excel	SysDictExcel
Service接口	模块名 + Service	SysUserService
Service实现	模块名 + ServiceImpl	SysUserServiceImpl
Base Service	模块名 + BaseService	SysUserBaseService
Controller	模块名 + Controller	SysUserController
Mapper	模块名 + Mapper	SysUserMapper
转换器	模块名 + Convert	SysUserConvert
工具类	功能名 + Utils	PasswdUtils、AuthUtils
配置类	功能名 + Config 或 Properties	SysConfig、GenProperties

方法命名

操作	命名规范	示例
查询单个	getXxx	getUserInfo()
分页查询	pageXxx	pageSysUser()
新增	addXxx / saveXxx	addSysUser()
修改	updateXxx / editXxx	editUserInfo()
删除	delXxx / deleteXxx	delSysUser()
统计	countXxx	—

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 : 1.0.0
 * @date : 2026/1/31 21:18
 */

方法注释格式

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

常量注释格式

/**
 * 微服务标识
 */
private static final String CLOUD_FLAG = String.valueOf(Boolean.TRUE);

4.3 代码风格

• Lombok：使用 @RequiredArgsConstructor 构造器注入，减少样板代码
• MapStruct：使用接口定义对象转换器，编译时自动生成实现
• MyBatis-Plus：继承 ServiceImpl 和 BaseMapper，简化CRUD操作
• 依赖注入：使用 @RequiredArgsConstructor + final 字段（构造器注入）和 @Resource（特殊场景）
• 统一返回：使用 Result<T> 统一响应格式
• 统一异常：使用 BizError（业务错误）和 BizWarning（业务警告）异常类
• JDK特性：使用 ScopedValue、switch表达式、record 等JDK 25特性
• 常量管理：通过 BaseParams 接口提供通用常量（CP_NUM0、CP_NUM1 等）

4.4 设计规范

• 分层原则：Controller -> Service -> Mapper 严格分层，禁止跨层调用
• 单一职责：每个模块负责单一业务领域
• 开闭原则：通过继承 BaseJob、BaseMessageHandle 等基类扩展功能
• 接口隔离：Service接口与BaseService接口分离，基础CRUD与业务逻辑分离

4.5 安全规范

• 密码加密：使用 SM3 国密算法加密存储密码，SM2 非对称加密传输密码
• SQL安全：使用 MyBatis-Plus 参数化查询，防止SQL注入
• 数据验证：使用 @Valid 注解进行请求参数验证
• 权限控制：基于 RBAC 模型的接口级别权限控制
• 数据脱敏：集成掩码机制（MaskIgnore），支持动态开关

五、项目依赖设计

5.1 核心框架依赖

依赖	版本	用途
Spring Boot	4.0.5	应用框架
Spring Framework	7.0.6	核心框架
Spring Cloud	2025.1.1	微服务框架
Spring Cloud Alibaba	2025.1.0.0	微服务组件
Spring Data BOM	2025.1.4	数据访问版本管理
MyBatis-Plus	3.5.16	ORM增强工具
MyBatis Spring Boot Starter	4.0.1	MyBatis集成

5.2 数据存储依赖

依赖	版本	用途
Druid	1.2.28	数据库连接池
MySQL Connector/J	9.6.0	MySQL数据库驱动
Elasticsearch Client	9.2.6	ES搜索引擎客户端
Spring Data Redis	（Spring Boot管理）	Redis集成
Lettuce	6.8.2	Redis客户端
Spring AMQP	4.0.2	RabbitMQ集成
RabbitMQ Client	5.27.1	RabbitMQ客户端

5.3 微服务相关依赖

依赖	版本	用途
Nacos Client	3.1.1	服务注册与配置中心
Sentinel	1.8.9	流量控制与熔断降级
Seata	2.5.0	分布式事务（可用）
RocketMQ	5.3.1	消息队列（可用）

5.4 工具库依赖

依赖	版本	用途
Lombok	1.18.44	代码简化
MapStruct	1.6.3	对象映射
FastJSON2	2.0.60	JSON处理
Velocity	2.4.1	模板引擎（代码生成）
Jackson	2.21.2	JSON序列化
Commons Lang3	3.20.0	通用工具
Commons IO	2.21.0	IO工具
Commons Text	1.15.0	文本处理
Caffeine	3.2.3	本地缓存

5.5 安全相关依赖

依赖	版本	用途
BouncyCastle (bcprov-jdk18on)	1.84	国密算法（SM2/SM3）
Easy Captcha	1.6.2	验证码生成
java-jwt	4.5.1	JWT令牌

5.6 文档相关依赖

依赖	版本	用途
Knife4j	4.5.0	API文档增强
SpringDoc OpenAPI	3.0.3	OpenAPI文档
Swagger Annotations	2.2.48	API注解

5.7 系统监控依赖

依赖	版本	用途
Spring Boot Admin	4.0.3	应用监控
OSHI Core	6.11.1	系统信息采集
Micrometer	1.16.4	指标采集

5.8 文件处理依赖

依赖	版本	用途
Fesod Sheet	2.0.1-incubating	Excel处理
PDFBox	3.0.7	PDF处理
Thumbnailator	0.4.21	图片压缩
S3 SDK	2.42.34	S3对象存储客户端

5.9 其他工具依赖

依赖	版本	用途
XXL-Job Core	3.4.0	分布式任务调度
IP2Region	3.3.7	IP归属地查询
UserAgentUtils	1.21	浏览器标识解析
Pinyin4j	2.5.1	拼音转换
ZXing	3.5.4	二维码/条形码
JSoup	1.22.1	HTML解析
MMSEG4J	1.10.0	中文分词

5.10 xtools 内部框架依赖

依赖	版本	用途
xtools-core	5.0.0	核心工具库
xtools-web	5.0.0	Web工具库
xtools-extend	5.0.0	扩展工具库
xtools-api	5.0.0	API基础库
xtools-boot-api	5.0.0	Boot API基础（Result、异常）
xtools-boot-core	5.0.0	Boot核心（Holder、工具）
xtools-boot-cache-redis	5.0.0	Redis缓存封装
xtools-boot-db-mybatis-plus	5.0.0	MyBatis-Plus封装
xtools-boot-elasticsearch	5.0.0	Elasticsearch封装
xtools-boot-ip	5.0.0	IP工具封装
xtools-boot-knife4j	5.0.0	Knife4j封装
xtools-boot-log	5.0.0	日志封装
xtools-boot-mask	5.0.0	数据脱敏封装
xtools-boot-mq-base	5.0.0	消息队列基础
xtools-boot-mq-rabbit	5.0.0	RabbitMQ封装
xtools-boot-storage-base	5.0.0	存储基础
xtools-boot-storage-file	5.0.0	本地文件存储
xtools-boot-storage-s3	5.0.0	S3对象存储
xtools-boot-task	5.0.0	异步任务封装
xtools-boot-thread	5.0.0	线程池封装
xtools-boot-web-base	5.0.0	Web基础
xtools-boot-web-filter	5.0.0	Web过滤器基础
xtools-boot-job-xxl	5.0.0	XXL-Job集成
xtools-cloud-alibaba-nacos	5.0.0	Nacos集成
xtools-cloud-alibaba-sentinel	5.0.0	Sentinel集成
xtools-cloud-call	5.0.0	微服务远程调用

六、技术选型说明

6.1 JDK 25

• 选择原因：采用最新LTS版本，充分利用JDK新特性提升开发效率和运行性能
• 主要特性：
  • ScopedValue：用于任务执行的上下文传递（LogTrackHolder），替代ThreadLocal
  • Virtual Threads（虚拟线程）：轻量级线程，提升高并发处理能力
  • Switch表达式：简化条件分支代码
  • Record：用于不可变数据载体
  • Pattern Matching：增强的模式匹配能力
  • 性能优化：ZGC/Shenandoah垃圾回收器优化

6.2 Spring Boot 4.0.5

• Spring Framework版本：7.0.6
• 主要特性：
  • 支持JDK 17+，完美适配JDK 25
  • 响应式编程支持（WebFlux）
  • 可观测性增强（Micrometer 1.16.4集成）
  • 虚拟线程支持
  • Jakarta EE 10+ 规范支持
  • GraalVM Native Image 支持

6.3 MyBatis-Plus 3.5.16

• MyBatis版本：4.0.1
• 主要特性：
  • 简化CRUD操作，通过 ServiceImpl 和 BaseMapper 提供通用方法
  • Lambda查询包装器，类型安全的条件构造
  • 内置分页插件
  • 代码生成器（本项目自研代码生成模块）
  • 性能分析拦截器

6.4 Elasticsearch 9.2.6

• Spring Data BOM：2025.1.4
• 主要特性：
  • 全文搜索引擎，用于日志存储和检索
  • 高性能、分布式架构
  • 支持近实时搜索
  • 通过 Spring Data Elasticsearch 集成

6.5 Redis

• 客户端：Lettuce 6.8.2
• 主要特性：
  • 高性能缓存，支持多种数据结构
  • 分布式锁（tryLock/releaseLock）
  • 认证信息缓存、权限缓存
  • 会话管理、限流计数

6.6 RabbitMQ

• Spring AMQP：4.0.2
• RabbitMQ Client：5.27.1
• 主要特性：
  • 可靠消息传递（消息确认机制）
  • 灵活路由（Exchange + Queue + RoutingKey）
  • 并发消费控制（concurrency配置）
  • 错误处理和重试机制（MqErrorHandle）

6.7 Nacos 3.1.1

• 用途：服务注册与发现、配置中心
• 主要特性：
  • 服务注册与发现
  • 动态配置管理
  • 服务健康检查

6.8 Sentinel 1.8.9

• 用途：流量控制与熔断降级
• 主要特性：
  • 流量控制
  • 熔断降级
  • 系统保护
  • 热点参数限流

6.9 其他重要依赖版本

依赖	版本	用途
Spring Cloud Alibaba	2025.1.0.0	微服务框架
Nacos	3.1.1	服务注册与配置中心
Sentinel	1.8.9	流量控制与熔断
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	系统监控
Easy Captcha	1.6.2	验证码生成
Fesod Sheet	2.0.1-incubating	Excel处理
Jackson	2.21.2	JSON处理
Druid	1.2.28	数据库连接池
Spring Boot Admin	4.0.3	应用监控
java-jwt	4.5.1	JWT令牌
XXL-Job	3.4.0	分布式任务调度

---

文档版本：v1.0 编写日期：2026-04-16 项目版本：1.0.0 父POM版本：xtools-parent-cloud:5.0.0 JDK版本：25 维护团队：xujun.org