Sa-Token路由拦截鉴权详解：优雅实现接口权限控制

Sa-Token路由拦截鉴权详解：优雅实现接口权限控制

Sa-Token 一个轻量级 Java 权限认证框架，让鉴权变得简单、优雅！—— 登录认证、权限认证、分布式Session会话、微服务网关鉴权、单点登录、OAuth2.0 项目地址: https://gitcode.com/gh_mirrors/sa/Sa-Token

一、路由拦截鉴权概述

在现代Web应用中，接口权限控制是保障系统安全的重要环节。Sa-Token作为一款轻量级Java权限认证框架，提供了强大的路由拦截鉴权功能，能够帮助开发者以声明式的方式轻松实现接口访问控制。

路由拦截鉴权的核心思想是：根据请求路径匹配规则，对符合特定条件的请求执行权限校验。相比传统的在每个Controller方法上加注解的方式，路由拦截更加集中、灵活，特别适合需要批量控制接口访问权限的场景。

二、基础使用示例

1. 最简单的登录校验拦截

假设我们需要实现"所有接口需要登录，但登录接口本身除外"的需求，可以这样配置：

@Configuration
public class SaTokenConfigure implements WebMvcConfigurer {
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new SaInterceptor(handle -> StpUtil.checkLogin()))
                .addPathPatterns("/**")
                .excludePathPatterns("/user/doLogin");
    }
}

这段代码做了三件事：

1. 创建SaInterceptor拦截器，设置基础校验规则为登录检查
2. 拦截所有路径(/**)
3. 排除登录接口(/user/doLogin)

2. 进阶：模块化权限控制

实际项目中，我们通常需要根据不同业务模块设置不同的权限：

@Configuration
public class SaTokenConfigure implements WebMvcConfigurer {
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new SaInterceptor(handler -> {
            // 通用登录校验
            SaRouter.match("/**")
                   .notMatch("/user/doLogin")
                   .check(r -> StpUtil.checkLogin());
            
            // 模块权限校验
            SaRouter.match("/user/**", r -> StpUtil.checkPermission("user"));
            SaRouter.match("/admin/**", r -> StpUtil.checkPermission("admin"));
            // 其他模块...
        })).addPathPatterns("/**");
    }
}

三、路由匹配的多种方式

Sa-Token提供了丰富的路由匹配方式，满足各种复杂场景：

1. 路径匹配

// 匹配多个路径
SaRouter.match("/user/**", "/goods/**").check(...);

// 排除特定路径
SaRouter.match("/**").notMatch("*.html", "*.css").check(...);

2. 请求方法匹配

// 只拦截GET请求
SaRouter.match(SaHttpMethod.GET).check(...);

3. 条件匹配

// 根据布尔条件匹配
SaRouter.match(StpUtil.isLogin()).check(...);

// 根据Lambda表达式匹配
SaRouter.match(r -> r.getRequest().getHeader("X-Token") != null).check(...);

4. 组合匹配

SaRouter
    .match(SaHttpMethod.POST)
    .match("/admin/**")
    .notMatch("/admin/export")
    .check(...);

四、流程控制与作用域

1. 中断匹配链

// stop()会停止后续匹配，但会继续执行Controller
SaRouter.match("/**").check(...).stop();

// back()会直接返回响应，不执行Controller
SaRouter.match("/error").back("系统错误");

2. 独立作用域

SaRouter.match("/**").free(r -> {
    // 这里的stop只会跳出当前free块
    SaRouter.match("/temp/**").check(...).stop();
});
// 这里的匹配会继续执行
SaRouter.match("/**").check(...);

五、注解与拦截器的配合

1. 使用@SaIgnore忽略校验

@SaIgnore
@RequestMapping("/public/data")
public SaResult getPublicData() {
    // 此接口将跳过所有路由拦截校验
    return SaResult.data(...);
}

2. 关闭注解校验能力

如果只想使用路由拦截，可以关闭注解校验：

new SaInterceptor(...).isAnnotation(false)

六、最佳实践建议

1. 分层设计：将公共校验（如登录检查）与模块校验分开，提高可读性
2. 合理使用排除规则：对静态资源、公开接口等做好排除配置
3. 注意匹配顺序：路由匹配是按代码顺序执行的，应将更具体的规则放在前面
4. 适度使用free作用域：复杂场景下使用free可以更好地控制校验流程

七、总结

Sa-Token的路由拦截鉴权功能通过简洁的API提供了强大的权限控制能力。无论是简单的登录校验，还是复杂的多模块权限系统，都能通过合理的路由配置优雅实现。相比传统方式，它具有以下优势：

1. 配置集中，便于维护
2. 规则灵活，支持多种匹配方式
3. 执行效率高，减少重复校验
4. 与注解鉴权互补，形成完整权限体系

掌握Sa-Token的路由拦截功能，能够显著提升开发效率，构建更加安全的Web应用。

Sa-Token 一个轻量级 Java 权限认证框架，让鉴权变得简单、优雅！—— 登录认证、权限认证、分布式Session会话、微服务网关鉴权、单点登录、OAuth2.0 项目地址: https://gitcode.com/gh_mirrors/sa/Sa-Token