1. 项目概述：Sa-Token在Spring Boot中的权限控制实践

在Web应用开发中，接口权限控制是保障系统安全的核心环节。最近在重构一个内容管理系统时，我遇到了这样的需求：既要对/admin路径下的管理接口进行严格的登录校验，又要允许/public下的资源无需认证即可访问。经过技术选型对比，最终选择了Sa-Token这个轻量级权限认证框架，它仅需5行核心代码就能实现灵活的路径拦截策略。

Sa-Token不同于传统Shiro或Spring Security的复杂配置，其设计哲学是"约定优于配置"。最新1.27.0版本通过注解式权限控制、路由拦截器、会话管理三大模块，提供了开箱即用的解决方案。特别适合中小型项目快速实现：登录验证、权限认证、路由拦截等安全需求。下面我将分享在Spring Boot中整合Sa-Token的具体实践，包括动态排除路径的工程化实现方案。

2. 环境准备与依赖配置

2.1 项目基础环境搭建

推荐使用Spring Boot 2.7.x + JDK11的组合进行开发，这是目前企业级应用最稳定的版本搭配。在pom.xml中需要声明以下核心依赖：

<dependencies> <!-- Spring Boot基础starter --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- Sa-Token核心包 --> <dependency> <groupId>cn.dev33</groupId> <artifactId>sa-token-spring-boot-starter</artifactId> <version>1.27.0</version> </dependency> <!-- 配置属性提示支持 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-configuration-processor</artifactId> <optional>true</optional> </dependency> </dependencies>

注意：使用Spring Boot 3.x的用户需要将sa-token版本升级到1.30.0+，因为Spring Boot 3对Jakarta EE的支持存在兼容性问题。

2.2 配置属性自动提示

在IDE中启用配置属性自动提示功能，可以避免手写配置时的拼写错误。在application.yml同级目录创建additional-spring-configuration-metadata.json文件：

{ "properties": [ { "name": "security.excludes", "type": "java.lang.String[]", "description": "需要排除权限校验的路径模式", "sourceType": "com.example.config.SecurityProperties" } ] }

这样在编写application.yml时，输入"security"就会自动提示excludes属性，并显示我们添加的描述信息。这个小技巧能显著提升团队协作时的配置效率。

3. 动态路径排除方案实现

3.1 配置属性映射类设计

采用领域驱动设计思想，将安全相关属性集中管理。创建SecurityProperties类：

@Data @Component @ConfigurationProperties(prefix = "security") @Validated public class SecurityProperties { @NotNull(message = "排除路径不能为null") @Size(min = 1, message = "至少需要配置一个排除路径") private String[] excludes = new String[0]; @Pattern(regexp = "^(strict|loose)$", message = "模式必须是strict或loose") private String mode = "strict"; }

这里引入了JSR-303验证注解：

• @NotNull确保配置不为null
• @Size保证至少配置一个排除路径
• @Pattern限制运行模式取值

3.2 多环境差异化配置

在Spring Boot的多环境配置文件中，可以针对不同环境设置不同的排除策略：

application-dev.yml:

security: excludes: - "/public/**" - "/swagger-ui/**" - "/v3/api-docs" - "/actuator/health"

application-prod.yml:

security: excludes: - "/public/**" - "/api/v1/auth/login" mode: "strict"

这种配置方式既满足了开发阶段需要访问Swagger文档的需求，又保证了生产环境的最小开放原则。

4. 拦截器深度配置实践

4.1 增强型拦截器实现

基础版拦截器存在两个痛点：1) 无法记录拦截日志 2) 错误信息不友好。下面展示改进后的实现：

@Slf4j @Configuration @RequiredArgsConstructor public class SecurityConfig implements WebMvcConfigurer { private final SecurityProperties securityProperties; @Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(new SaInterceptor(handler -> { SaRouter.match("/**") .notMatch(securityProperties.getExcludes()) .check(r -> { try { StpUtil.checkLogin(); } catch (NotLoginException e) { log.warn("拦截未授权请求: {}", RequestHolder.getRequest().getRequestURI()); throw new BusinessException(401, "请先登录系统"); } }); })).addPathPatterns("/**"); } }

关键改进点：

