rui-docs/backend/guides/rui-common-core使用手册.md

rui-common-core 使用手册

文件名：rui-common-core使用手册.md 存放位置：docs/rui-common-core使用手册.md

文档定位：本文档是 rui-common-core 模块的唯一权威参考，记录所有工具类、注解、事件、DTO 的功能与用法。

使用规则：

1. 开发前先查本文档：使用任何通用工具/注解/常量前，优先查阅本文档确认是否存在可用实现
2. 新增即更新：向 rui-common-core 模块新增/修改任何类、方法时，必须同步更新本文档
3. 禁止重复造轮子：本文档中已有的工具，禁止在业务模块中重新实现

---

1. 模块概述

rui-common-core 是睿核通用平台框架的核心基础模块，为所有上层模块提供通用的工具类、常量、异常、上下文持有器、注解、事件、DTO 等基础能力。

定位：无业务依赖，无 Spring 依赖（除 SpringUtil、LoginEvent 外），可被任意模块引用。

---

2. 功能清单

2.1 上下文持有器（holder）

类名	功能	说明
TenantContextHolder	租户上下文	线程隔离的租户 ID 存储，支持父子线程传递
LocaleContextHolder	本地化上下文	线程隔离的语言环境存储

2.2 工具类（util）

类名	功能	依赖
ServletUtil	Servlet 请求工具	获取 IP、参数、Header、请求体等
SpringUtil	Spring 上下文工具	获取 Bean、配置、Environment、判断环境
JsonUtil	JSON 工具	基于 Fastjson2，对象与 JSON 互转
DateUtil	日期时间工具	基于 JDK 8 java.time，格式化、解析、计算
IdWorker	雪花算法 ID 生成器	分布式唯一 ID，支持趋势递增
BeanUtil	Bean 拷贝工具	基于 Spring BeanUtils，支持列表拷贝
EncryptUtil	加密工具	MD5、SHA-256、AES、Base64
ValidateUtil	校验工具	手机号、邮箱、身份证、URL、密码等校验
StringUtil	字符串扩展工具	驼峰/下划线转换、脱敏、截取等
ThreadUtil	线程工具	线程池创建、优雅关闭、命名线程工厂
FileUtil	文件工具	读写、复制、移动、目录操作、大小格式化
UserNoGenerator	用户编号生成器	生成 U0001 格式编号，自动跳过保留靓号

2.3 异常（exception）

类名	功能
BizException	业务异常，统一业务错误抛出

2.4 常量（constants）

类名	功能
SecurityConstant	安全相关常量（Token 前缀、Header 名称等）

2.5 模型（model）

类名	功能
PageResult	统一分页结果封装

2.6 结果封装（result）

类名	功能
Result	统一 API 返回结果（code、msg、data）
ResultCode	统一错误码枚举

2.7 注解（annotation）

类名	功能	目标位置
DataScope	数据权限注解，自动拼接数据范围 SQL	Service 方法

2.8 事件（event）

类名	功能	说明
LoginEvent	登录事件	登录成功/失败时发布，供监听器记录日志

2.9 DTO（dto）

类名	功能	说明
OperLogDTO	操作日志 DTO	跨服务传输操作日志数据

2.10 拦截器上下文（interceptor）

类名	功能	说明
DataScopeContext	数据权限上下文	ThreadLocal 存储数据范围信息，需手动清理

---

3. 工具类详细说明

3.1 IdWorker（雪花算法）

// 生成唯一 ID
long id = IdWorker.nextIdLong();
String idStr = IdWorker.nextIdStr();

// 从 ID 中提取信息
long timestamp = IdWorker.extractTimestamp(id);
long workerId = IdWorker.extractWorkerId(id);

3.2 DateUtil（日期时间）

// 获取当前时间
String now = DateUtil.now();                          // 2024-01-01 12:00:00
String today = DateUtil.today();                      // 2024-01-01

// 格式化与解析
String str = DateUtil.format(LocalDateTime.now());
LocalDateTime dt = DateUtil.parse("2024-01-01 12:00:00");

// 计算
LocalDateTime tomorrow = DateUtil.plusDays(dt, 1);
long days = DateUtil.betweenDays(start, end);

3.3 JsonUtil（JSON 处理）

// 对象转 JSON
String json = JsonUtil.toJsonString(user);

