xtools-app 设计文档

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

一、功能和用途

1.1 项目概述

xtools-app 是一套基于 Spring Boot 构建的企业级基础应用平台，提供系统管理、代码生成、监控管理等核心功能。项目采用多模块架构，支持独立部署（Standalone）和微服务部署两种模式。

1.2 技术特点

• 采用最新的 JDK 25 版本，充分利用虚拟线程（Virtual Thread）、ScopedValue 等新特性
• 基于 Spring Boot 4.0.6 构建，支持自动配置和快速开发
• 集成 Spring Cloud Alibaba 2025.1.0.0 微服务框架
• 使用 MyBatis-Plus 3.5.16 简化数据访问层开发
• 集成 Elasticsearch 实现日志存储和检索（Spring Data BOM 2025.1.5）
• 支持 Nacos 3.1.1 服务注册与发现、Sentinel 1.8.9 流量控制和熔断降级
• 使用 Redis 实现分布式缓存和会话管理
• 使用 RabbitMQ（Spring AMQP 4.0.3）实现异步消息处理
• 支持 Knife4j 4.5.0 自动生成 API 文档
• 使用 SM2/SM3 国密算法保障密码安全

1.3 核心功能

1.4 功能关系图

1.5 功能层次图

二、项目结构设计

2.1 整体架构

2.2 分层架构

2.3 模块职责

2.4 包结构设计

xtools.app.{module}
├── controller          # 控制器
├── service             # 服务接口
│   ├── base            # 基础CRUD服务接口
│   └── impl            # 服务实现
├── mapper              # MyBatis Mapper
├── model
│   ├── entity          # 实体类
│   ├── dto
│   │   ├── req         # 请求DTO（AddReq, UpdateReq, PageReq）
│   │   ├── resp        # 响应DTO
│   │   └── excel       # Excel导入导出DTO
│   └── vo              # 视图对象
├── convert             # MapStruct 对象转换器
├── config              # 模块配置
├── utils               # 工具类
├── mq                  # RabbitMQ 消息消费者
├── job                 # 定时任务
├── enums               # 枚举类
├── init                # 初始化（ApplicationRunner）
└── aop                 # AOP切面

2.5 系统边界视图

三、项目功能设计

3.1 认证授权设计

3.1.1 登录认证流程

3.1.2 Token管理机制

Token 基于 UUID 生成，存储在 Redis 中，包含四种键类型：

Token 刷新流程：客户端使用 refreshToken 请求 GET /sys/login/refresh/{refreshToken}，后端查找对应的 accessToken，获取登录用户信息，生成新的 Token 对。

3.1.3 授权设计（RBAC模型）

3.1.4 权限验证流程

3.1.5 权限缓存初始化

系统启动时 InitSys（ApplicationRunner, Order: 200）执行权限缓存加载：

1. 查询所有 SysInterfacePerm 记录
2. 按 模块名:HTTP方法 分组
3. 以 JSON 字符串存入 Redis Hash（key: AUTH_SYS_URI）
4. 使用 ScopedValue 传递日志追踪上下文

3.2 日志管理设计

3.2.1 日志类型

3.2.2 日志处理流程

3.2.3 Elasticsearch日志存储

当配置 sys.log.type=elasticsearch 时，EsSysLogServiceImpl（标记 @Primary）替代默认的 SysLogServiceImpl：

• 使用 Spring Data Elasticsearch Repository 存储日志
• 支持分页查询：match_phrase（精确匹配）、wildcard（模糊匹配）、时间范围过滤
• 支持链路追踪查询：按 logIndex 和 logTime 排序，最多查询 10,000 条
• 支持按时间范围批量删除：_delete_by_query

3.3 代码生成设计

3.3.1 代码生成流程

3.3.2 模板引擎配置

• 使用 Apache Velocity 2.4.1 模板引擎
• 模板从 classpath 加载，UTF-8 编码
• 通过 GenProperties 配置后端/前端应用名、模块名、作者、版本等参数
• 支持过滤字段（正则匹配字段注释）
• 支持排除表（配置不生成的表名）

