rui-docs/backend/spring-rui 代码分析报告.md

spring-rui 代码分析报告

分析日期：2026-05-26 目标：分析 ~/rhkj/spring-rui（排除 app/ 目录），对比 {root}，识别可复用模式和缺失能力。

---

一、项目架构对比

维度	spring-rui	{root}（本项目）
包名	org.rui	com.rui
模块组织	单体 rui-common 内含 15 子模块	平铺 4 子模块 core/mybatis/security/web
ORM	MyBatis Plus + 自定义类型处理器	MyBatis Plus
响应模型	Result<T> extends JSONObject	R<T> POJO
JSON 框架	fastjson2（核心依赖）	Jackson
多租户	配置驱动（TABLE/IGNORE/NONE 三种模式）	硬编码忽略表列表
缓存	Redis Manager（发布/订阅）	无

---

二、spring-rui 各模块分析

2.1 rui-common-core

文件	说明	{root} 状态
Result.java	响应模型，extends JSONObject，含 error/message/code/data/rows/results，支持链式调用	已有 R<T>，功能较弱
ResultResponse.java	简单响应 holder	已有 ResultCode
ResponseStatus.java	枚举：SUCCESSFUL/UNAUTHORIZED/FORBIDDEN/NOT_FOUND/VALIDATE_FAILED 等	可参考补全
TenantContextHolder.java	租户上下文 ThreadLocal	已有 TenantContextHolder
TenantBroker.java	支持在指定租户下执行代码	无，可选
IdWorker.java	ID 生成器	无
JacksonConfig.java	Jackson 全局配置	可参考
KeyStrResolver.java / TenantKeyStrResolver.java	缓存 Key 解析（含租户隔离）	无，可复用
SpringUtil.java	Spring 上下文工具	无
ServletUtil.java	Servlet 请求工具（提取所有参数为 Map）	无
JsonUtil.java	JSON 合并/赋值工具（JsonUtil.assign()）	无
AmountUtil.java / NumberUtil.java / RandomUtil.java	金额/数字/随机工具	无
IPSeekerUtil.java / IpUtil.java	IP 归属地查询	无
StringUtil.java	字符串增强工具	已有 hutool
LocalDateTimeUtil.java	时间工具	无
Validate.java / BaseRegex.java / NumericUtil.java	正则/校验工具	无
HttpClient.java	HTTP 客户端封装	无
CertHelper.java / CertUtil.java / RsaUtil.java / AesUtil.java / MD5Util.java / ShaUtil.java / SignatureUtil.java	加密/证书工具链	无
DelayQueueManager.java / QueueTask.java	延迟队列	无
Scheduled.java / Task.java / TaskConfiguration.java / TaskFactory.java	定时任务调度	无
ProxyProperties.java / ProxyInterceptor.java / ProxyProperty.java	代理链支持	无（我们有 proxy chain ThreadLocal）
LocaleContextHolder.java / LocaleUtil.java	国际化支持	无
FileUtil.java / MimeUtil.java / ZipUtil.java / GzipUtil.java	文件/压缩工具	无
AntPathMatcher.java / PathMatcher.java	路径匹配	无
AccountProperty.java / AppProperty.java / MqttProperty.java / WsProperty.java	配置属性类	无

2.2 rui-common-data

文件	说明	{root} 状态
MybatisPlusConfiguration.java	MP 插件配置（分页 + 多租户 + 防全表更新）	已有，缺 BlockAttackInnerInterceptor
MybatisProperties.java	MP 配置属性（表前缀、租户模式、忽略表列表）	无
PageService.java	通用查询构建器（类型字段 + 排序 + 分页 + 返回 Result）	2026-05-26 已移植
PageOptions.java	查询选项（下拉框过滤）	无，可选
TenantHandler.java	配置驱动多租户（TABLE/IGNORE/NONE 三种模式）	可参考优化
BaseMultiTableInnerInterceptor.java	多表拦截器	无
TableInterceptor.java	表前缀替换（#prefix# 占位符）	无
AbstractObjectTypeHandler.java / JsonObjectTypeHandler.java / JsonArrayTypeHandler.java / StringArrayTypeHandler.java / LongTypeHandler.java / IntegerTypeHandler.java / BigDecimalArrayTypeHandler.java / ArrayTypeHandler.java	类型处理器	无