// JSON 转对象
User user = JsonUtil.parseObject(json, User.class);
List<User> list = JsonUtil.parseList(json, User.class);
Map<String, Object> map = JsonUtil.parseMap(json);

3.4 EncryptUtil（加密）

// MD5
String md5 = EncryptUtil.md5("password");

// SHA-256
String sha256 = EncryptUtil.sha256("password");

// AES 对称加密
String encrypt = EncryptUtil.aesEncrypt("content", "1234567890123456");
String decrypt = EncryptUtil.aesDecrypt(encrypt, "1234567890123456");

// Base64
String base64 = EncryptUtil.base64Encode("content");

3.5 ValidateUtil（校验）

// 常用校验
boolean isMobile = ValidateUtil.isMobile("13800138000");
boolean isEmail = ValidateUtil.isEmail("test@example.com");
boolean isIdCard = ValidateUtil.isIdCard("110101199001011234");
boolean isUrl = ValidateUtil.isUrl("https://example.com");
boolean isIpv4 = ValidateUtil.isIpv4("192.168.1.1");

// 密码强度
boolean validPwd = ValidateUtil.isValidPassword("Abc123456");

3.6 SpringUtil（Spring 上下文）

// 获取 Bean
UserService service = SpringUtil.getBean(UserService.class);

// 获取配置
String value = SpringUtil.getProperty("server.port");

// 判断环境
boolean isDev = SpringUtil.isDev();
boolean isProd = SpringUtil.isProd();

3.7 BeanUtil（Bean 拷贝）

// 对象拷贝
UserDTO dto = BeanUtil.copyProperties(user, UserDTO.class);

// 列表拷贝
List<UserDTO> dtoList = BeanUtil.copyList(userList, UserDTO.class);

// 忽略 null 值拷贝（用于更新）
BeanUtil.copyNonNullProperties(source, target);

3.8 StringUtil（字符串扩展）

// 命名转换
String camel = StringUtil.underlineToCamel("user_name");   // userName
String underline = StringUtil.camelToUnderline("userName"); // user_name

// 脱敏
String mobile = StringUtil.desensitizeMobile("13800138000");  // 138****8000
String email = StringUtil.desensitizeEmail("test@example.com"); // t***@example.com

// 其他
String truncated = StringUtil.truncate("很长的字符串", 5); // 很长的字...

3.9 ThreadUtil（线程池）

// 创建线程池
ExecutorService pool = ThreadUtil.newFixedPool(4, "my-pool");
ScheduledExecutorService scheduled = ThreadUtil.newScheduledPool(2, "schedule");

// 推荐：自定义线程池
ThreadPoolExecutor executor = ThreadUtil.newThreadPool(
    4, 8, 60, 100, "business"
);

// 优雅关闭
ThreadUtil.shutdown(pool, 30);

3.10 FileUtil（文件操作）

// 读写
String content = FileUtil.readString("/path/file.txt");
FileUtil.writeString("/path/file.txt", "content");
FileUtil.appendString("/path/file.txt", "append");

// 目录
FileUtil.createDir("/path/dir");
FileUtil.delete("/path/file.txt");

// 信息
boolean exists = FileUtil.exists("/path/file.txt");
long size = FileUtil.size("/path/file.txt");
String sizeStr = FileUtil.formatSize(1024 * 1024); // 1.00 MB

3.11 UserNoGenerator（用户编号生成器）

// 生成格式化的用户编号（U0001、U0002...）
String userNo = UserNoGenerator.format(1);     // U0001

// 判断是否为保留靓号（豹子号、连号、含666/888/999）
boolean reserved = UserNoGenerator.isReserved("U1111"); // true

// 生成下一个可用编号（自动跳过保留号）
String next = UserNoGenerator.generate(1);     // U0001（如果 U0001 是靓号则自动跳过）

---

4. 注解使用说明

4.1 @DataScope（数据权限）

标记在 Service 方法上，由 MyBatis Plus 拦截器自动拼接数据范围 SQL。

@DataScope(deptField = "dept_id", userField = "create_by")
public List<User> list() {
    return baseMapper.selectList();
}

参数说明：

• deptField：部门字段名，默认 "dept_id"
• userField：用户字段名，默认 "create_by"

数据范围类型（由 DataScopeContext 设置）：

• 1：全部数据
• 2：本部门数据
• 3：本部门及子部门数据
• 4：仅本人数据
• 5：自定义数据