3.3.3 生成代码结构

{backendAppName}/{moduleName}/{moduleName}-biz/src/main/java/{packageName}/{subPackageName}/
├── controller/          # Controller类
├── service/             # Service接口
│   ├── base/            # 基础CRUD
│   └── impl/            # Service实现
├── mapper/              # Mapper接口
├── model/
│   ├── entity/          # 实体类
│   └── dto/
│       ├── req/         # 请求DTO
│       └── resp/        # 响应DTO
├── convert/             # MapStruct转换器
└── utils/               # 工具类

{frontendAppName}/src/{subPackageName}/{subModuleName}/
├── index.ts             # API接口
└── {tableName}/index.vue   # Vue页面

sql/                      # SQL脚本

3.4 任务调度设计

3.4.1 任务类型

3.4.2 定时任务实现

3.4.3 动态定时任务

SysScheduledService 提供动态定时任务管理：

• init()：启动时从数据库加载所有启用的定时任务
• start()：启动指定任务（创建 ScheduledTask 注册到 Spring TaskScheduler）
• stop()：停止指定任务（取消 ScheduledTask）
• restart()：重启指定任务
• run()：立即执行一次任务

任务初始化通过 InitSysScheduled（ApplicationRunner, Order: 200）在系统启动时自动完成。

3.5 缓存设计

3.5.1 缓存策略

项目使用 Redis 作为主要缓存介质，所有缓存键和 TTL 通过 AppCache 枚举集中管理：

3.5.2 Redis操作日志AOP

RedisServiceAop 切面环绕所有 RedisService 方法：

• 记录方法名、参数、返回值、执行时间
• 通过 LogBus 发布 REDIS 类型日志
• 仅在存在 LogTrack 上下文时记录

3.5.3 风控本地缓存

URI风控使用两级缓存架构：

• 一级缓存：Caffeine 本地缓存（20秒过期）
• 二级缓存：Redis String 缓存
• 查询顺序：Caffeine -> Redis

3.6 风控管理设计

• IP风控：启动时从数据库加载 IP 黑名单到 Redis Hash，支持动态添加/移除
• URI风控：使用 Caffeine + Redis 两级缓存，启动时从数据库加载 URI 黑名单字符串
• 风控数据来源：SysRisk 实体，按 SysRiskType（IP/URI）分类存储

3.7 文件管理设计

文件生命周期状态：TEMP（临时） -> OK（确认）或 DELETE（删除/过期）

3.8 系统监控设计

SysMonitorController（/sys/monitor）提供以下监控端点：

使用枚举类型选择不同的监控指标，委托给 boot 框架中的 RedisMonitor、MySqlMonitor、ElasticsearchMonitor 实现。

3.9 消息队列设计

队列定义：

错误处理：使用 SM3 哈希消息内容作为去重键，通过 Redis 计数器跟踪重试次数，最多重试 3 次。

四、编码规范设计

4.1 命名规范

类命名

方法命名

4.2 注释规范

类注释格式：

/**
 * <p>Title : 类名称</p>
 * <p>Description : 类描述</p>
 * <p>Company : org.xujun</p>
 *
 * @author : 作者名
 * @version : 版本号
 * @date : 日期
 */

方法注释格式：

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

4.3 代码风格

• Lombok：使用 @Data、@Builder、@Slf4j、@AllArgsConstructor、@NoArgsConstructor 等注解简化 POJO 代码
• MapStruct：使用 @Mapper 注解定义对象转换器，编译期生成转换代码
• MyBatis-Plus：使用 BaseMapper 简化 CRUD 操作，IService 封装 Service 层通用方法
• 构造器注入：使用 @RequiredArgsConstructor（Lombok）替代 @Autowired 字段注入
• 统一返回格式：所有 API 响应使用 Result<T> 统一封装
• 统一异常处理：BizError（业务错误）、BizWarning（业务警告）、UnauthorizedError（未授权）、BizPublicKeyError（密钥过期）
• API文档：使用 @Tag、@Operation、@Schema 注解生成 Knife4j API 文档