2.3 rui-common-security

文件	说明	{root} 状态
ResourceServerAutoConfiguration.java / ResourceServerConfiguration.java	OAuth2 资源服务器配置	无（不同安全架构）
AuthUtil.java / UserUtil.java	认证用户工具	部分（SecurityUtils）
OAuthBearerTokenResolver.java	Token 解析器	无
RedisOAuth2AuthorizationService.java	Redis 授权存储	无
CustomOAuth2FeignRequestInterceptor.java	Feign Token 传递	无
OAuthUserDetailsService.java	用户详情服务接口	无
DefaultOAuthUserDetailsServiceImpl.java	默认实现	无
WeixinOAuthUserDetailsServiceImpl.java	微信登录实现	无
RestTemplateUserDetailsServiceImpl.java	RestTemplate 远程调用实现	无
PermissionService.java	权限校验 Bean（@perm.isSystemTenant()）	无
AuthIgnore.java / Inner.java	注解	无
SecurityInnerAspect.java	内部调用切面	无
FeignClientConfiguration.java / FeignConfiguration.java	Feign 配置	无
RemoteUserService.java / RemoteClientService.java	Feign 远程调用接口	无
GlobalExceptionHandler.java	全局异常处理	已有

2.4 rui-service-system（参考 CRUD 模式）

重点分析 — CRUD 标准模式：

Controller
├── GET    /{module}/list           → PageService 分页列表
├── GET    /{module}/{id}           → doGet: service.getById(id)
├── POST   /{module}                → doAdd: service.doAdd(bean)
├── PUT    /{module}/{id}           → doUpdate: service.doUpdate(bean)
├── DELETE /{module}/remove/{id}    → doRemove: 物理删除
└── DELETE /{module}/{id}           → doDelete: 软删除

Service (extends ServiceImpl<Mapper, Entity>)
├── doAdd(bean)     → bean.setDefaultValue(); this.save(bean)
├── doUpdate(bean)  → bean.setUpdatedAt(); this.updateById(bean)
├── doRemove(id)    → this.removeById(id)
└── doDelete(id)    → baseMapper.doDelete(id)  // SQL: UPDATE SET deleted=!deleted

Mapper (extends BaseMapper<Entity>)
└── @Update("UPDATE #prefix#table SET deleted=!deleted WHERE id=#{id}")
    Integer doDelete(Serializable id);

模式要点：

• doRemove = 物理删除，doDelete = 软删除（toggle deleted 标记）
• 所有 Service 方法返回 Result<?> 而非实体
• Mapper 中使用 #prefix# 占位符，由 TableInterceptor 自动替换为实际表前缀
• Entity 实现 setDefaultValue() 方法初始化字段

2.5 rui-service-users（同上，CRUD 模式验证）

与 rui-service-system 完全一致的 CRUD 模式。每个模块有：

• model/ — 实体类（implements Serializable）
• mapper/ — MyBatis Plus Mapper
• service/ — 接口
• service/impl/ — 实现（extends ServiceImpl + doAdd/doUpdate/doRemove/doDelete）
• controller/ — 接口（extends BaseController + CRUD 端点）

2.6 rui-gateway

文件	说明	{root} 状态
GrayLoadBalancer.java	灰度负载均衡	无
GrayReactiveLoadBalancerClientFilter.java	灰度过滤器	无
GlobalExceptionHandler.java	网关异常处理	无

2.7 rui-oauth2

文件	说明	{root} 状态
OauthApplication.java	启动类（无额外配置）	已有 AuthApplication

---

三、已移植到 {root} 的内容

2026-05-26 批量移植

