基于MyBatis插件实现数据权限控制：原理、实现与避坑指南

1. 项目背景与核心痛点

最近在做一个后台管理系统，涉及到多租户、多部门的数据隔离需求。简单来说，就是不同角色的用户登录后，只能看到自己权限范围内的数据。比如，部门经理只能看到本部门的订单，普通员工只能看到自己创建的工单，而超级管理员则能看到全公司的数据。这个需求在业内通常被称为“数据权限”或“行级权限”。

听起来很简单，不就是加个where条件吗？但真做起来，你会发现到处都是坑。最直接的实现方式，就是在每一个查询数据库的地方，手动拼接上user_id = ?或者dept_id in (?)这样的条件。项目初期，业务简单，查询不多，这么干还能应付。但随着业务模块爆炸式增长，你会发现，同样的权限过滤逻辑，在几十个、上百个Mapper接口的SQL里重复出现。一旦权限规则发生变动（比如从按部门过滤，改成按项目组过滤），那就是一场灾难，你需要像大海捞针一样去修改每一个相关的SQL语句，漏掉一个就可能造成严重的数据泄露风险。

所以，我们需要一个更优雅、更解耦的方案：将数据权限的控制逻辑从业务SQL中剥离出来，进行统一管理和自动注入。这样，业务开发人员写SQL时，只需要关注业务逻辑本身，数据权限作为一个“切面”自动生效。MyBatis作为Java生态中最主流的ORM框架，其强大的插件机制为我们实现这个目标提供了可能。今天，我就结合Spring Boot和MyBatis，来详细拆解一下数据权限的完整实现方案，包括核心原理、详细步骤、避坑指南，以及我趟过的一些雷。

2. 方案选型：为什么是 MyBatis 插件？

实现数据权限，业内主要有几种思路，我们来逐一分析，看看为什么最终我选择了基于MyBatis插件的方案。

2.1 几种常见方案的对比

• 方案一：在每一个Service或Mapper方法中硬编码这是最原始的方法。缺点刚才已经说了，耦合度高，难以维护，违反DRY原则，基本不可取。

• 方案二：使用视图（View）在数据库层为不同角色创建不同的视图，业务代码直接查询视图。这种方式将权限逻辑下沉到数据库，对应用透明。但缺点也很明显：视图多了难以管理；权限规则变更（特别是动态规则）需要DBA介入修改视图，不灵活；复杂的多表关联权限用视图实现会很繁琐。

• 方案三：使用 Spring AOP 拦截 Service 层在Service层的方法执行前后进行拦截，动态修改传入Mapper的参数或对查询结果进行过滤。这种方式比硬编码好，但存在局限性。对于查询，你需要在AOP里解析方法参数，构造复杂的权限条件对象，逻辑会很重。更麻烦的是，它难以处理MyBatis中动态SQL（如<if>标签）与权限条件的无缝拼接。

• 方案四：使用 MyBatis 插件（Interceptor）这是我们的主角。MyBatis插件可以拦截四大核心对象（Executor,StatementHandler,ParameterHandler,ResultSetHandler）的方法执行。我们可以在SQL被送往数据库执行前，拦截并修改它，动态注入权限过滤条件。这是最彻底的方案，因为它作用于SQL生成这个最底层、最统一的环节。

  1. 解耦彻底：业务代码零侵入，Mapper接口和XML中的SQL无需关心权限。
  2. 灵活强大：可以获取到完整的SQL语句、参数映射、MappedStatement等信息，能实现非常复杂的权限规则注入。
  3. 统一管理：所有数据操作入口都被插件把守，安全边界清晰。

2.2 MyBatis 插件的工作原理与拦截点选择

MyBatis插件通过实现Interceptor接口，并使用@Intercepts和@Signature注解来声明要拦截的方法。

