From 075a41cdb02f6503239edd31747824471faed9b2 Mon Sep 17 00:00:00 2001 From: AprilWind <2100166581@qq.com> Date: Fri, 28 Jun 2024 10:07:21 +0800 Subject: [PATCH] =?UTF-8?q?docs=20=E4=BC=98=E5=8C=96mybatis=E6=B3=A8?= =?UTF-8?q?=E9=87=8A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../common/mybatis/annotation/DataColumn.java | 13 +- .../mybatis/annotation/DataPermission.java | 7 +- .../mybatis/core/domain/BaseEntity.java | 1 - .../mybatis/core/mapper/BaseMapperPlus.java | 163 ++++++++++++++++-- .../common/mybatis/core/page/PageQuery.java | 4 +- .../mybatis/core/page/TableDataInfo.java | 10 +- .../common/mybatis/enums/DataBaseType.java | 11 +- .../common/mybatis/enums/DataScopeType.java | 38 ++-- .../handler/InjectionMetaObjectHandler.java | 31 +++- .../handler/MybatisExceptionHandler.java | 5 +- .../handler/PlusDataPermissionHandler.java | 55 +++++- .../common/mybatis/helper/DataBaseHelper.java | 5 +- .../mybatis/helper/DataPermissionHelper.java | 22 ++- .../PlusDataPermissionInterceptor.java | 70 +++++++- .../mybatis/service/SysDataScopeService.java | 15 +- .../dubbo/RemoteDataScopeServiceImpl.java | 12 ++ 16 files changed, 401 insertions(+), 61 deletions(-) diff --git a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/annotation/DataColumn.java b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/annotation/DataColumn.java index aca470fd..f8c5cd00 100644 --- a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/annotation/DataColumn.java +++ b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/annotation/DataColumn.java @@ -3,9 +3,10 @@ package org.dromara.common.mybatis.annotation; import java.lang.annotation.*; /** - * 数据权限 - * + * 数据权限注解，用于标记数据权限的占位符关键字和替换值 + *

* 一个注解只能对应一个模板 + *

* * @author Lion Li * @version 3.5.0 @@ -16,12 +17,16 @@ import java.lang.annotation.*; public @interface DataColumn { /** - * 占位符关键字 + * 数据权限模板的占位符关键字，默认为 "deptName" + * + * @return 占位符关键字数组 */ String[] key() default "deptName"; /** - * 占位符替换值 + * 数据权限模板的占位符替换值，默认为 "dept_id" + * + * @return 占位符替换值数组 */ String[] value() default "dept_id"; diff --git a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/annotation/DataPermission.java b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/annotation/DataPermission.java index f4351e38..6fd3c3e0 100644 --- a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/annotation/DataPermission.java +++ b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/annotation/DataPermission.java @@ -3,7 +3,7 @@ package org.dromara.common.mybatis.annotation; import java.lang.annotation.*; /** - * 数据权限组 + * 数据权限组注解，用于标记数据权限配置数组 * * @author Lion Li * @version 3.5.0 @@ -13,6 +13,11 @@ import java.lang.annotation.*; @Documented public @interface DataPermission { + /** + * 数据权限配置数组，用于指定数据权限的占位符关键字和替换值 + * + * @return 数据权限配置数组 + */ DataColumn[] value(); } diff --git a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/core/domain/BaseEntity.java b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/core/domain/BaseEntity.java index 820b49af..13a79416 100644 --- a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/core/domain/BaseEntity.java +++ b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/core/domain/BaseEntity.java @@ -17,7 +17,6 @@ import java.util.Map; * * @author Lion Li */ - @Data public class BaseEntity implements Serializable { diff --git a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/core/mapper/BaseMapperPlus.java b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/core/mapper/BaseMapperPlus.java index bea96203..12290903 100644 --- a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/core/mapper/BaseMapperPlus.java +++ b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/core/mapper/BaseMapperPlus.java @@ -34,20 +34,42 @@ public interface BaseMapperPlus extends BaseMapper { Log log = LogFactory.getLog(BaseMapperPlus.class); + /** + * 获取当前类的泛型类型 V 的 Class 对象 + *

+ * 该方法使用反射机制从当前类（继承自 BaseMapperPlus 类）的泛型参数中获取第一个泛型类型 V 的 Class 对象 + * + * @return 当前类的泛型类型 V 的 Class 对象 + */ default Class currentVoClass() { return (Class) ReflectionKit.getSuperClassGenericType(this.getClass(), BaseMapperPlus.class, 1); } + /** + * 获取当前类的泛型类型 T 的 Class 对象 + *

+ * 该方法使用反射机制从当前类（继承自 BaseMapperPlus 类）的泛型参数中获取第一个泛型类型 T 的 Class 对象 + * + * @return 当前类的泛型类型 T 的 Class 对象 + */ default Class currentModelClass() { return (Class) ReflectionKit.getSuperClassGenericType(this.getClass(), BaseMapperPlus.class, 0); } + /** + * 使用默认的查询条件查询并返回结果列表 + * + * @return 返回查询结果的列表 + */ default List selectList() { return this.selectList(new QueryWrapper<>()); } /** - * 批量插入 + * 批量插入实体对象集合 + * + * @param entityList 实体对象集合 + * @return 插入操作是否成功的布尔值 */ default boolean insertBatch(Collection entityList) { Db.saveBatch(entityList); @@ -56,7 +78,10 @@ public interface BaseMapperPlus extends BaseMapper { } /** - * 批量更新 + * 批量根据ID更新实体对象集合 + * + * @param entityList 实体对象集合 + * @return 更新操作是否成功的布尔值 */ default boolean updateBatchById(Collection entityList) { Db.updateBatchById(entityList); @@ -65,7 +90,10 @@ public interface BaseMapperPlus extends BaseMapper { } /** - * 批量插入或更新 + * 批量插入或更新实体对象集合 + * + * @param entityList 实体对象集合 + * @return 插入或更新操作是否成功的布尔值 */ default boolean insertOrUpdateBatch(Collection entityList) { Db.saveOrUpdateBatch(entityList); @@ -74,7 +102,11 @@ public interface BaseMapperPlus extends BaseMapper { } /** - * 批量插入(包含限制条数) + * 批量插入实体对象集合并指定批处理大小 + * + * @param entityList 实体对象集合 + * @param batchSize 批处理大小 + * @return 插入操作是否成功的布尔值 */ default boolean insertBatch(Collection entityList, int batchSize) { Db.saveBatch(entityList, batchSize); @@ -83,7 +115,11 @@ public interface BaseMapperPlus extends BaseMapper { } /** - * 批量更新(包含限制条数) + * 批量根据ID更新实体对象集合并指定批处理大小 + * + * @param entityList 实体对象集合 + * @param batchSize 批处理大小 + * @return 更新操作是否成功的布尔值 */ default boolean updateBatchById(Collection entityList, int batchSize) { Db.updateBatchById(entityList, batchSize); @@ -92,7 +128,11 @@ public interface BaseMapperPlus extends BaseMapper { } /** - * 批量插入或更新(包含限制条数) + * 批量插入或更新实体对象集合并指定批处理大小 + * + * @param entityList 实体对象集合 + * @param batchSize 批处理大小 + * @return 插入或更新操作是否成功的布尔值 */ default boolean insertOrUpdateBatch(Collection entityList, int batchSize) { Db.saveOrUpdateBatch(entityList, batchSize); @@ -100,12 +140,23 @@ public interface BaseMapperPlus extends BaseMapper { return true; } + /** + * 根据ID查询单个VO对象 + * + * @param id 主键ID + * @return 查询到的单个VO对象 + */ default V selectVoById(Serializable id) { return selectVoById(id, this.currentVoClass()); } /** - * 根据 ID 查询 + * 根据ID查询单个VO对象并将其转换为指定的VO类 + * + * @param id 主键ID + * @param voClass 要转换的VO类的Class对象 + * @param VO类的类型 + * @return 查询到的单个VO对象，经过转换为指定的VO类后返回 */ default C selectVoById(Serializable id, Class voClass) { T obj = this.selectById(id); @@ -115,12 +166,23 @@ public interface BaseMapperPlus extends BaseMapper { return MapstructUtils.convert(obj, voClass); } + /** + * 根据ID集合批量查询VO对象列表 + * + * @param idList 主键ID集合 + * @return 查询到的VO对象列表 + */ default List selectVoBatchIds(Collection idList) { return selectVoBatchIds(idList, this.currentVoClass()); } /** - * 查询（根据ID 批量查询） + * 根据ID集合批量查询实体对象列表，并将其转换为指定的VO对象列表 + * + * @param idList 主键ID集合 + * @param voClass 要转换的VO类的Class对象 + * @param VO类的类型 + * @return 查询到的VO对象列表，经过转换为指定的VO类后返回 */ default List selectVoBatchIds(Collection idList, Class voClass) { List list = this.selectBatchIds(idList); @@ -130,12 +192,23 @@ public interface BaseMapperPlus extends BaseMapper { return MapstructUtils.convert(list, voClass); } + /** + * 根据查询条件Map查询VO对象列表 + * + * @param map 查询条件Map + * @return 查询到的VO对象列表 + */ default List selectVoByMap(Map map) { return selectVoByMap(map, this.currentVoClass()); } /** - * 查询（根据 columnMap 条件） + * 根据查询条件Map查询实体对象列表，并将其转换为指定的VO对象列表 + * + * @param map 查询条件Map + * @param voClass 要转换的VO类的Class对象 + * @param VO类的类型 + * @return 查询到的VO对象列表，经过转换为指定的VO类后返回 */ default List selectVoByMap(Map map, Class voClass) { List list = this.selectByMap(map); @@ -145,16 +218,34 @@ public interface BaseMapperPlus extends BaseMapper { return MapstructUtils.convert(list, voClass); } + /** + * 根据条件查询单个VO对象 + * + * @param wrapper 查询条件Wrapper + * @return 查询到的单个VO对象 + */ default V selectVoOne(Wrapper wrapper) { return selectVoOne(wrapper, this.currentVoClass()); } + /** + * 根据条件查询单个VO对象，并根据需要决定是否抛出异常 + * + * @param wrapper 查询条件Wrapper + * @param throwEx 是否抛出异常的标志 + * @return 查询到的单个VO对象 + */ default V selectVoOne(Wrapper wrapper, boolean throwEx) { return selectVoOne(wrapper, this.currentVoClass(), throwEx); } /** - * 根据 entity 条件，查询一条记录 + * 根据条件查询单个VO对象，并指定返回的VO对象的类型 + * + * @param wrapper 查询条件Wrapper + * @param voClass 返回的VO对象的Class对象 + * @param 返回的VO对象的类型 + * @return 查询到的单个VO对象，经过类型转换为指定的VO类后返回 */ default C selectVoOne(Wrapper wrapper, Class voClass) { T obj = this.selectOne(wrapper); @@ -165,7 +256,13 @@ public interface BaseMapperPlus extends BaseMapper { } /** - * 根据 entity 条件，查询一条记录 + * 根据条件查询单个实体对象，并将其转换为指定的VO对象 + * + * @param wrapper 查询条件Wrapper + * @param voClass 要转换的VO类的Class对象 + * @param throwEx 是否抛出异常的标志 + * @param VO类的类型 + * @return 查询到的单个VO对象，经过转换为指定的VO类后返回 */ default C selectVoOne(Wrapper wrapper, Class voClass, boolean throwEx) { T obj = this.selectOne(wrapper, throwEx); @@ -175,16 +272,32 @@ public interface BaseMapperPlus extends BaseMapper { return MapstructUtils.convert(obj, voClass); } + /** + * 查询所有VO对象列表 + * + * @return 查询到的VO对象列表 + */ default List selectVoList() { return selectVoList(new QueryWrapper<>(), this.currentVoClass()); } + /** + * 根据条件查询VO对象列表 + * + * @param wrapper 查询条件Wrapper + * @return 查询到的VO对象列表 + */ default List selectVoList(Wrapper wrapper) { return selectVoList(wrapper, this.currentVoClass()); } /** - * 根据 entity 条件，查询全部记录 + * 根据条件查询实体对象列表，并将其转换为指定的VO对象列表 + * + * @param wrapper 查询条件Wrapper + * @param voClass 要转换的VO类的Class对象 + * @param VO类的类型 + * @return 查询到的VO对象列表，经过转换为指定的VO类后返回 */ default List selectVoList(Wrapper wrapper, Class voClass) { List list = this.selectList(wrapper); @@ -194,15 +307,31 @@ public interface BaseMapperPlus extends BaseMapper { return MapstructUtils.convert(list, voClass); } + /** + * 根据条件分页查询VO对象列表 + * + * @param page 分页信息 + * @param wrapper 查询条件Wrapper + * @return 查询到的VO对象分页列表 + */ default

> P selectVoPage(IPage page, Wrapper wrapper) { return selectVoPage(page, wrapper, this.currentVoClass()); } /** - * 分页查询VO + * 根据条件分页查询实体对象列表，并将其转换为指定的VO对象分页列表 + * + * @param page 分页信息 + * @param wrapper 查询条件Wrapper + * @param voClass 要转换的VO类的Class对象 + * @param VO类的类型 + * @param

VO对象分页列表的类型 + * @return 查询到的VO对象分页列表，经过转换为指定的VO类后返回 */ default > P selectVoPage(IPage page, Wrapper wrapper, Class voClass) { + // 根据条件分页查询实体对象列表 List list = this.selectList(page, wrapper); + // 创建一个新的VO对象分页列表，并设置分页信息 IPage voPage = new Page<>(page.getCurrent(), page.getSize(), page.getTotal()); if (CollUtil.isEmpty(list)) { return (P) voPage; @@ -211,6 +340,14 @@ public interface BaseMapperPlus extends BaseMapper { return (P) voPage; } + /** + * 根据条件查询符合条件的对象，并将其转换为指定类型的对象列表 + * + * @param wrapper 查询条件Wrapper + * @param mapper 转换函数，用于将查询到的对象转换为指定类型的对象 + * @param 要转换的对象的类型 + * @return 查询到的符合条件的对象列表，经过转换为指定类型的对象后返回 + */ default List selectObjs(Wrapper wrapper, Function mapper) { return this.selectObjs(wrapper).stream().filter(Objects::nonNull).map(mapper).collect(Collectors.toList()); } diff --git a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/core/page/PageQuery.java b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/core/page/PageQuery.java index f66fd165..31be8dd4 100644 --- a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/core/page/PageQuery.java +++ b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/core/page/PageQuery.java @@ -20,7 +20,6 @@ import java.util.List; * * @author Lion Li */ - @Data @NoArgsConstructor public class PageQuery implements Serializable { @@ -58,6 +57,9 @@ public class PageQuery implements Serializable { */ public static final int DEFAULT_PAGE_SIZE = Integer.MAX_VALUE; + /** + * 构建分页对象 + */ public Page build() { Integer pageNum = ObjectUtil.defaultIfNull(getPageNum(), DEFAULT_PAGE_NUM); Integer pageSize = ObjectUtil.defaultIfNull(getPageSize(), DEFAULT_PAGE_SIZE); diff --git a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/core/page/TableDataInfo.java b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/core/page/TableDataInfo.java index a4b67997..8ecfb54a 100644 --- a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/core/page/TableDataInfo.java +++ b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/core/page/TableDataInfo.java @@ -14,7 +14,6 @@ import java.util.List; * * @author Lion Li */ - @Data @NoArgsConstructor public class TableDataInfo implements Serializable { @@ -53,6 +52,9 @@ public class TableDataInfo implements Serializable { this.total = total; } + /** + * 根据分页对象构建表格分页数据对象 + */ public static TableDataInfo build(IPage page) { TableDataInfo rspData = new TableDataInfo<>(); rspData.setCode(HttpStatus.HTTP_OK); @@ -62,6 +64,9 @@ public class TableDataInfo implements Serializable { return rspData; } + /** + * 根据数据列表构建表格分页数据对象 + */ public static TableDataInfo build(List list) { TableDataInfo rspData = new TableDataInfo<>(); rspData.setCode(HttpStatus.HTTP_OK); @@ -71,6 +76,9 @@ public class TableDataInfo implements Serializable { return rspData; } + /** + * 构建表格分页数据对象 + */ public static TableDataInfo build() { TableDataInfo rspData = new TableDataInfo<>(); rspData.setCode(HttpStatus.HTTP_OK); diff --git a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/enums/DataBaseType.java b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/enums/DataBaseType.java index 93487e94..5084424e 100644 --- a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/enums/DataBaseType.java +++ b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/enums/DataBaseType.java @@ -1,8 +1,8 @@ package org.dromara.common.mybatis.enums; -import org.dromara.common.core.utils.StringUtils; import lombok.AllArgsConstructor; import lombok.Getter; +import org.dromara.common.core.utils.StringUtils; /** * 数据库类型 @@ -33,8 +33,17 @@ public enum DataBaseType { */ SQL_SERVER("Microsoft SQL Server"); + /** + * 数据库类型 + */ private final String type; + /** + * 根据数据库产品名称查找对应的数据库类型 + * + * @param databaseProductName 数据库产品名称 + * @return 对应的数据库类型枚举值，如果未找到则返回 null + */ public static DataBaseType find(String databaseProductName) { if (StringUtils.isBlank(databaseProductName)) { return null; diff --git a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/enums/DataScopeType.java b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/enums/DataScopeType.java index 9ea66b0a..a67395fa 100644 --- a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/enums/DataScopeType.java +++ b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/enums/DataScopeType.java @@ -1,19 +1,23 @@ package org.dromara.common.mybatis.enums; -import org.dromara.common.core.utils.StringUtils; import lombok.AllArgsConstructor; import lombok.Getter; +import org.dromara.common.core.utils.StringUtils; import org.dromara.common.mybatis.helper.DataPermissionHelper; +import org.dromara.common.mybatis.service.SysDataScopeService; +import org.dromara.system.api.model.LoginUser; /** - * 数据权限类型 - *

- * 语法支持 spel 模板表达式 + * 数据权限类型枚举 *

- * 内置数据 user 当前用户 内容参考 LoginUser - * 如需扩展数据 可使用 {@link DataPermissionHelper} 操作 - * 内置服务 sdss 系统数据权限服务 内容参考 SysDataScopeService - * 如需扩展更多自定义服务 可以参考 sdss 自行编写 + * 支持使用 SpEL 模板表达式定义 SQL 查询条件 + * 内置数据： + * - {@code user}: 当前登录用户信息，参考 {@link LoginUser} + * 内置服务： + * - {@code sdss}: 系统数据权限服务，参考 {@link SysDataScopeService} + * 如需扩展数据，可以通过 {@link DataPermissionHelper} 进行操作 + * 如需扩展服务，可以通过 {@link SysDataScopeService} 自行编写 + *

* * @author Lion Li * @version 3.5.0 @@ -29,36 +33,50 @@ public enum DataScopeType { /** * 自定数据权限 + * 使用 SpEL 表达式：`#{#deptName} IN ( #{@sdss.getRoleCustom( #user.roleId )} )` + * 如果不满足条件，则使用默认 SQL 表达式：`1 = 0` */ CUSTOM("2", " #{#deptName} IN ( #{@sdss.getRoleCustom( #user.roleId )} ) ", " 1 = 0 "), /** * 部门数据权限 + * 使用 SpEL 表达式：`#{#deptName} = #{#user.deptId}` + * 如果不满足条件，则使用默认 SQL 表达式：`1 = 0` */ DEPT("3", " #{#deptName} = #{#user.deptId} ", " 1 = 0 "), /** * 部门及以下数据权限 + * 使用 SpEL 表达式：`#{#deptName} IN ( #{@sdss.getDeptAndChild( #user.deptId )}` + * 如果不满足条件，则使用默认 SQL 表达式：`1 = 0` */ DEPT_AND_CHILD("4", " #{#deptName} IN ( #{@sdss.getDeptAndChild( #user.deptId )} )", " 1 = 0 "), /** * 仅本人数据权限 + * 使用 SpEL 表达式：`#{#userName} = #{#user.userId}` + * 如果不满足条件，则使用默认 SQL 表达式：`1 = 0` */ SELF("5", " #{#userName} = #{#user.userId} ", " 1 = 0 "); private final String code; /** - * 语法 采用 spel 模板表达式 + * SpEL 模板表达式，用于构建 SQL 条件 */ private final String sqlTemplate; /** - * 不满足 sqlTemplate 则填充 + * 如果不满足 {@code sqlTemplate} 的条件，则使用此默认 SQL 表达式 */ private final String elseSql; + /** + * 根据枚举代码查找对应的枚举值 + * + * @param code 枚举代码 + * @return 对应的枚举值，如果未找到则返回 null + */ public static DataScopeType findCode(String code) { if (StringUtils.isBlank(code)) { return null; diff --git a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/handler/InjectionMetaObjectHandler.java b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/handler/InjectionMetaObjectHandler.java index ce754733..f6b2b121 100644 --- a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/handler/InjectionMetaObjectHandler.java +++ b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/handler/InjectionMetaObjectHandler.java @@ -20,22 +20,28 @@ import java.util.Date; @Slf4j public class InjectionMetaObjectHandler implements MetaObjectHandler { + /** + * 插入填充方法，用于在插入数据时自动填充实体对象中的创建时间、更新时间、创建人、更新人等信息 + * + * @param metaObject 元对象，用于获取原始对象并进行填充 + */ @Override public void insertFill(MetaObject metaObject) { try { - if (ObjectUtil.isNotNull(metaObject) - && metaObject.getOriginalObject() instanceof BaseEntity baseEntity) { + if (ObjectUtil.isNotNull(metaObject) && metaObject.getOriginalObject() instanceof BaseEntity baseEntity) { + // 获取当前时间作为创建时间和更新时间，如果创建时间不为空，则使用创建时间，否则使用当前时间 Date current = ObjectUtil.isNotNull(baseEntity.getCreateTime()) ? baseEntity.getCreateTime() : new Date(); baseEntity.setCreateTime(current); baseEntity.setUpdateTime(current); + + // 如果创建人为空，则填充当前登录用户的信息 if (ObjectUtil.isNull(baseEntity.getCreateBy())) { LoginUser loginUser = getLoginUser(); if (ObjectUtil.isNotNull(loginUser)) { Long userId = loginUser.getUserId(); - // 当前已登录 且 创建人为空 则填充 + // 填充创建人、更新人和创建部门信息 baseEntity.setCreateBy(userId); - // 当前已登录 且 更新人为空 则填充 baseEntity.setUpdateBy(userId); baseEntity.setCreateDept(ObjectUtil.isNotNull(baseEntity.getCreateDept()) ? baseEntity.getCreateDept() : loginUser.getDeptId()); @@ -47,15 +53,20 @@ public class InjectionMetaObjectHandler implements MetaObjectHandler { } } + /** + * 更新填充方法，用于在更新数据时自动填充实体对象中的更新时间和更新人信息 + * + * @param metaObject 元对象，用于获取原始对象并进行填充 + */ @Override public void updateFill(MetaObject metaObject) { try { - if (ObjectUtil.isNotNull(metaObject) - && metaObject.getOriginalObject() instanceof BaseEntity baseEntity) { + if (ObjectUtil.isNotNull(metaObject) && metaObject.getOriginalObject() instanceof BaseEntity baseEntity) { + // 获取当前时间作为更新时间，无论原始对象中的更新时间是否为空都填充 Date current = new Date(); - // 更新时间填充(不管为不为空) baseEntity.setUpdateTime(current); - // 当前已登录 更新人填充(不管为不为空) + + // 获取当前登录用户的ID，并填充更新人信息 Long userId = LoginHelper.getUserId(); if (ObjectUtil.isNotNull(userId)) { baseEntity.setUpdateBy(userId); @@ -67,7 +78,9 @@ public class InjectionMetaObjectHandler implements MetaObjectHandler { } /** - * 获取登录用户 + * 获取当前登录用户信息 + * + * @return 当前登录用户的信息，如果用户未登录则返回 null */ private LoginUser getLoginUser() { LoginUser loginUser; diff --git a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/handler/MybatisExceptionHandler.java b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/handler/MybatisExceptionHandler.java index ec3ee0df..518d52d2 100644 --- a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/handler/MybatisExceptionHandler.java +++ b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/handler/MybatisExceptionHandler.java @@ -1,15 +1,14 @@ package org.dromara.common.mybatis.handler; -import org.dromara.common.core.domain.R; +import jakarta.servlet.http.HttpServletRequest; import lombok.extern.slf4j.Slf4j; +import org.dromara.common.core.domain.R; import org.dromara.common.core.utils.StringUtils; import org.mybatis.spring.MyBatisSystemException; import org.springframework.dao.DuplicateKeyException; import org.springframework.web.bind.annotation.ExceptionHandler; import org.springframework.web.bind.annotation.RestControllerAdvice; -import jakarta.servlet.http.HttpServletRequest; - /** * Mybatis异常处理器 * diff --git a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/handler/PlusDataPermissionHandler.java b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/handler/PlusDataPermissionHandler.java index fd7dd34d..200006ff 100644 --- a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/handler/PlusDataPermissionHandler.java +++ b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/handler/PlusDataPermissionHandler.java @@ -68,13 +68,27 @@ public class PlusDataPermissionHandler { */ private final BeanResolver beanResolver = new BeanFactoryResolver(SpringUtils.getBeanFactory()); + /** + * 构造方法，扫描指定包下的 Mapper 类并初始化缓存 + * + * @param mapperPackage Mapper 类所在的包路径 + */ public PlusDataPermissionHandler(String mapperPackage) { scanMapperClasses(mapperPackage); } - + /** + * 获取数据过滤条件的 SQL 片段 + * + * @param where 原始的查询条件表达式 + * @param mappedStatementId Mapper 方法的 ID + * @param isSelect 是否为查询语句 + * @return 数据过滤条件的 SQL 片段 + */ public Expression getSqlSegment(Expression where, String mappedStatementId, boolean isSelect) { + // 获取数据权限配置 DataPermission dataPermission = getDataPermission(mappedStatementId); + // 获取当前登录用户信息 LoginUser currentUser = DataPermissionHelper.getVariable("user"); if (ObjectUtil.isNull(currentUser)) { currentUser = LoginHelper.getLoginUser(); @@ -84,6 +98,7 @@ public class PlusDataPermissionHandler { if (LoginHelper.isSuperAdmin() || LoginHelper.isTenantAdmin()) { return where; } + // 构造数据过滤条件的 SQL 片段 String dataFilterSql = buildDataFilter(dataPermission.value(), isSelect); if (StringUtils.isBlank(dataFilterSql)) { return where; @@ -103,7 +118,12 @@ public class PlusDataPermissionHandler { } /** - * 构造数据过滤sql + * 构建数据过滤条件的 SQL 语句 + * + * @param dataColumns 数据权限注解中的列信息 + * @param isSelect 标志当前操作是否为查询操作，查询操作和更新或删除操作在处理过滤条件时会有不同的处理方式 + * @return 构建的数据过滤条件的 SQL 语句 + * @throws ServiceException 如果角色的数据范围异常或者 key 与 value 的长度不匹配，则抛出 ServiceException 异常 */ private String buildDataFilter(DataColumn[] dataColumns, boolean isSelect) { // 更新或删除需满足所有条件 @@ -159,20 +179,29 @@ public class PlusDataPermissionHandler { } /** - * 通过 mapperPackage 设置的扫描包 扫描缓存有注解的方法与类 + * 扫描指定包下的 Mapper 类，并查找其中带有特定注解的方法或类 + * + * @param mapperPackage Mapper 类所在的包路径 */ private void scanMapperClasses(String mapperPackage) { + // 创建资源解析器和元数据读取工厂 PathMatchingResourcePatternResolver resolver = new PathMatchingResourcePatternResolver(); CachingMetadataReaderFactory factory = new CachingMetadataReaderFactory(); + // 将 Mapper 包路径按分隔符拆分为数组 String[] packagePatternArray = StringUtils.splitPreserveAllTokens(mapperPackage, ConfigurableApplicationContext.CONFIG_LOCATION_DELIMITERS); String classpath = ResourcePatternResolver.CLASSPATH_ALL_URL_PREFIX; try { for (String packagePattern : packagePatternArray) { + // 将包路径转换为资源路径 String path = ClassUtils.convertClassNameToResourcePath(packagePattern); + // 获取指定路径下的所有 .class 文件资源 Resource[] resources = resolver.getResources(classpath + path + "/*.class"); for (Resource resource : resources) { + // 获取资源的类元数据 ClassMetadata classMetadata = factory.getMetadataReader(resource).getClassMetadata(); + // 获取资源对应的类对象 Class clazz = Resources.classForName(classMetadata.getClassName()); + // 查找类中的特定注解 findAnnotation(clazz); } } @@ -181,9 +210,13 @@ public class PlusDataPermissionHandler { } } + /** + * 在指定的类中查找特定的注解 DataPermission，并将带有这个注解的方法或类存储到 dataPermissionCacheMap 中 + * + * @param clazz 要查找的类 + */ private void findAnnotation(Class clazz) { DataPermission dataPermission; - // 获取方法注解 for (Method method : clazz.getMethods()) { if (method.isDefault() || method.isVarArgs()) { continue; @@ -194,17 +227,24 @@ public class PlusDataPermissionHandler { dataPermissionCacheMap.put(mappedStatementId, dataPermission); } } - // 获取类注解 if (AnnotationUtil.hasAnnotation(clazz, DataPermission.class)) { dataPermission = AnnotationUtil.getAnnotation(clazz, DataPermission.class); dataPermissionCacheMap.put(clazz.getName(), dataPermission); } } + /** + * 根据映射语句 ID 或类名获取对应的 DataPermission 注解对象 + * + * @param mapperId 映射语句 ID + * @return DataPermission 注解对象，如果不存在则返回 null + */ public DataPermission getDataPermission(String mapperId) { + // 检查缓存中是否包含映射语句 ID 对应的 DataPermission 注解对象 if (dataPermissionCacheMap.containsKey(mapperId)) { return dataPermissionCacheMap.get(mapperId); } + // 如果缓存中不包含映射语句 ID 对应的 DataPermission 注解对象，则尝试使用类名作为键查找 String clazzName = mapperId.substring(0, mapperId.lastIndexOf(".")); if (dataPermissionCacheMap.containsKey(clazzName)) { return dataPermissionCacheMap.get(clazzName); @@ -213,7 +253,10 @@ public class PlusDataPermissionHandler { } /** - * 是否无效 + * 检查给定的映射语句 ID 是否有效，即是否能够找到对应的 DataPermission 注解对象 + * + * @param mapperId 映射语句 ID + * @return 如果找到对应的 DataPermission 注解对象，则返回 false；否则返回 true */ public boolean invalid(String mapperId) { return getDataPermission(mapperId) == null; diff --git a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/helper/DataBaseHelper.java b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/helper/DataBaseHelper.java index 4a293835..a98b3b7e 100644 --- a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/helper/DataBaseHelper.java +++ b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/helper/DataBaseHelper.java @@ -2,11 +2,11 @@ package org.dromara.common.mybatis.helper; import cn.hutool.core.convert.Convert; import com.baomidou.dynamic.datasource.DynamicRoutingDataSource; +import lombok.AccessLevel; +import lombok.NoArgsConstructor; import org.dromara.common.core.exception.ServiceException; import org.dromara.common.core.utils.SpringUtils; import org.dromara.common.mybatis.enums.DataBaseType; -import lombok.AccessLevel; -import lombok.NoArgsConstructor; import javax.sql.DataSource; import java.sql.Connection; @@ -14,7 +14,6 @@ import java.sql.DatabaseMetaData; import java.sql.SQLException; import java.util.ArrayList; import java.util.List; -import java.util.Set; /** * 数据库助手 diff --git a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/helper/DataPermissionHelper.java b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/helper/DataPermissionHelper.java index 0beae4da..4650a5a1 100644 --- a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/helper/DataPermissionHelper.java +++ b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/helper/DataPermissionHelper.java @@ -24,17 +24,35 @@ public class DataPermissionHelper { public static final String DATA_PERMISSION_KEY = "data:permission"; + /** + * 从上下文中获取指定键的变量值，并将其转换为指定的类型 + * + * @param key 变量的键 + * @param 变量值的类型 + * @return 指定键的变量值，如果不存在则返回 null + */ public static T getVariable(String key) { Map context = getContext(); return (T) context.get(key); } - + /** + * 向上下文中设置指定键的变量值 + * + * @param key 要设置的变量的键 + * @param value 要设置的变量值 + */ public static void setVariable(String key, Object value) { Map context = getContext(); context.put(key, value); } + /** + * 获取数据权限上下文 + * + * @return 存储在SaStorage中的Map对象，用于存储数据权限相关的上下文信息 + * @throws NullPointerException 如果数据权限上下文类型异常，则抛出NullPointerException + */ public static Map getContext() { SaStorage saStorage = SaHolder.getStorage(); Object attribute = saStorage.get(DATA_PERMISSION_KEY); @@ -64,6 +82,7 @@ public class DataPermissionHelper { /** * 在忽略数据权限中执行 + *

禁止在忽略数据权限中执行忽略数据权限

* * @param handle 处理执行方法 */ @@ -78,6 +97,7 @@ public class DataPermissionHelper { /** * 在忽略数据权限中执行 + *

禁止在忽略数据权限中执行忽略数据权限

* * @param handle 处理执行方法 */ diff --git a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/interceptor/PlusDataPermissionInterceptor.java b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/interceptor/PlusDataPermissionInterceptor.java index 6eed8f77..85a4d0ab 100644 --- a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/interceptor/PlusDataPermissionInterceptor.java +++ b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/interceptor/PlusDataPermissionInterceptor.java @@ -37,17 +37,33 @@ public class PlusDataPermissionInterceptor extends BaseMultiTableInnerIntercepto private final PlusDataPermissionHandler dataPermissionHandler; + /** + * 构造函数，初始化 PlusDataPermissionHandler 实例 + * + * @param mapperPackage 扫描的映射器包 + */ public PlusDataPermissionInterceptor(String mapperPackage) { this.dataPermissionHandler = new PlusDataPermissionHandler(mapperPackage); } + /** + * 在执行查询之前，检查并处理数据权限相关逻辑 + * + * @param executor MyBatis 执行器对象 + * @param ms 映射语句对象 + * @param parameter 方法参数 + * @param rowBounds 分页对象 + * @param resultHandler 结果处理器 + * @param boundSql 绑定的 SQL 对象 + * @throws SQLException 如果发生 SQL 异常 + */ @Override public void beforeQuery(Executor executor, MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, BoundSql boundSql) throws SQLException { - // 检查忽略注解 + // 检查是否需要忽略数据权限处理 if (InterceptorIgnoreHelper.willIgnoreDataPermission(ms.getId())) { return; } - // 检查是否无效 无数据权限注解 + // 检查是否缺少有效的数据权限注解 if (dataPermissionHandler.invalid(ms.getId())) { return; } @@ -56,16 +72,26 @@ public class PlusDataPermissionInterceptor extends BaseMultiTableInnerIntercepto mpBs.sql(parserSingle(mpBs.sql(), ms.getId())); } + /** + * 在准备 SQL 语句之前，检查并处理更新和删除操作的数据权限相关逻辑 + * + * @param sh MyBatis StatementHandler 对象 + * @param connection 数据库连接对象 + * @param transactionTimeout 事务超时时间 + */ @Override public void beforePrepare(StatementHandler sh, Connection connection, Integer transactionTimeout) { PluginUtils.MPStatementHandler mpSh = PluginUtils.mpStatementHandler(sh); MappedStatement ms = mpSh.mappedStatement(); + // 获取 SQL 命令类型（增、删、改、查） SqlCommandType sct = ms.getSqlCommandType(); + + // 只处理更新和删除操作的 SQL 语句 if (sct == SqlCommandType.UPDATE || sct == SqlCommandType.DELETE) { if (InterceptorIgnoreHelper.willIgnoreDataPermission(ms.getId())) { return; } - // 检查是否无效 无数据权限注解 + // 检查是否缺少有效的数据权限注解 if (dataPermissionHandler.invalid(ms.getId())) { return; } @@ -74,6 +100,14 @@ public class PlusDataPermissionInterceptor extends BaseMultiTableInnerIntercepto } } + /** + * 处理 SELECT 查询语句中的 WHERE 条件 + * + * @param select SELECT 查询对象 + * @param index 查询语句的索引 + * @param sql 查询语句 + * @param obj WHERE 条件参数 + */ @Override protected void processSelect(Select select, int index, String sql, Object obj) { if (select instanceof PlainSelect) { @@ -84,6 +118,14 @@ public class PlusDataPermissionInterceptor extends BaseMultiTableInnerIntercepto } } + /** + * 处理 UPDATE 语句中的 WHERE 条件 + * + * @param update UPDATE 查询对象 + * @param index 查询语句的索引 + * @param sql 查询语句 + * @param obj WHERE 条件参数 + */ @Override protected void processUpdate(Update update, int index, String sql, Object obj) { Expression sqlSegment = dataPermissionHandler.getSqlSegment(update.getWhere(), (String) obj, false); @@ -92,6 +134,14 @@ public class PlusDataPermissionInterceptor extends BaseMultiTableInnerIntercepto } } + /** + * 处理 DELETE 语句中的 WHERE 条件 + * + * @param delete DELETE 查询对象 + * @param index 查询语句的索引 + * @param sql 查询语句 + * @param obj WHERE 条件参数 + */ @Override protected void processDelete(Delete delete, int index, String sql, Object obj) { Expression sqlSegment = dataPermissionHandler.getSqlSegment(delete.getWhere(), (String) obj, false); @@ -101,10 +151,10 @@ public class PlusDataPermissionInterceptor extends BaseMultiTableInnerIntercepto } /** - * 设置 where 条件 + * 设置 SELECT 语句的 WHERE 条件 * - * @param plainSelect 查询对象 - * @param mappedStatementId 执行方法id + * @param plainSelect SELECT 查询对象 + * @param mappedStatementId 映射语句的 ID */ protected void setWhere(PlainSelect plainSelect, String mappedStatementId) { Expression sqlSegment = dataPermissionHandler.getSqlSegment(plainSelect.getWhere(), mappedStatementId, true); @@ -113,6 +163,14 @@ public class PlusDataPermissionInterceptor extends BaseMultiTableInnerIntercepto } } + /** + * 构建表达式，用于处理表的数据权限 + * + * @param table 表对象 + * @param where WHERE 条件表达式 + * @param whereSegment WHERE 条件片段 + * @return 构建的表达式 + */ @Override public Expression buildTableExpression(Table table, Expression where, String whereSegment) { // 只有新版数据权限处理器才会执行到这里 diff --git a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/service/SysDataScopeService.java b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/service/SysDataScopeService.java index 0c187f66..4543579c 100644 --- a/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/service/SysDataScopeService.java +++ b/ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/service/SysDataScopeService.java @@ -1,7 +1,7 @@ package org.dromara.common.mybatis.service; -import org.dromara.system.api.RemoteDataScopeService; import org.apache.dubbo.config.annotation.DubboReference; +import org.dromara.system.api.RemoteDataScopeService; import org.springframework.stereotype.Service; /** @@ -18,11 +18,24 @@ public class SysDataScopeService { @DubboReference private RemoteDataScopeService remoteDataScopeService; + /** + * 获取角色自定义权限语句 + * + * @param roleId 角色ID + * @return 返回角色的自定义权限语句，如果没有找到则返回 null + */ public String getRoleCustom(Long roleId) { return remoteDataScopeService.getRoleCustom(roleId); } + /** + * 获取部门和下级权限语句 + * + * @param deptId 部门ID + * @return 返回部门及其下级的权限语句，如果没有找到则返回 null + */ public String getDeptAndChild(Long deptId) { return remoteDataScopeService.getDeptAndChild(deptId); } + } diff --git a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/dubbo/RemoteDataScopeServiceImpl.java b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/dubbo/RemoteDataScopeServiceImpl.java index ea59a992..b09f682c 100644 --- a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/dubbo/RemoteDataScopeServiceImpl.java +++ b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/dubbo/RemoteDataScopeServiceImpl.java @@ -32,6 +32,12 @@ public class RemoteDataScopeServiceImpl implements RemoteDataScopeService { private final SysRoleDeptMapper roleDeptMapper; private final SysDeptMapper deptMapper; + /** + * 获取角色自定义权限语句 + * + * @param roleId 角色ID + * @return 返回角色的自定义权限语句，如果没有找到则返回 null + */ @Override public String getRoleCustom(Long roleId) { List list = roleDeptMapper.selectList( @@ -44,6 +50,12 @@ public class RemoteDataScopeServiceImpl implements RemoteDataScopeService { return null; } + /** + * 获取部门和下级权限语句 + * + * @param deptId 部门ID + * @return 返回部门及其下级的权限语句，如果没有找到则返回 null + */ @Override public String getDeptAndChild(Long deptId) { List deptList = deptMapper.selectList(new LambdaQueryWrapper()