文件	位置	对应 spring-rui
PageResult.java	rui-common-core	新增（基于 Result 分页字段）
PageService.java	rui-common-mybatis	rui-common-data/PageService.java
BaseController.java	rui-common-web	rui-service-system/controller/BaseController.java
防全表更新	MyBatisPlusConfig.java	MybatisPlusConfiguration.java 中的 BlockAttackInnerInterceptor

---

四、后续可选移植项

优先级高（核心能力）

功能	来源模块	说明
SpringUtil.java	core	Spring 上下文静态获取
ServletUtil.java	core	请求参数提取工具（PageService 用）
JsonUtil.java	core	JSON 合并/赋值（assign 方法在更新场景很有用）
MybatisProperties.java	data	配置化表前缀/租户模式，替代硬编码

优先级中（开发提效）

功能	来源模块	说明
StringUtil.java / AmountUtil.java / NumberUtil.java	core	常用工具
LocalDateTimeUtil.java	core	时间工具
IdWorker.java	core	ID 生成器
IPSeekerUtil.java / IpUtil.java	core	IP 工具
ArrayTypeHandler.java 系列	data	MP 类型处理器（JSON/数组）
KeyStrResolver.java 系列	core	缓存 Key 租户隔离

优先级低（按需移植）

功能	来源模块	说明
加密工具链（RSA/AES/MD5/SHA/证书）	core	spring-rui 安全相关
HttpClient.java	core	HTTP 客户端
DelayQueueManager.java	core	延迟队列
定时任务调度	core	自定义任务框架
国际化	core	Locale 工具
灰度负载均衡	gateway	与部署环境强相关
Feign 远程调用	security	与认证架构耦合

---

五、CRUD 编程规范（推荐）

基于 spring-rui 模式，推荐 {root} 业务模块遵循以下规范：

Controller 规范

@RestController
@RequiredArgsConstructor
@RequestMapping("system/tenant")
public class SysTenantController extends BaseController {

    private final SysTenantService service;

    @GetMapping("/list")
    public R<PageResult<SysTenant>> list(HttpServletRequest request) {
        PageService<SysTenant> ps = new PageService<>(request);
        ps.setDefaultOrderColumn("updatedAt");
        ps.putBoolean("deleted").putQuery("deleted", false);
        ps.putLike("name");
        return ps.getResults(service);
    }

    @GetMapping("{id}")
    public R<SysTenant> get(@PathVariable Long id) {
        return R.ok(service.getById(id));
    }

    @PostMapping
    public R<Void> add(@RequestBody SysTenant bean) {
        return service.doAdd(bean);
    }

    @PutMapping("{id}")
    public R<Void> update(@RequestBody SysTenant bean) {
        return service.doUpdate(bean);
    }

    @DeleteMapping("{id}")
    public R<Void> delete(@PathVariable Long id) {
        return service.doDelete(id);
    }
}

Service 规范

public interface SysTenantService extends IService<SysTenant> {
    R<Void> doAdd(SysTenant bean);
    R<Void> doUpdate(SysTenant bean);
    R<Void> doDelete(Long id);
}

public class SysTenantServiceImpl extends ServiceImpl<SysTenantMapper, SysTenant>
        implements SysTenantService {

    public R<Void> doAdd(SysTenant bean) {
        bean.setDefaultValue();
        if (this.save(bean)) return R.ok("添加成功");
        return R.fail("添加失败");
    }

    public R<Void> doUpdate(SysTenant bean) {
        bean.setUpdatedAt(LocalDateTime.now());
        if (this.updateById(bean)) return R.ok("更新成功");
        return R.fail("更新失败");
    }

    public R<Void> doDelete(Long id) {
        if (baseMapper.doDelete(id) == 1) return R.ok("删除成功");
        return R.fail("删除失败");
    }
}

Mapper 规范

@Mapper
public interface SysTenantMapper extends BaseMapper<SysTenant> {
    @Update("UPDATE rui_system_tenant SET deleted = !deleted WHERE id = #{id}")
    int doDelete(@Param("id") Long id);
}

注：spring-rui 使用 #prefix# 占位符 + TableInterceptor 自动替换表前缀。本项目暂不引入该机制，直接在 SQL 中写完整表名。