1. 使用@Slf4j记录拦截日志
2. 通过NotMatch语法提高可读性
3. 自定义业务异常转换Sa-Token原生异常
4. 引入RequestHolder获取当前请求信息

4.2 拦截器执行顺序控制

当项目中有多个拦截器时，需要精确控制执行顺序。例如审计日志拦截器应该在权限拦截之前执行：

@Override public void addInterceptors(InterceptorRegistry registry) { // 审计日志拦截器 registry.addInterceptor(auditInterceptor) .order(Ordered.HIGHEST_PRECEDENCE); // 权限拦截器 registry.addInterceptor(saTokenInterceptor) .order(Ordered.HIGHEST_PRECEDENCE + 1); }

Sa-Token拦截器建议设置在中间优先级（默认是0），既不会影响基础功能的拦截器，又能保证在业务拦截前完成鉴权。

5. 实战中的疑难问题解决

5.1 静态资源被错误拦截

常见问题：虽然配置了/static/**排除路径，但CSS/JS文件仍然被拦截。解决方案：

1. 检查路径是否被Spring Boot默认映射：

@Configuration public class WebMvcConfig implements WebMvcConfigurer { @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("/static/**") .addResourceLocations("classpath:/static/"); } }

2. 确保Sa-Token排除模式与资源处理器一致：

security: excludes: - "/static/**"

5.2 网关层与应用层拦截冲突

在微服务架构下，可能出现网关和应用双重拦截导致401错误。推荐采用以下协作方案：

1. 网关层（如Spring Cloud Gateway）配置白名单：

spring: cloud: gateway: routes: - id: auth-service uri: lb://auth-service predicates: - Path=/api/auth/** filters: - name: SaTokenFilter args: exclude: - "/api/auth/public/**"

2. 应用层采用宽松模式：

security: mode: "loose"

这种分层防护体系既避免了重复拦截，又能实现纵深防御。

6. 高级特性扩展应用

6.1 注解式权限控制

除了路径拦截，Sa-Token还支持细粒度的注解控制：

@RestController @RequestMapping("/user") public class UserController { @SaCheckLogin @GetMapping("/profile") public R profile() { return R.success(UserService.getProfile()); } @SaCheckRole("admin") @PostMapping("/create") public R createUser(@Valid @RequestBody UserDTO dto) { return R.success(UserService.create(dto)); } }

注解优先级高于拦截器配置，适合需要精确到方法级的权限控制场景。

6.2 动态权限更新方案

对于需要热更新权限配置的场景，可以结合Redis发布订阅机制：

@EventListener public void handleRedisMessage(RedisMessageEvent event) { if ("security_update".equals(event.getChannel())) { SecurityProperties newProps = JSON.parseObject( event.getMessage(), SecurityProperties.class ); securityProperties.setExcludes(newProps.getExcludes()); log.info("安全配置已热更新"); } }

通过@RefreshScope或自定义事件监听，可以实现配置的动态生效，无需重启应用。

7. 性能优化与监控

7.1 拦截器性能测试

使用JMeter对拦截器进行压测（100并发，10000次请求）：

测试结果表明Sa-Token在性能损耗上明显优于传统方案。

7.2 监控指标暴露

通过Spring Boot Actuator暴露权限相关指标：

@Bean public MeterRegistryCustomizer<MeterRegistry> saTokenMetrics() { return registry -> { Gauge.builder("sa.token.active_sessions", StpUtil::getLoginCount) .register(registry); }; }

这样可以在Prometheus中监控当前活跃会话数，及时发现异常登录情况。

8. 安全加固建议

1. CSRF防护：在登录接口启用Sa-Token的CSRF防护

   @PostMapping("/login") public R login(@RequestBody LoginDTO dto) { StpUtil.checkCsrfToken(); // ...登录逻辑 }

2. 频控拦截：对敏感接口添加请求频率限制

   @SaCheckSafe("user:login") // 5分钟内最多失败5次 @PostMapping("/login") public R login(/*...*/) { /*...*/ }

3. 二次验证：关键操作需要短信/邮件验证

   @SaCheckSafe("account:delete") @SaCheckSecond("email") @DeleteMapping("/account") public R deleteAccount() { /*...*/ }

这些安全措施与路径拦截形成多层次的防护体系，大幅提升系统安全性。