---

5. 事件使用说明

5.1 LoginEvent（登录事件）

登录成功或失败时发布，供其他模块监听记录日志。

// 发布事件
applicationEventPublisher.publishEvent(
    new LoginEvent(this, userId, username, 1, clientId, ip, 
                   location, browser, os, 1, "登录成功")
);

// 监听事件
@Component
public class LoginEventListener {
    @EventListener
    public void onLogin(LoginEvent event) {
        // 记录登录日志
    }
}

---

6. DTO 使用说明

6.1 OperLogDTO（操作日志 DTO）

用于跨服务传输操作日志数据。

OperLogDTO log = new OperLogDTO();
log.setTitle("用户管理");
log.setOperType(2);        // 修改
log.setOperTypeName("修改用户");
log.setRequestUrl("/user/admin/user");
log.setRequestMethod("PUT");
log.setUserId(userId);
log.setStatus(1);          // 成功

---

7. 上下文使用说明

7.1 TenantContextHolder（租户上下文）

// 设置租户ID
TenantContextHolder.setTenantId(100L);

// 获取租户ID
Long tenantId = TenantContextHolder.getTenantId();

// 清理（必须在线程结束时调用）
TenantContextHolder.clear();

7.2 DataScopeContext（数据权限上下文）

// 设置数据范围
DataScopeContext.setDataScope(2);    // 本部门
DataScopeContext.setUserId(userId);
DataScopeContext.setDeptId(deptId);

// 获取数据范围
Integer scope = DataScopeContext.getDataScope();

// 清理（必须在线程结束时调用，防止内存泄漏）
DataScopeContext.clear();

---

8. 使用方式

8.1 Maven 依赖

<dependency>
    <groupId>com.rui</groupId>
    <artifactId>rui-common-core</artifactId>
    <version>${revision}</version>
</dependency>

8.2 在业务模块中使用

import com.rui.common.core.util.*;

@Service
public class UserService {
    
    public void createUser(User user) {
        // 生成唯一 ID
        user.setId(IdWorker.nextIdLong());
        
        // 生成用户编号
        user.setUserNo(UserNoGenerator.generate(seq));
        
        // 日期处理
        user.setCreatedAt(DateUtil.nowDateTime());
        
        // 密码加密
        user.setPassword(EncryptUtil.md5(user.getPassword()));
        
        // 保存...
    }
}

---

9. 规范说明

9.1 工具类设计原则

1. 无状态：所有工具类均为无状态静态方法，线程安全
2. 不可实例化：通过 private 构造器防止实例化
3. 异常处理：内部捕获并转换为 RuntimeException，避免污染业务代码
4. 空安全：所有方法对 null 参数有处理，避免 NPE

9.2 新增规范

如需向本模块新增类，请遵循：

1. 包名规范：

   • 工具类：com.rui.common.core.util
   • 注解：com.rui.common.core.annotation
   • 事件：com.rui.common.core.event
   • DTO：com.rui.common.core.dto
   • 上下文：com.rui.common.core.holder / interceptor
   • 常量：com.rui.common.core.constants
   • 异常：com.rui.common.core.exception

2. 命名规范：

   • 工具类：以 Util 结尾，如 XxxUtil
   • 注解：以功能命名，如 @DataScope
   • 事件：以 Event 结尾，如 XxxEvent
   • DTO：以 DTO 结尾，如 XxxDTO

3. 方法规范：均为 public static（工具类）

4. 文档规范：类注释和方法注释使用中文

5. 测试规范：建议补充单元测试

6. 文档同步：新增/修改后必须同步更新本文档

---

10. 文档维护说明

10.1 何时更新本文档

场景	操作
新增工具类/注解/事件/DTO	在功能清单中添加条目，在详细说明中添加使用示例
修改现有类的方法签名	同步更新对应详细说明中的代码示例
删除类或方法	从文档中移除对应条目，并在版本历史中注明
发现文档与代码不一致	以代码为准，修正文档

10.2 版本历史

日期	版本	变更内容
2024-01	1.0	初始版本，包含基础工具类
2024-06	1.1	新增 IdWorker、BeanUtil、ThreadUtil
2026-05	1.2	补充完整工具类集合，新增文档
2026-06	1.3	新增 UserNoGenerator、DataScope 注解、LoginEvent、OperLogDTO、DataScopeContext；补充文档使用说明