1. 为什么需要一套独立的通用数据权限校验框架1.1 一次权限事故引发的重构先讲一个我实际经历过的场景。某次给一个后台管理系统做权限改造初期只做了菜单权限和按钮权限也就是用户能不能看到某个页面、能不能点某个按钮。上线第三天运营人员发现一个严重问题A部门的主管在导出报表时能查到B部门的客户订单明细。查了半天问题出在接口层只校验了用户已登录和是否拥有导出按钮的权限码但数据行本身没有任何过滤——只要请求参数里传了某个客户ID后端就老老实实把数据返回了。这个问题的本质是传统的鉴权框架比如Shiro、Spring Security解决的是你能不能用这个功能的问题但解决不了你能看到哪些数据的问题。前者是粗粒度的权限后者是需要和业务深度绑定的数据权限。而数据权限恰恰是最容易出事故的环节因为它跟具体的表结构、部门层级、用户角色、甚至业务规则都强相关很难用一套标准化的代码去套用。这次事故之后我开始着手设计一套基于SpringMVC的通用数据权限校验框架。目标很明确不重复造Shiro和Spring Security已经做好的认证和功能权限轮子只在它们之上补上数据行级权限这一层。这篇文章就是这套框架的使用示例我把设计思路、核心实现、完整使用步骤和踩坑记录都整理出来希望能给正在被数据权限折磨的同学一个可参考的落地方案。1.2 常见数据权限方案的痛点先说说市面上常见的做法以及它们各自的问题。很多人一开始写数据权限喜欢直接在Service层里硬编码。比如这样public ListOrder queryOrderList(OrderQuery query) { // 硬编码只能查本部门的数据 Long deptId currentUser().getDeptId(); query.setDeptId(deptId); return orderMapper.selectList(query); }这种写法在项目初期没什么问题但一旦业务多起来痛点非常明显重复代码爆炸每个需要数据权限的Service方法里都要写一遍获取当前用户、判断角色、拼接部门条件的逻辑几十个方法下来全是重复代码。权限规则和业务逻辑耦合如果有一天权限规则变了比如从只能查本部门改成能查本部门及子部门需要把所有写死deptId的地方翻出来改一遍漏一个就是一次事故。难以统一管理每个开发者的写法不一样有的用dept_id字段有的用create_by字段有的用data_scope字段规则散落在各处审计和排查非常困难。另外一些人会尝试用MyBatis的拦截器来做思路是在SQL执行前动态拼接数据权限条件。这个方向是对的但很多实现做得非常死板拦截器里写死了表名和字段名一换项目就废掉根本谈不上通用。1.3 我最终确定的设计目标在动手之前我给自己定了几条硬性标准也建议你做同类框架时先想清楚这些约束对业务代码侵入要小最好一个注解就能声明这个接口需要数据权限控制让开发者能专注于业务逻辑。权限规则要能和业务解耦规则中需要哪些上下文信息用户、部门、角色、自定义参数由框架统一从上下文获取而不是业务代码自己组装。要支持多种数据范围比如仅本人、本部门、本部门及子部门、全部数据、按自定义SQL片段这是最常见的数据权限需求。规则配置要能动态调整权限规则不要写死在代码里最好配置在数据库或配置中心改成规则不用发版重启。性能损耗要可控数据权限的SQL改写不能造成严重的性能退化不能出现全表扫描或者干脆拼错SQL。基于这几点我设计出了一套以注解声明 拦截器解析 ThreadLocal上下文 SQL自动改写为核心的通用方案。接下来我会把每个环节的细节展开讲。2. 框架整体设计与核心实现思路2.1 整体架构注解、拦截器、ThreadLocal三位一体这套框架的运行链路并不复杂核心是三个角色自定义注解标注在Controller方法或Service方法上声明当前接口需要什么样的数据权限控制粒度。SpringMVC拦截器在请求进入Controller之前解析注解、初始化数据权限上下文并把上下文放到ThreadLocal中。MyBatis拦截器或JDBC层拦截器在SQL真正执行前根据ThreadLocal中的权限上下文动态改写SQL拼上数据过滤条件。这个设计的巧妙之处在于业务代码完全不感知权限逻辑。Controller里的那行DataAuth就是唯一的侵入点而SQL改写发生在持久层业务Service层的代码看起来就跟普通查询没有任何区别。链路大致如下请求 - SpringMVC拦截器(解析注解初始化上下文) - Controller - Service - Mapper | v MyBatis拦截器(读取上下文改写SQL) - 数据库ThreadLocal在这里起到了跨层传递的作用。因为SpringMVC拦截器先执行Service层和Mapper层后执行中间的层层方法调用如果靠参数传递权限上下文会非常丑陋所以使用ThreadLocal存放当前请求的用户信息、部门信息、权限规则等请求结束再清理掉。2.2 数据范围枚举与规则模型数据权限的核心是范围概念。我定义了一个枚举来统一各种范围类型public enum DataScope { ALL(1), // 全部数据 DEPT(2), // 本部门数据 DEPT_AND_CHILD(3), // 本部门及子部门数据 SELF(4), // 仅本人数据 CUSTOM(5); // 自定义规则 }光有枚举还不够因为本部门子部门这些概念需要转换成具体的SQL条件。这里我用一个DataScopeRule对象来表示一条完整的权限规则它包含的信息如下字段说明scope数据范围类型对应上面的枚举deptIdColumn部门ID在目标表中的字段名比如dept_iduserIdColumn用户ID在目标表中的字段名比如create_bytableAlias如果SQL语句中用了表别名这里指定别名避免拼接条件时字段歧义customSql当scopeCUSTOM时直接使用这段自定义SQL片段作为过滤条件ignoreIfEmptyUser当上下文中没有用户信息时是否放行跳过权限过滤例如某个页面的数据权限规则是只能看本部门及子部门的数据在数据库里配置的规则可能是{ scope: DEPT_AND_CHILD, deptIdColumn: dept_id, tableAlias: o }那么框架改写SQL时会生成类似这样的条件o.dept_id IN (SELECT id FROM sys_dept WHERE id ? OR parent_id ?)这里的部门层级关系通过递归查询或预先存储的部门路径字段来处理具体得看你们部门的表结构设计。2.3 模块划分与关键类说明我把框架拆成了几个职责单一的模块使用时可以按需裁剪annotation模块包含DataAuth注解以及注解上的各个属性比如resourceType资源类型用于匹配动态规则、tableAlias默认表别名。context模块包含DataAuthContext当前请求上下文、UserContextHolder用户信息持有者。主要作用是存取当前登录用户、用户部门、角色、以及解析后的权限规则。handler模块包含DataAuthInterceptorSpringMVC拦截器负责在请求进入时读取注解并把上下文初始化到ThreadLocal中DataScopeHandler负责根据规则生成SQL片段。plugin模块包含MyBatis的拦截器实现核心是改写SQL。如果你不用MyBatis可以换成JDBC的StatementInspector或者直接用AOP在Service层拼条件这块是整套框架里最灵活的部分。在实际项目中我并不强制要求一定用MyBatis拦截器。如果某些团队用的是Spring JDBC Template那可以在DAO层包一层AOP在方法执行前后改写SQL如果某些SQL极其复杂拼接风险太大也可以降级为Service层通过ThreadLocal获取上下文后手动拼条件。框架的价值在于把上下文和规则解析统一起来而不一定在于某个具体的拦截技术。3. 快速上手一个完整的使用示例3.1 基础配置与依赖引入假设这是一个普通的SpringMVC项目基于Maven构建。第一步是在pom.xml中引入框架依赖如果是公司内部平台通常已经推到私有仓库dependency groupIdcom.example.common/groupId artifactIddata-auth-springmvc/artifactId version1.2.0/version /dependency然后在spring-mvc.xml里注册拦截器mvc:interceptors mvc:interceptor mvc:mappedPath value/**/ bean classcom.example.dataauth.handler.DataAuthInterceptor/ /mvc:interceptor /mvc:interceptors在MyBatis的配置里注册SQL改写插件plugins plugin interceptorcom.example.dataauth.plugin.DataAuthSqlInterceptor property namedialect valuemysql/ /plugin /plugins这里要注意一个细节拦截器的mappedPath不能只配业务接口路径因为很多数据权限的上下文初始化依赖于拦截器先执行。但如果项目里已经有其他拦截器做了登录用户校验建议把DataAuthInterceptor放在登录拦截器之后注册保证ThreadLocal里已经有用户信息可用。3.2 定义当前用户上下文框架本身不关心你是谁它只关心你往UserContextHolder里塞了什么。所以项目中需要有一个地方把登录用户信息填充进去。通常的做法是在登录拦截器或者认证过滤器里做这一步public class LoginInterceptor extends HandlerInterceptorAdapter { Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) { // 假设你已经从token或session中解析出了登录用户 LoginUser user parseUser(request); UserContext context new UserContext(); context.setUserId(user.getUserId()); context.setDeptId(user.getDeptId()); context.setRoleCode(user.getRoleCode()); // 如果用户拥有管理员角色可以设置一个标记 context.setAdmin(user.isAdmin()); UserContextHolder.set(context); return true; } Override public void afterCompletion(...) { UserContextHolder.clear(); } }UserContextHolder本质上就是一个ThreadLocal的封装public class UserContextHolder { private static final ThreadLocalUserContext CONTEXT new ThreadLocal(); public static void set(UserContext context) { CONTEXT.set(context); } public static UserContext get() { return CONTEXT.get(); } public static void clear() { CONTEXT.remove(); } }强调一点clear()必须在请求结束的afterCompletion里调用。我之前就见过有团队忘了清理导致线程池复用线程时A用户登录后看到了B用户的数据权限范围这种偶发问题极难排查。3.3 在业务方法上标注数据权限注解上下文准备好了接下来是框架使用中最直观的一步在需要控制数据权限的接口方法上添加DataAuth。比如一个订单列表查询接口原本的实现可能长这样RestController RequestMapping(/api/order) public class OrderController { GetMapping(/list) public ResultListOrderVO list(OrderQuery query) { ListOrder orders orderService.queryList(query); return Result.ok(orders); } }加上数据权限注解后GetMapping(/list) DataAuth(resourceType order, tableAlias o) public ResultListOrderVO list(OrderQuery query) { ... }这个resourceType order用来在运行时动态匹配该资源的权限规则。规则存在哪里存在数据库的sys_data_auth_rule表里。这张表的典型结构如下字段说明id主键resource_type资源类型比如order、customerrole_code角色编码比如manager、sales、financescope数据范围枚举值dept_id_column部门ID字段名user_id_column用户ID字段名table_alias默认表别名custom_sql自定义SQL片段scope为CUSTOM时使用enabled是否启用在运行时DataAuthInterceptor拿到DataAuth注解上的resourceType再结合当前用户所属的角色编码去查询这张表得到一条规则放入上下文。如果没有查到匹配的规则则默认放行不做额外限制。这样可以避免新增角色时忘记配规则导致功能不可用。3.4 核心环节SQL自动改写逻辑到了最关键的一步。DataAuthSqlInterceptor作为MyBatis插件会在Executor执行查询前拦截BoundSql并改写SQL。这里我简化了实现但保留了核心逻辑Intercepts({ Signature(type StatementHandler.class, method prepare, args {Connection.class, Integer.class}) }) public class DataAuthSqlInterceptor implements Interceptor { Override public Object intercept(Invocation invocation) throws Throwable { StatementHandler handler (StatementHandler) invocation.getTarget(); BoundSql boundSql handler.getBoundSql(); String originalSql boundSql.getSql(); // 1. 从上下文获取当前用户和规则 DataAuthContext context DataAuthContextHolder.getContext(); if (context null || !context.isAuthRequired()) { return invocation.proceed(); } // 2. 根据规则生成过滤SQL片段 String authSql DataScopeHandler.buildSql(context.getRule(), context.getUser()); if (StringUtils.isBlank(authSql)) { return invocation.proceed(); } // 3. 把过滤条件拼接到原始SQL的WHERE之后 String newSql SqlAppender.appendWhere(originalSql, authSql); // 通过反射修改BoundSql中的SQL ReflectUtil.setFieldValue(boundSql, sql, newSql); return invocation.proceed(); } }这个拦截器最复杂的地方不是拼接逻辑本身而是SqlAppender这个工具类。真实的SQL可能是SELECT o.* FROM t_order o LEFT JOIN t_customer c ON o.customer_id c.id WHERE o.status 1 ORDER BY o.create_time DESC如果直接无脑在SQL后面追加AND ...遇到没有WHERE子句的情况或者已有WHERE但拼出来语法错误就会直接让整个查询崩溃。所以拼接时要判断原始SQL是否含有WHERE关键字注意排除子查询中的WHERE是否含有GROUP BY、ORDER BY、LIMIT等关键字如果有过滤条件要插入到它们之前是否已经存在相同表别名的过滤条件避免同一个条件拼两遍导致重复。这部分代码实现的时候最好写一套完整的单元测试覆盖各种SQL形态。我自己在项目里就囤了一批测试用例包括子查询、带LEFT JOIN、带聚合函数、带UNION等场景。3.5 自定义数据范围与复杂场景示例上面讲的都是一般规则但实际业务里总有特殊情况。比如财务角色需要看到全公司的数据但前提是金额大于某个阈值再比如销售角色只能看到自己名下的客户但客户如果被转移给了别人还需要能看到转移记录。对于这类需求CUSTOM自定义SQL片段是最灵活的出口。假设资源类型为customer时某个特殊角色需要看到最近30天内创建且归属在本区域的客户规则表里可以这样配置{ scope: CUSTOM, customSql: c.owner_id IN (SELECT id FROM sys_user WHERE dept_id IN (SELECT id FROM sys_dept WHERE region_code EAST)) AND c.create_time DATE_SUB(NOW(), INTERVAL 30 DAY) }改写后的SQL大概是这样SELECT c.* FROM t_customer c WHERE c.owner_id IN (...) AND c.create_time ... AND (c.owner_id IN (SELECT id FROM sys_user WHERE dept_id IN (SELECT id FROM sys_dept WHERE region_code EAST)) AND c.create_time DATE_SUB(NOW(), INTERVAL 30 DAY))这个自定义片段其实是画蛇添足版的演示实际配置往往更精炼但它说明了一个关键能力当内置的四种范围满足不了需求时你可以在不写Java代码、不重启服务的前提下通过配置解决一个复杂的权限需求。这也是通用数据权限框架相对硬编码方案的最大优势之一。3.6 集成Spring Security或Shiro时怎么配合很多人会问如果我项目里已经用了Spring Security或者Shiro这套框架会和它们冲突吗实际并不会反而它们是互补关系。Spring Security负责认证和功能权限拦截在它的过滤器链里完成登录用户信息的解析然后我们这套框架的拦截器在进入Controller前拿到SecurityContext里的用户信息组装出自己的数据权限上下文。严格来说它只需要在SpringMVC的HandlerInterceptor层面工作根本不需要知道你是不是用了Security。如果你用的是Spring Boot并且集成了Spring Security可以这样配置Configuration public class DataAuthConfig implements WebMvcConfigurer { Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(new DataAuthInterceptor()) .addPathPatterns(/**) .excludePathPatterns(/login, /error); } }这里拦截器执行顺序要手动确认如果登录用户信息是通过Spring Security的Authentication对象持有的那DataAuthInterceptor需要想办法从SecurityContextHolder中读取用户信息同样塞到UserContextHolder里即可。框架本身不限制用户信息来源这是它通用的一个体现。4. 常见问题与排查技巧实录4.1 数据权限不生效问题可能出在哪这是被问得最多的一个问题。按照我的排查经验依次检查以下几个环节第一步确认拦截器有没有注册成功。很多坑都是配置文件的问题比如在SpringMVC中配置了mvc:interceptors但spring-mvc.xml扫描的包路径和Controller不一致导致拦截器根本没挂上。可以在DataAuthInterceptor.preHandle里加一行日志打点确认。第二步确认注解有没有被扫描到。DataAuth如果打在Service方法上但项目用的是SpringMVC的注解扫描配置只扫了Controller包那注解自然不会生效。我的建议是注解尽量打在Controller方法上因为它是请求入口语义也最清晰。第三步确认规则表里有没有配置对应的角色规则。框架的设计是查不到规则就放行所以如果你忘了在规则表里插入一条记录接口看起来一切正常但数据权限根本没生效。这种静默失败很容易让人误判。建议在规则未命中时打印一个告警日志方便后续排查。第四步确认ThreadLocal有没有被意外清理。如果项目中有异步操作比如把业务丢进线程池执行子线程是拿不到父线程ThreadLocal中的上下文的。这时需要你手动把上下文对象传递进去或者改用TransmittableThreadLocal来支持异步场景。4.2 SQL拼接导致语法错误这个是SQL改写插件最常见的故障。通常的表现是某个接口原本正常加了数据权限后直接报SQL语法错误。我遇到过的一个典型场景是子查询里的WHERE干扰判断。原始SQL是这样的SELECT * FROM t_order o WHERE o.amount 100看起来有WHERE直接在后面追加就是。但如果原始SQL是这样SELECT * FROM t_order o WHERE EXISTS (SELECT 1 FROM t_customer c WHERE c.id o.customer_id)此时SQL中出现了两个WHERE如果拼接逻辑只找第一个WHERE并且直接在其后追加结果可能是对的但如果拼接逻辑找的是最后一个WHERE就会把条件插到子查询里面去逻辑直接拧巴。还有一类问题更隐蔽原始SQL没有WHERE直接写成SELECT * FROM t_order ORDER BY create_time DESC拼接时如果判断没有WHERE就在FROM后面加WHERE你得处理ORDER BY的存在。所以我强烈建议SqlAppender这个工具类的编写必须配套充足的单元测试和样例SQL库。不要试图写一个万能的正则去解析SQL稳一点的做法是先尝试解析出主查询的WHERE子句位置再结合关键字优先级插入。如果解析过程中遇到无法识别的复杂SQL形态宁可跳过权限改写并将该请求记入异常日志也不要冒险拼接导致核心查询崩溃。4.3 权限规则过多或SQL过于复杂时遇到性能问题数据权限条件本身是一个IN (SELECT ...)或者EXISTS子查询。当部门层级深、数据量大时这种子查询的性能需要关注。一个常见优化是采用部门路径设计。很多系统在部门表里冗余了一个ancestors字段比如1,2,5代表部门ID为5且上级链路是1和2。这样本部门及子部门的条件就可以改写成o.dept_id IN (SELECT id FROM sys_dept WHERE ancestors LIKE CONCAT(1,2,, %))相比递归查询这种方案要快得多。如果你的数据量非常大比如千万级IN (SELECT ...)仍然不是最优解。更合理的方式是先把当前用户有权访问的部门ID集合查出来放到应用层缓存里然后生成IN (41, 42, 43, 44)这样静态的条件。虽然SQL文本会变长但对数据库优化器来说友好得多。我的建议是规则解析和权限条件生成可以做成两级缓存。一级是规则本身的缓存一级是用户有权访问的部门或数据ID集合的缓存。缓存失效策略可以做成角色变更时主动清理或定时刷新。4.4 多数据源与读写分离场景如果你的项目配置了多数据源MyBatis拦截器会拦截所有数据源的SQL执行这就有可能导致主库的权限规则被错误地应用到了从库报表的查询上。解决思路有两种在DataAuth注解上增加一个属性datasource表示该接口只对指定数据源启用权限控制或者在拦截器里根据当前事务的数据源名称做白名单过滤。另外数据权限改写主要针对SELECT操作。如果是UPDATE或DELETE理论上也应该做数据权限限制否则可能发生越权修改他人数据。但要注意UPDATE和DELETE语句的改写比SELECT更危险建议在框架的配置项中明确允许改写的操作类型。我见过因为权限条件漏了主键等值条件导致批量误更新的例子这里必须小心。4.5 常见问题速查表问题现象可能原因解决方案数据权限完全不生效拦截器未注册 / 规则未配置 / 注解未扫描逐项检查配置文件和规则表数据权限条件重复拼接多个拦截器同时处理或代理类重复调用在拼接前检查SQL中是否已包含相同别名条件子查询被错误修改SQL解析逻辑不健壮加强解析逻辑复杂SQL跳过并告警异步线程中权限丢失ThreadLocal未传递使用TransmittableThreadLocal或手动传参UPDATE语句越权未对UPDATE/DELETE做限制在拦截器中对非SELECT操作单独校验数据量越大查询越慢子查询未优化或缓存未生效改用部门路径、静态IN集合、两级缓存5. 扩展点、边界与一些个人经验5.1 框架的扩展点从能用到好用如果你已经跑通了上面的示例可以再考虑几个扩展方向让框架变得更适合你的团队规则来源扩展。目前规则存在数据库表里但有些公司希望用Apollo或Nacos这样的配置中心来做规则下发。其实只需要修改RuleProvider这个接口的实现从数据库读取改成从配置中心读取即可框架核心代码不用动。支持字段级脱敏。数据权限控制的是能看哪些行行级权限解决了但列级权限比如某些角色的用户不能看到客户手机号是另一个维度。可以把脱敏逻辑也做进拦截器里针对特定角色的查询结果做字段转换但要注意和分页插件、JSON序列化的兼容性。操作审计与追踪。数据权限框架天然是一个很好的审计埋点位置。在拦截器中记录什么角色、什么用户、在什么时间、访问了哪个资源、命中了哪条规则这些信息对安全合规很有价值。5.2 需要特别注意的边界情况这套框架不是万能的有几个场景我建议主动放弃SQL自动改写复杂的报表SQL。比如多级嵌套、动态SQL列、透视表等改写风险极高手动在SQL里写条件反而更可控。全文检索类查询。比如Elasticsearch的查询压根不走MyBatis的SQL执行链路数据权限需要另外处理。定时任务和消息队列消费场景。这些场景通常没有HttpServletRequestThreadLocal上下文是空的框架会自动放行。如果任务本身需要数据权限控制你需要手动构造UserContext塞进上下文再执行查询。5.3 我这几个月实操下来的体会最后分享几个真实经验。第一个是关于通用和可控的取舍。数据权限框架如果设计得太通用会陷入不断适配各种SQL方言和业务姿势的无底洞如果设计得太贴身每换一个项目就得重构一次。比较好的平衡点是把规则模型做通用把SQL解析和拦截器实现做成可插拔。第二个经验是千万不要把数据权限做成一个黑盒。业务团队对数据权限是非常敏感的线上出了越权问题第一反应是关掉你这个框架。所以一定要有完善的日志和开关。我在框架里加了一个全局开关如果配置中心里某个配置项为false则所有数据权限直接放行。这个开关在紧急事故时可以救命但也意味着默认必须为true并且要有监控告警。第三个经验是数据权限改写的SQL一定要纳入慢查询监控。权限条件拼接不当很容易把一个原本走索引的查询变成全表扫描。所以上线后我会重点观察那些开启数据权限的接口的SQL执行计划确认EXPLAIN结果里用到了合适的索引。以上这些就是这套基于SpringMVC的通用数据权限校验框架从设计到落地的完整经历。它不是什么惊天动地的黑科技但确实解决了很多项目中数据越权看不见、权限代码重复多、规则调整要发版的痛点。如果你也在做类似的事情希望这篇文章能给你省下一些摸索时间特别是SQL改写那一块测试用例一定要写足。