You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Repository Guidelines
文档定位
本文件聚焦“写代码时需要的架构与模块提示信息”，不包含 Git 流程、编译或测试命令。
系统架构总览
- 工程形态：Maven 多模块单体应用，前后端分离（
ruoyi-ui + Spring Boot 后端）。
- 模块分层：
ruoyi-admin：应用入口、Controller 暴露层。ruoyi-framework：安全认证、AOP、拦截器、数据权限与限流实现层。ruoyi-system：系统业务域（用户/角色/菜单/字典等）服务层。ruoyi-common：跨模块基础设施与通用契约层。ruoyi-quartz：任务调度能力层。ruoyi-generator：代码生成能力层。
- 关键依赖方向：
admin -> framework -> system -> common，quartz/generator -> common。
Backend Tech Stack (With Versions)
版本来源：根 pom.xml 的 properties 与 dependencyManagement。
| 技术 |
版本 |
说明 |
| Java |
17 |
语言与运行时基线 |
| Spring Boot BOM |
3.5.8 |
Spring 生态版本管理 |
| MyBatis Spring Boot Starter |
3.0.5 |
ORM/Mapper |
| Druid Spring Boot 3 Starter |
1.2.27 |
数据源与连接池 |
| PageHelper Starter |
2.1.1 |
分页 |
| MySQL Connector/J |
8.2.0 |
MySQL 驱动 |
| SpringDoc OpenAPI |
2.8.14 |
API 文档 |
| Spring Security |
由 Boot 3.5.8 管理 |
认证鉴权 |
| Spring Data Redis |
由 Boot 3.5.8 管理 |
缓存/会话 |
| JJWT |
0.9.1 |
JWT |
| Quartz |
2.5.2 |
定时任务 |
| Fastjson2 |
2.0.60 |
JSON |
| Apache POI |
4.1.2 |
Excel 导入导出 |
| Velocity |
2.3 |
代码生成模板 |
| Kaptcha |
2.3.3 |
验证码 |
| YAUAA |
7.32.0 |
User-Agent 解析 |
| OSHI |
6.9.1 |
主机监控信息 |
| Commons IO |
2.21.0 |
IO 工具 |
| Jakarta Servlet API |
6.0.0 |
Servlet 规范 |
ruoyi-common 模块深度分析
模块定位与边界
ruoyi-common 是后端基础设施层，提供统一契约、基类、工具和安全过滤，不承载业务流程。- 当前约
109 个 Java 类，属于项目复用中心模块。
包结构概览（一级包）
utils（36）：通用工具主集合。core（22）：Controller/Domain/Page/Redis/Text 基础抽象。exception（18）：统一异常体系。annotation（9）：横切能力注解契约。constant（6）/enums（8）：常量与策略枚举。filter（6）/xss（2）：请求过滤与输入安全。config（2）：通用配置与序列化器。
架构中心性（跨模块复用）
ruoyi-framework: 148 次 import com.ruoyi.common.*ruoyi-admin: 138 次ruoyi-system: 86 次ruoyi-quartz: 40 次ruoyi-generator: 25 次- 高频类：
StringUtils、AjaxResult、Constants、BaseController、SecurityUtils、ExcelUtil。
设计机制（写代码时重点）
- 契约与实现分离：
@DataScope/@RateLimiter/@RepeatSubmit/@Log 定义在 common，实现放在 framework 的 Aspect/Interceptor。
- 统一返回规范：Controller 继承
BaseController，统一输出 AjaxResult/TableDataInfo。
- 统一实体扩展位：
BaseEntity.params 用于数据权限 SQL 片段等横切参数传递。
- 统一安全输入链路：
SqlUtil、XssFilter、XssValidator、RepeatableFilter 负责请求与参数安全治理。
ruoyi-common 类级别索引清单（按包）
annotation
| 类 |
使用场景 |
Anonymous |
标记匿名可访问接口 |
DataScope |
服务查询方法注入数据权限条件 |
DataSource |
动态切换主从数据源 |
Excel/Excels |
实体字段导入导出映射 |
Log |
业务操作日志切面采集 |
RateLimiter |
接口限流（全局或按 IP） |
RepeatSubmit |
防重复提交 |
Sensitive |
返回字段脱敏 |
config
| 类 |
使用场景 |
RuoYiConfig |
读取 ruoyi.* 业务基础配置（上传路径、验证码类型等） |
SensitiveJsonSerializer |
配合 @Sensitive 做序列化脱敏 |
constant
| 类 |
使用场景 |
Constants |
全局常量（JWT 字段、权限标识、资源前缀等） |
CacheConstants |
Redis key 前缀统一管理 |
HttpStatus |
返回状态码常量 |
GenConstants |
代码生成器常量 |
ScheduleConstants |
调度任务常量 |
UserConstants |
用户/角色状态常量 |
core.controller
| 类 |
使用场景 |
BaseController |
分页、排序、安全用户获取、统一响应快捷方法 |
core.domain
| 类 |
使用场景 |
AjaxResult |
标准接口返回体（Map 风格） |
R<T> |
泛型响应体（类型化返回） |
BaseEntity |
审计字段与 params 扩展参数 |
TreeEntity/TreeSelect |
树结构实体与前端下拉树数据 |
core.domain.entity
| 类 |
使用场景 |
SysUser |
用户领域共享实体（含校验、Excel 注解） |
SysRole |
角色与数据权限范围 |
SysDept |
部门树领域实体 |
SysMenu |
菜单与权限节点 |
SysDictType/SysDictData |
字典类型与字典项 |
core.domain.model
| 类 |
使用场景 |
LoginBody |
登录请求体 |
RegisterBody |
注册请求体 |
LoginUser |
安全上下文主体（token、权限、登录态） |
core.page
| 类 |
使用场景 |
PageDomain |
分页参数承载 |
TableSupport |
从请求提取分页参数 |
TableDataInfo |
表格分页响应结构 |
core.redis
| 类 |
使用场景 |
RedisCache |
对 RedisTemplate 的统一封装（对象/列表/集合/Map/过期） |
core.text
| 类 |
使用场景 |
Convert |
安全类型转换 |
StrFormatter |
{} 占位符格式化 |
CharsetKit |
字符集处理 |
enums
| 类 |
使用场景 |
BusinessType/OperatorType |
操作日志分类 |
DataSourceType |
主从数据源策略 |
LimitType |
限流维度（默认/IP） |
HttpMethod |
请求方法匹配 |
UserStatus/BusinessStatus |
状态语义统一 |
DesensitizedType |
脱敏策略函数集合 |
exception
| 类 |
使用场景 |
BaseException |
业务基础异常（支持国际化 code） |
ServiceException |
服务层运行时异常（可带状态码） |
UtilException |
工具类异常 |
DemoModeException/GlobalException |
演示模式与全局业务异常 |
file.* |
文件上传、大小、扩展名异常 |
user.* |
登录、验证码、密码重试、黑名单异常 |
job.TaskException |
定时任务执行异常 |
filter
| 类 |
使用场景 |
RepeatableFilter/RepeatedlyRequestWrapper |
JSON 请求体可重复读取 |
XssFilter/XssHttpServletRequestWrapper |
请求参数与 JSON 体 XSS 清洗 |
RefererFilter |
防盗链 Referer 校验 |
PropertyPreExcludeFilter |
JSON 属性排除辅助 |
utils（重点工具类补充）
| 类 |
使用场景 |
StringUtils |
字符串/集合空判断、模板格式化、命名转换 |
DateUtils |
日期解析与格式化 |
SecurityUtils |
获取当前用户、权限匹配、密码加密 |
ServletUtils |
request/response/session 获取与渲染 |
PageUtils |
分页启动与清理 |
DictUtils |
字典缓存读写与标签值转换 |
FileUploadUtils |
统一上传路径、命名、扩展名校验 |
FileUtils/ImageUtils/MimeTypeUtils |
文件读写、图片处理、类型识别 |
ExcelUtil |
Excel 导入导出核心工具 |
SqlUtil |
orderBy 白名单校验与关键字过滤 |
IpUtils/AddressUtils |
IP 解析与归属地查询 |
HttpUtils/HttpHelper/UserAgentUtils |
HTTP 调用、请求体读取、UA 解析 |
SpringUtils |
非托管代码获取 Bean/环境信息 |
BeanUtils/BeanValidators/ReflectUtils |
Bean 复制、校验、反射访问 |
IdUtils/UUID/Seq |
唯一 ID 与序列号 |
Md5Utils/Base64 |
摘要与编码 |
xss
| 类 |
使用场景 |
Xss |
字段级 XSS 校验注解 |
XssValidator |
XSS 校验实现 |
写代码时的实用提示（聚焦 common）
- 返回值统一：优先使用
AjaxResult/TableDataInfo，避免模块间返回结构不一致。
- 分页与排序安全：动态排序字段必须走
SqlUtil.escapeOrderBySql 逻辑。
- Redis key 必须使用
CacheConstants 前缀，避免不同模块 key 冲突。
- 上传逻辑优先复用
FileUploadUtils，不要在业务层重复拼接文件路径。
- 涉及脱敏字段优先用
@Sensitive，不要在 Controller 手工字符串处理。
- 新增通用能力时，先判断是否应放在
ruoyi-common（跨模块复用）还是业务模块（仅单域使用）。