@Intercepts({ @Signature(type = StatementHandler.class, method = "prepare", args = {Connection.class, Integer.class}) }) public class DataPermissionInterceptor implements Interceptor { // ... 实现逻辑 }

这里最关键的是拦截点的选择。我们应该拦截StatementHandler.prepare方法。因为在这个时间点，SqlSource已经根据DynamicContext等解析出了最终的、待执行的SQL字符串（但还没有创建PreparedStatement），同时BoundSql中也包含了所有的运行时参数。这是我们修改SQL的最佳时机。

注意：不要拦截Executor的query或update方法。虽然那里也能拿到SQL，但Executor层面处理的是多个语句的执行过程（如批处理、缓存），而StatementHandler才是真正负责单个语句生成和参数设置的，在这里修改更精准，副作用更小。

3. 核心实现：构建数据权限拦截器

理论说完了，我们开始动手。整个核心在于实现这个DataPermissionInterceptor。我会分步讲解，并附上关键代码。

3.1 定义权限上下文与规则引擎

首先，我们需要一个地方来存放当前用户的权限信息，比如用户ID、角色列表、部门ID、数据权限范围标识等。通常我们会把它放在ThreadLocal里，确保线程安全。

public class DataPermissionContextHolder { private static final ThreadLocal<DataPermissionContext> CONTEXT_HOLDER = new ThreadLocal<>(); public static void setContext(DataPermissionContext context) { CONTEXT_HOLDER.set(context); } public static DataPermissionContext getContext() { return CONTEXT_HOLDER.get(); } public static void clearContext() { CONTEXT_HOLDER.remove(); } @Data public static class DataPermissionContext { // 用户唯一标识 private Long userId; // 用户所属部门ID private Long deptId; // 用户角色列表 private List<String> roles; // 数据权限范围：ALL-全部，DEPT-本部门及以下，DEPT_ONLY-仅本部门，SELF-仅自己 private String dataScope; // 其他自定义属性，如项目组ID等 private Map<String, Object> attributes; } }

然后，定义一个规则引擎。它的职责是根据DataPermissionContext和当前要执行的SQL信息（表名、操作类型），生成对应的WHERE条件片段。这里我们可以设计一个简单的接口和基于配置的实现。

public interface DataPermissionRuleEngine { /** * 判断是否需要对此SQL进行权限过滤 * @param mappedStatementId MyBatis的语句ID * @return true 需要过滤 */ boolean needFilter(String mappedStatementId); /** * 根据上下文生成数据权限SQL条件片段 * @param context 权限上下文 * @param tableAlias 查询中表的别名（可能为空） * @return SQL条件片段，如 " AND dept_id = 123" */ String buildCondition(DataPermissionContext context, String tableAlias); }

一个简单的实现可能是这样的（基于注解或配置文件）：

@Component public class DefaultDataPermissionRuleEngine implements DataPermissionRuleEngine { // 可以从数据库或配置文件中加载规则 private Map<String, String> statementRuleMap = new HashMap<>(); public DefaultDataPermissionRuleEngine() { // 示例：key为Mapper方法全限定名，value为规则表达式 statementRuleMap.put("com.example.mapper.OrderMapper.selectList", "order"); statementRuleMap.put("com.example.mapper.UserMapper.selectPage", "user"); } @Override public boolean needFilter(String mappedStatementId) { // 排除一些不需要过滤的方法，比如登录、获取用户信息等 if (mappedStatementId.contains(".UserMapper.selectByLogin")) { return false; } return statementRuleMap.containsKey(mappedStatementId); } @Override public String buildCondition(DataPermissionContext context, String tableAlias) { if (context == null) { return ""; } String prefix = tableAlias == null ? "" : tableAlias + "."; StringBuilder condition = new StringBuilder(" AND "); switch (context.getDataScope()) { case "ALL": return ""; // 全部数据，不加条件 case "DEPT": // 假设有部门层级表，这里简化处理为本部门 condition.append(prefix).append("dept_id = ").append(context.getDeptId()); break; case "SELF": condition.append(prefix).append("create_by = '").append(context.getUserId()).append("'"); break; // ... 其他规则 default: condition.append("1=1"); // 默认无权限 } return condition.toString(); } }

3.2 实现拦截器逻辑

现在，我们来编写拦截器本身。它的核心逻辑是：

1. 拦截prepare方法。
2. 判断当前执行的SQL是否需要添加数据权限。
3. 如果需要，则解析原始SQL，找到合适的插入点（通常在WHERE关键字后），拼接上我们生成的权限条件。
4. 使用修改后的SQL替换原来的BoundSql。

@Slf4j @Component @Intercepts({ @Signature(type = StatementHandler.class, method = "prepare", args = {Connection.class, Integer.class}) }) public class DataPermissionInterceptor implements Interceptor { @Autowired private DataPermissionRuleEngine ruleEngine; // 用于匹配WHERE关键字，考虑换行和大小写 private static final Pattern WHERE_PATTERN = Pattern.compile("\\s+[Ww][Hh][Ee][Rr][Ee]\\s+"); // 匹配GROUP BY/ORDER BY等子句，用于确定WHERE条件插入的边界 private static final Pattern GROUP_ORDER_LIMIT_PATTERN = Pattern.compile("\\s+(GROUP BY|ORDER BY|LIMIT|OFFSET)\\s+", Pattern.CASE_INSENSITIVE); @Override public Object intercept(Invocation invocation) throws Throwable { StatementHandler statementHandler = (StatementHandler) invocation.getTarget(); MetaObject metaObject = SystemMetaObject.forObject(statementHandler); // 分离代理对象链，获取原始的StatementHandler（可能被多次代理） while (metaObject.hasGetter("h")) { Object h = metaObject.getValue("h"); metaObject = SystemMetaObject.forObject(h); } while (metaObject.hasGetter("target")) { Object target = metaObject.getValue("target"); metaObject = SystemMetaObject.forObject(target); } // 获取MappedStatement和BoundSql MappedStatement mappedStatement = (MappedStatement) metaObject.getValue("delegate.mappedStatement"); BoundSql boundSql = (BoundSql) metaObject.getValue("delegate.boundSql"); String originalSql = boundSql.getSql(); // 1. 判断是否需要数据权限过滤 if (!ruleEngine.needFilter(mappedStatement.getId())) { return invocation.proceed(); } DataPermissionContext context = DataPermissionContextHolder.getContext(); if (context == null) { log.warn("DataPermissionContext is null for statement: {}", mappedStatement.getId()); return invocation.proceed(); } // 2. 生成权限条件片段 // 这里需要解析SQL，获取主查询的表别名，这是一个复杂点，简化处理先假设表别名或使用空 String tableAlias = parseTableAlias(originalSql); // 需要自己实现一个简单的解析器 String permissionCondition = ruleEngine.buildCondition(context, tableAlias); if (StringUtils.isEmpty(permissionCondition)) { // 无需添加条件，如权限为ALL return invocation.proceed(); } // 3. 修改SQL，注入权限条件 String newSql = injectCondition(originalSql, permissionCondition); log.debug("Original SQL: {}", originalSql); log.debug("New SQL with data permission: {}", newSql); // 4. 替换BoundSql中的SQL metaObject.setValue("delegate.boundSql.sql", newSql); // 5. 继续执行原流程 return invocation.proceed(); } /** * 将权限条件注入到原始SQL中 */ private String injectCondition(String originalSql, String condition) { if (!StringUtils.hasText(condition)) { return originalSql; } condition = condition.trim(); // 确保条件以 AND 开头 if (!condition.toUpperCase().startsWith("AND")) { condition = " AND " + condition; } String upperCaseSql = originalSql.toUpperCase(); int whereIndex = upperCaseSql.indexOf(" WHERE "); if (whereIndex == -1) { // 原SQL没有WHERE子句，需要构造 // 找到ORDER BY/GROUP BY/LIMIT等子句的位置 Matcher matcher = GROUP_ORDER_LIMIT_PATTERN.matcher(originalSql); if (matcher.find()) { int insertPos = matcher.start(); return originalSql.substring(0, insertPos) + " WHERE 1=1 " + condition + " " + originalSql.substring(insertPos); } else { // 没有这些子句，直接追加在最后 return originalSql + " WHERE 1=1 " + condition; } } else { // 原SQL有WHERE子句，在WHERE之后插入 // 找到WHERE关键字在原始SQL（保留大小写）中的准确位置 Matcher whereMatcher = WHERE_PATTERN.matcher(originalSql); if (whereMatcher.find()) { int insertPos = whereMatcher.end(); // WHERE关键字之后的位置 return originalSql.substring(0, insertPos) + condition + " " + originalSql.substring(insertPos); } // 如果正则没匹配到（理论上不会），fallback到原逻辑 return originalSql.replaceFirst("(?i)\\s+WHERE\\s+", " WHERE " + condition + " AND "); } } // 简单的表别名解析（示例，实际应用需要更复杂的解析，如使用JSqlParser） private String parseTableAlias(String sql) { // 这是一个极其简化的示例，仅用于说明。 // 真实场景强烈建议使用JSqlParser等SQL解析库。 // 例如，假设我们约定查询主表别名为 't' return "t"; } @Override public Object plugin(Object target) { return Plugin.wrap(target, this); } @Override public void setProperties(Properties properties) { // 可以从配置文件中读取属性 } }

3.3 注册拦截器与填充上下文

拦截器写好了，需要把它注册到MyBatis的配置中。在Spring Boot中，我们可以通过一个配置类来实现。

@Configuration public class MyBatisConfig { @Bean public DataPermissionInterceptor dataPermissionInterceptor() { return new DataPermissionInterceptor(); } /** * 将拦截器添加到MyBatis的插件链中 */ @Bean public ConfigurationCustomizer mybatisConfigurationCustomizer(DataPermissionInterceptor interceptor) { return configuration -> configuration.addInterceptor(interceptor); } }

接下来，我们需要在用户请求进入时，填充DataPermissionContextHolder。这通常在一个Filter或Spring Interceptor中完成。

@Component public class DataPermissionContextFilter extends OncePerRequestFilter { @Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException { try { // 1. 从Session、Token或请求头中获取当前用户信息 // 这里假设你有一个UserService能从安全上下文中获取用户详情 User currentUser = getCurrentUser(request); if (currentUser != null) { // 2. 构建权限上下文 DataPermissionContext context = new DataPermissionContext(); context.setUserId(currentUser.getId()); context.setDeptId(currentUser.getDeptId()); context.setRoles(currentUser.getRoles()); context.setDataScope(currentUser.getDataScope()); // 这个字段需要你在用户表或角色权限表中定义 // 3. 设置到ThreadLocal DataPermissionContextHolder.setContext(context); } filterChain.doFilter(request, response); } finally { // 4. 请求结束后，务必清除ThreadLocal，防止内存泄漏 DataPermissionContextHolder.clearContext(); } } private User getCurrentUser(HttpServletRequest request) { // 实现你的用户获取逻辑，例如从Spring Security的SecurityContextHolder中获取 // 示例：return (User) SecurityContextHolder.getContext().getAuthentication().getPrincipal(); return null; // 模拟 } }

记得在SecurityConfig或WebMvcConfig中注册这个Filter。

4. 高级场景与避坑指南

基础功能跑通了，但在实际项目中，你会遇到更复杂的情况。下面分享几个我踩过的坑和解决方案。

4.1 多表关联查询的权限注入

这是最常见也最头疼的问题。我们的SQL常常是多表JOIN，权限条件应该加在哪个表上？比如：

SELECT o.*, u.name FROM order o LEFT JOIN user u ON o.create_by = u.id WHERE o.status = 1

如果权限规则是“只能看自己创建的订单”，那么条件o.create_by = ?应该加在order表上。我们的拦截器需要能识别出SQL中的主表（或者业务表），并针对性地添加条件。

解决方案：

1. 使用注解标记：在Mapper方法上使用自定义注解，显式指定需要过滤的表名和别名。

   @DataPermission(table = "order", alias = "o") List<OrderVO> selectOrderList(OrderQuery query);

   拦截器解析这个注解，获取表名和别名，然后生成条件。这种方式最清晰，但需要开发人员手动添加注解。

2. 使用SQL解析库：引入JSqlParser这样的库，在拦截器中解析SQL的抽象语法树（AST）。你可以分析FROM和JOIN子句，识别出所有表，然后根据某种规则（如第一个表、或根据表名字典）确定主业务表。这种方式更智能，但复杂度高，性能有轻微损耗，且需要处理各种SQL方言的兼容性。

   import net.sf.jsqlparser.parser.CCJSqlParserUtil; import net.sf.jsqlparser.statement.Statement; import net.sf.jsqlparser.statement.select.PlainSelect; import net.sf.jsqlparser.statement.select.Select; private String parseMainTableWithJSqlParser(String sql) { try { Statement statement = CCJSqlParserUtil.parse(sql); if (statement instanceof Select) { Select select = (Select) statement; if (select.getSelectBody() instanceof PlainSelect) { PlainSelect plainSelect = (PlainSelect) select.getSelectBody(); FromItem fromItem = plainSelect.getFromItem(); if (fromItem instanceof Table) { Table table = (Table) fromItem; return table.getAlias() != null ? table.getAlias().getName() : table.getName(); } } } } catch (JSQLParserException e) { log.error("Failed to parse SQL for data permission", e); } return null; }

4.2 分页插件（如 PageHelper）的兼容性问题

如果你的项目使用了PageHelper，你会发现它也是一个MyBatis插件。插件执行是有顺序的。如果我们的数据权限插件在PageHelper之后执行，那么PageHelper生成的count查询语句（用于计算总数）可能不会被我们的插件处理，导致分页总数计算错误。

解决方案： 明确指定插件的执行顺序。在Spring Boot中，可以通过@Order注解或ConfigurationCustomizer中的添加顺序来控制。通常，数据权限插件应该在分页插件之后执行，以确保count查询也能被正确过滤。

@Bean public ConfigurationCustomizer mybatisConfigurationCustomizer(DataPermissionInterceptor dpInterceptor, PageInterceptor pageInterceptor) { return configuration -> { configuration.addInterceptor(pageInterceptor); // 先加PageHelper configuration.addInterceptor(dpInterceptor); // 后加数据权限 }; }

实测经验：一定要测试带分页的查询，对比插件生效前后的total数，确保count查询的SQL也被正确修改了。这是最容易出问题的地方。

4.3 权限条件的冲突与重复添加

想象一个场景：业务SQL本身有一个WHERE create_by = #{userId}（比如查询“我的待办”），而我们的数据权限规则也是SELF（只能看自己的数据）。如果插件不加判断地直接追加一个AND create_by = ?，就会导致SQL出现重复条件，虽然结果可能对，但不够优雅，也可能影响数据库优化器的判断。

解决方案： 在injectCondition方法中，可以增加一个简单的分析逻辑。使用JSqlParser解析原始SQL的WHERE条件，检查是否已经存在与我们即将添加的条件等价或更强的条件。如果存在，则可以跳过添加，或者进行合并。这是一个高级特性，实现起来较复杂，需要权衡开发成本和收益。对于大多数项目，重复条件可能可以接受，优先保证功能正确性。

4.4 忽略特定的查询（白名单机制）

不是所有查询都需要数据权限。例如：

• 登录验证、获取当前用户信息。
• 下拉框数据字典查询（通常需要全量）。
• 一些特殊的报表或管理员专属接口。

解决方案： 在我们的DataPermissionRuleEngine.needFilter()方法中实现白名单机制。可以通过注解、配置文件(如application.yml)或MapperID匹配规则来排除。

@Override public boolean needFilter(String mappedStatementId) { // 1. 注解白名单：通过反射检查方法上是否有 @DataPermissionIgnore 注解 // 2. 配置白名单：从配置文件读取一组 regex 模式，匹配则忽略 // 例如：忽略所有以 .selectDict 结尾的查询 if (mappedStatementId.matches(".*\\.selectDict.*")) { return false; } // 3. 默认规则：根据 mappedStatementId 判断是否需要 return statementRuleMap.containsKey(mappedStatementId); }

5. 测试与验证：如何确保插件正确工作

实现完了，怎么验证它是否按预期工作？不能光看日志，必须有系统的测试。

5.1 单元测试拦截器逻辑

为DataPermissionInterceptor和DataPermissionRuleEngine编写单元测试，模拟不同的权限上下文，验证生成的SQL条件片段是否正确。

@SpringBootTest class DataPermissionRuleEngineTest { @Autowired private DataPermissionRuleEngine ruleEngine; @Test void testBuildConditionForSelf() { DataPermissionContext context = new DataPermissionContext(); context.setUserId(100L); context.setDataScope("SELF"); String condition = ruleEngine.buildCondition(context, "t"); assertEquals(" AND t.create_by = 100", condition); } @Test void testBuildConditionForAll() { DataPermissionContext context = new DataPermissionContext(); context.setDataScope("ALL"); String condition = ruleEngine.buildCondition(context, "t"); assertEquals("", condition); // 全部数据，应返回空字符串 } }

5.2 集成测试：验证SQL修改

编写一个集成测试，启动一个真实的Spring上下文，调用你的Mapper方法，然后利用MyBatis提供的SqlSession或Interceptor机制，捕获最终执行的SQL语句，断言其是否包含了正确的权限条件。

@SpringBootTest @AutoConfigureTestDatabase class OrderMapperDataPermissionTest { @Autowired private OrderMapper orderMapper; @Autowired private DataPermissionContextHolder contextHolder; @Test void testSelectListWithDataPermission() { // 1. 模拟用户登录，设置权限上下文 DataPermissionContext context = new DataPermissionContext(); context.setUserId(123L); context.setDataScope("SELF"); contextHolder.setContext(context); // 2. 执行查询 List<Order> orders = orderMapper.selectList(new OrderQuery()); // 3. 这里无法直接断言SQL，但可以断言查询结果 // 例如，确保查出的所有订单的 create_by 都是 123 assertFalse(orders.isEmpty()); assertTrue(orders.stream().allMatch(order -> order.getCreateBy().equals(123L))); // 4. 更直接的方式：配置一个测试用的MyBatis ExecutorListener 或使用 p6spy 等SQL日志工具来捕获SQL进行断言 } }

5.3 生产环境监控与日志

在生产环境，为拦截器打开DEBUG级别日志，输出修改前后的SQL。这不仅是排查问题的利器，也是审计数据权限是否生效的依据。可以考虑将关键的操作（尤其是权限过滤失败或上下文为空的情况）记录到更高级别的日志或审计系统中。

6. 性能考量与优化建议

动态修改SQL必然带来性能开销，我们需要将其降到最低。

1. 减少不必要的解析：在needFilter()方法中尽快返回false。使用高效的匹配机制，比如将白名单MapperID放在HashSet中，而不是遍历List。
2. 缓存权限规则：DataPermissionRuleEngine中的规则（如statementRuleMap）不应该每次请求都从数据库查询。可以在应用启动时加载到内存，或者使用Redis缓存，并监听规则变更事件进行更新。
3. 慎用复杂的SQL解析：如果使用JSqlParser，要意识到它的解析是有成本的。对于确定的、简单的查询，优先使用注解方式指定表别名，避免每次执行都进行完整的SQL解析。
4. 注意ThreadLocal的内存泄漏：我们的DataPermissionContextHolder使用了ThreadLocal。务必确保在Filter或Interceptor的finally块中调用clearContext()，特别是在使用线程池的场景（如Tomcat的HTTP线程池、@Async异步任务），否则可能导致内存泄漏和脏数据问题。
5. 条件预编译：我们生成的权限条件（如AND dept_id = ?）是字符串拼接进SQL的。要确保条件中的参数值是通过PreparedStatement设置的，而不是直接字符串拼接，以防止SQL注入。在我们的示例中，条件值（如context.getDeptId()）被直接拼成了SQL的一部分，这在实际中是不安全的。更安全的做法是，拦截器不仅修改SQL，还要向BoundSql的附加参数列表中添加新的参数映射。这涉及到对ParameterHandler的更深层次操作，实现复杂度会大大增加。一个折中的方案是，确保权限上下文中的值都是可信的（如数字ID），并且对字符串类型进行严格的转义，或者直接规定权限条件只使用数字ID进行比较。

最后，数据权限是一个涉及安全和业务逻辑的复杂特性，没有银弹。本文提供的方案是一个坚实起点，你可以根据自己项目的复杂程度进行裁剪和增强。比如，对于超大型系统，可能需要将权限规则配置中心化、支持更复杂的RBAC（基于角色的访问控制）模型、甚至与Apache ShardingSphere这类中间件结合。但无论如何，理解MyBatis插件这个核心机制，是你构建任何灵活数据访问层的基础。