4.4 设计规范

• 分层原则：Controller -> Service -> Mapper，每层职责单一明确
• 单一职责：每个 Service 只负责一个业务领域
• 开闭原则：通过 @Primary 注解支持 Service 实现的运行时替换（如 EsSysLogServiceImpl 替换默认 SysLogServiceImpl）
• 基础抽象：BaseService + BaseServiceImpl 封装通用 CRUD，业务 Service 只关注差异化逻辑
• 过滤器链：使用 @Order 控制过滤器执行顺序（HttpLogFilter: 200 -> AuthFilter: 201）
• 初始化模式：ApplicationRunner + @Order 控制启动顺序

4.5 安全规范

五、项目依赖设计

5.1 核心框架依赖

5.2 工具库依赖

5.3 安全相关依赖

5.4 文档相关依赖

5.5 消息队列依赖

5.6 缓存依赖

5.7 系统监控依赖

5.8 数据库依赖

5.9 文件处理依赖

5.10 其他工具依赖

5.11 微服务相关依赖

5.12 xtools内部框架依赖

所有 xtools 内部模块版本均为 5.0.0：

六、技术选型说明

6.1 JDK 25

• 选择原因：最新LTS版本，提供长期支持和性能优化
• 主要新特性：
  • 虚拟线程（Virtual Threads）：轻量级线程，大幅提升并发能力，项目中用于异步日志记录（VirtualThreadTaskUtils.simple()）
  • Scoped Value：虚拟线程间的上下文传递，项目中用于 LogTrackHolder 上下文传播
  • Structured Concurrency：结构化并发编程
  • 改进的 ZGC/Shenandoah 垃圾回收器
  • Pattern Matching 增强
  • Record Classes 增强

6.2 Spring Boot 4.0.6

• Spring Framework 版本：7.0.7
• Spring Security 版本：7.0.5
• 主要特性：
  • 支持 Jakarta EE 11
  • 原生支持虚拟线程
  • 改进的可观测性（Observability）
  • 增强 GraalVM Native Image 支持
  • 改进的自动配置机制

6.3 MyBatis-Plus 3.5.16

• 支持的 MyBatis 版本：4.0.1
• 主要特性：
  • 简化 CRUD 操作（BaseMapper、IService）
  • 内置分页插件
  • 条件构造器（QueryWrapper、LambdaQueryWrapper）
  • 自动填充、逻辑删除、乐观锁
  • 代码生成器
  • SQL 性能分析

6.4 Elasticsearch

• Spring Data BOM 版本：2025.1.5
• 主要特性：
  • 全文搜索和倒排索引
  • 分布式架构，高可用
  • 近实时搜索
  • 项目中用于系统日志的存储和检索，支持分页查询、链路追踪和批量删除

6.5 Redis

• 版本说明：由 Spring Boot 4.0.6 管理
• 主要特性：
  • 高性能键值缓存
  • 支持多种数据结构（String、Hash、List、Set、ZSet）
  • 项目中用于：Token存储、权限缓存、风控数据、分布式锁、参数缓存等
  • 通过 RedisService 封装操作，AOP切面记录操作日志

6.6 RabbitMQ

• 版本说明：Spring AMQP 4.0.3（由Spring Boot管理）
• 主要特性：
  • 可靠消息传递（确认机制、持久化）
  • 灵活路由（Direct/Fanout/Topic交换机）
  • 消息确认和重试机制
  • 项目中用于：异步日志存储、异步任务记录
  • 自定义错误处理：SM3去重 + Redis计数器 + 最多3次重试

6.7 Nacos 3.1.1

• 选择原因：Spring Cloud Alibaba 生态核心组件
• 主要特性：
  • 服务注册与发现
  • 动态配置管理
  • 健康检查
  • 支持微服务部署模式

6.8 其他重要依赖版本

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