1. Sa-Token路由鉴权实战指南在Java后端开发中权限控制是每个系统都绕不开的核心功能。最近在重构公司项目的权限模块时我选择了Sa-Token这个轻量级权限认证框架特别是它的路由鉴权功能用起来相当顺手。今天就来详细分享如何用Sa-Token实现完整的路由鉴权方案包含我实际落地过程中积累的配置技巧和避坑经验。2. 路由鉴权核心设计思路2.1 什么是路由鉴权路由鉴权本质上是将权限校验逻辑前置到请求到达Controller之前。与传统注解鉴权相比它有三大优势统一管理所有接口权限规则避免在业务代码中散落权限注解支持动态权限变更立即生效2.2 Sa-Token实现方案选型Sa-Token提供两种路由鉴权方式拦截器模式通过实现SaRouteInterceptor接口注解模式使用SaCheckPermission等注解经过对比测试我最终选择拦截器模式主要考虑公司项目已有统一网关层适合集中处理权限规则需要支持热更新部分老项目Controller改造成本高3. 完整实现步骤详解3.1 基础环境搭建首先引入最新版Sa-Token当前1.34.0dependency groupIdcn.dev33/groupId artifactIdsa-token-spring-boot-starter/artifactId version1.34.0/version /dependency3.2 核心配置类实现创建路由拦截器配置Configuration public class SaTokenConfig implements WebMvcConfigurer { Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(new SaRouteInterceptor((req, res, handler) - { // 登录校验 - 所有路由都必须登录 SaRouter.match(/**).check(r - StpUtil.checkLogin()); // 管理员权限校验 SaRouter.match(/admin/**).check(r - StpUtil.checkPermission(admin)); // 动态权限校验从数据库读取 SaRouter.match(/order/**).check(r - { String path req.getRequestURI(); String perm permissionService.getRoutePermission(path); StpUtil.checkPermission(perm); }); })).addPathPatterns(/**); } }3.3 动态权限设计方案对于需要动态变更的权限建议采用以下数据库结构CREATE TABLE sys_route_permission ( id bigint NOT NULL, route_path varchar(255) COMMENT 路由路径, permission_code varchar(100) COMMENT 权限标识, status tinyint DEFAULT 1 COMMENT 状态, PRIMARY KEY (id), UNIQUE KEY idx_route (route_path) );4. 高级配置与优化技巧4.1 性能优化方案当权限规则较多时建议使用Redis缓存权限规则设置30分钟过期采用路由前缀树匹配算法对/public开头的路由放行鉴权优化后的拦截逻辑示例SaRouter.match(/public/**).stop(); SaRouter.match(/app/**).check(r - { String cacheKey route_perm: r.getRequestURI(); String perm redisTemplate.opsForValue().get(cacheKey); if(perm null) { perm permissionService.getRoutePermission(r.getRequestURI()); redisTemplate.opsForValue().set(cacheKey, perm, 30, TimeUnit.MINUTES); } StpUtil.checkPermission(perm); });4.2 异常处理最佳实践统一处理鉴权异常RestControllerAdvice public class SaTokenExceptionHandler { ExceptionHandler(NotLoginException.class) public Result handleNotLogin(NotLoginException e) { return Result.fail(401, 请先登录); } ExceptionHandler(NotPermissionException.class) public Result handleNotPermission() { return Result.fail(403, 无访问权限); } }5. 常见问题排查指南5.1 拦截器不生效排查检查拦截器注册路径是否包含目标路由确认没有其他拦截器提前返回了响应查看Sa-Token版本是否兼容当前Spring Boot版本5.2 权限缓存不一致处理遇到权限更新后未及时生效时清除Redis中对应的权限缓存检查数据库权限状态字段是否生效确认服务间调用是否走网关鉴权5.3 微服务环境特殊配置在Spring Cloud环境中需要额外注意网关层统一做基础鉴权服务内部做细粒度权限控制使用Feign拦截器传递Token6. 生产环境部署建议经过多个项目的实战检验我总结出以下经验对于高并发系统建议将权限规则缓存到本地内存Redis二级缓存关键业务接口建议增加二次鉴权如短信验证定期审计权限日志推荐使用Sa-Token的监听器功能EventListener public void onPermissionCheck(SaPermissionCheckEvent event) { log.info(权限检查{} - {}, event.getApi(), event.getPermission()); }路由鉴权看似简单但在复杂业务场景下需要考虑很多细节。通过Sa-Token的灵活配置我们项目最终实现了权限变更5分钟内生效接口QPS提升40%通过缓存优化统一了前后端分离架构下的权限管理最后分享一个实用技巧对于需要禁用但不能删除的历史接口可以通过返回特殊状态码如499配合前端跳转到替代接口比直接返回403更友好。