Sa-Token 基础及 Spring Boot 集成实战指南_Java

一、sa-token 简介

sa-token 是一个轻量级 java 权限认证框架，主要解决登录认证、权限认证、单点登录、oauth2.0、分布式 session 会话等一系列与权限相关的问题。相比于 shiro 和 spring security，sa-token 具有以下特点：

简单易用：api 设计直观，学习成本低
功能全面：覆盖大部分认证授权场景
轻量高效：不依赖复杂设计，性能优异
模块化设计：可按需引入功能模块
良好扩展性：支持自定义各种组件

二、核心概念

1. 登录认证流程

用户登录 -> 生成token -> 存储token -> 返回给客户端
客户端携带token -> 服务器验证token -> 访问受保护资源

2. 核心组件

stputil：核心工具类，提供登录、注销、权限校验等操作
satokenconfig：配置类，可自定义各种参数
sainterceptor：拦截器，实现路由拦截鉴权
satokendao：token 持久层接口，默认内存实现，可扩展为 redis

3. 主要功能

登录认证
权限认证（角色/权限）
session 管理
踢人下线
多账号体系
单点登录
模拟他人账号
临时身份切换

三、spring boot 集成实战

1. 添加依赖

<!-- sa-token 核心包 -->
<dependency>
    <groupid>cn.dev33</groupid>
    <artifactid>sa-token-spring-boot-starter</artifactid>
    <version>最新版本</version>
</dependency>
<!-- 如果使用redis持久化 -->
<dependency>
    <groupid>cn.dev33</groupid>
    <artifactid>sa-token-dao-redis</artifactid>
    <version>最新版本</version>
</dependency>
<dependency>
    <groupid>org.apache.commons</groupid>
    <artifactid>commons-pool2</artifactid>
</dependency>

2. 基础配置

# application.yml
sa-token:
  # token名称 (同时也是cookie名称)
  token-name: satoken
  # token有效期，单位s 默认30天
  timeout: 2592000
  # token临时有效期 (指定时间内无操作就视为token过期) 单位: 秒
  activity-timeout: -1
  # 是否允许同一账号并发登录 (为true时允许一起登录, 为false时新登录挤掉旧登录)
  is-concurrent: true
  # 在多人登录同一账号时，是否共用一个token (为true时所有登录共用一个token, 为false时每次登录新建一个token)
  is-share: true
  # token风格
  token-style: uuid
  # 是否输出操作日志
  is-log: true

3. 登录认证实现

@restcontroller
@requestmapping("/user/")
public class usercontroller {
    @postmapping("dologin")
    public saresult dologin(string username, string password) {
        // 模拟数据库校验
        if("admin".equals(username) && "123456".equals(password)) {
            // 登录成功，生成token
            stputil.login(10001);
            return saresult.ok("登录成功").setdata(stputil.gettokeninfo());
        }
        return saresult.error("登录失败");
    }
    // 查询登录状态
    @getmapping("islogin")
    public saresult islogin() {
        return saresult.ok("是否登录：" + stputil.islogin());
    }
    // 退出登录
    @getmapping("logout")
    public saresult logout() {
        stputil.logout();
        return saresult.ok();
    }
}

4. 权限认证实现

@restcontroller
@requestmapping("/admin/")
public class admincontroller {
    // 权限校验：必须具有admin权限才能进入
    @sacheckpermission("admin")
    @getmapping("menu")
    public saresult menu() {
        return saresult.data("管理员菜单");
    }
    // 角色校验：必须具有super-admin角色才能进入
    @sacheckrole("super-admin")
    @getmapping("settings")
    public saresult settings() {
        return saresult.data("系统设置");
    }
    // 二级认证：必须输入密码进行二次验证后才能进入
    @sachecksafe()
    @getmapping("criticaloperation")
    public saresult criticaloperation() {
        return saresult.data("关键操作");
    }
}

5. 全局拦截器配置

@configuration
public class satokenconfigure implements webmvcconfigurer {
    // 注册sa-token的注解拦截器，打开注解式鉴权功能
    @override
    public void addinterceptors(interceptorregistry registry) {
        // 注册注解拦截器
        registry.addinterceptor(new sainterceptor()).addpathpatterns("/**");
    }
}

四、进阶功能

1. redis 集成（分布式会话）

# application.yml
spring:
  redis:
    host: 127.0.0.1
    port: 6379
    password: 
    database: 0
sa-token:
  # 配置token持久化到redis
  is-share: true
  is-read-body: false
  is-read-head: true
  is-v: false
  token-prefix: "satoken:"
  jwt-secret-key: null
  id-token-timeout: 86400
  dao: "redis"

2. 自定义会话管理

@component
public class customsatokendao extends satokendaodefaultimpl {
    // 重写数据访问层方法，例如使用mongodb存储
    @override
    public string get(string key) {
        // 自定义实现
        return super.get(key);
    }
    @override
    public void set(string key, string value, long timeout) {
        // 自定义实现
        super.set(key, value, timeout);
    }
}

3. 注解鉴权

sa-token 提供丰富的注解用于权限控制：

@sachecklogin: 登录校验
@sacheckrole("admin"): 角色校验
@sacheckpermission("user:add"): 权限校验
@sachecksafe: 二级认证校验
@sacheckbasic: httpbasic校验

4. 路由拦截鉴权

@configuration
public class satokenconfigure implements webmvcconfigurer {
    @override
    public void addinterceptors(interceptorregistry registry) {
        registry.addinterceptor(new sainterceptor(handler -> {
            // 登录校验 -- 拦截所有路由
            sarouter.match("/**").check(r -> stputil.checklogin());
            // 角色校验 -- 拦截以 admin 开头的路由
            sarouter.match("/admin/**").check(r -> stputil.checkrole("admin"));
            // 权限校验 -- 不同模块校验不同权限
            sarouter.match("/user/**", r -> stputil.checkpermission("user"));
            sarouter.match("/order/**", r -> stputil.checkpermission("order"));
        })).addpathpatterns("/**");
    }
}

五、最佳实践

token 安全
- 使用 https
- 设置合理的 token 有效期
- 避免 token 在 url 中传输
- 实现 token 续期机制
权限设计
- 遵循最小权限原则
- 使用 rbac (基于角色的访问控制) 模型
- 实现权限缓存机制
性能优化
- 对于分布式系统使用 redis 存储 token
- 合理设置 token 的过期时间
- 实现本地缓存减少持久层访问
监控与日志
- 记录关键认证操作
- 监控异常登录行为
- 实现登录设备管理

六、常见问题解决方案

token 失效问题
- 检查 token 过期时间设置
- 验证 token 持久化是否正常工作
- 检查是否有并发登录冲突

跨域问题

@configuration
public class webmvcconfig implements webmvcconfigurer {
    @override
    public void addcorsmappings(corsregistry registry) {
        registry.addmapping("/**")
                .allowedorigins("*")
                .allowedmethods("*")
                .allowedheaders("*")
                .exposedheaders("satoken"); // 重点暴露satoken头
    }
}

自定义响应格式

@restcontrolleradvice
public class globalexceptionhandler {
    // 拦截所有未处理的satoken异常
    @exceptionhandler(satokenexception.class)
    public saresult handlersatokenexception(satokenexception e) {
        return saresult.error(e.getmessage());
    }
}

多账号体系

// 对于不同的账号体系，可以使用不同的stputil
stputil.stplogic("user").login(10001);  // 用户体系登录
stputil.stplogic("admin").login(1);     // 管理员体系登录

七、总结

sa-token 作为一个轻量级的权限认证框架，通过简单的 api 设计和丰富的功能，能够满足大多数应用的认证授权需求。与 spring boot 的集成非常简便，通过少量配置即可实现强大的权限控制功能。

相比传统的 shiro 和 spring security，sa-token 的学习曲线更为平缓，且针对常见场景提供了开箱即用的解决方案。特别是对于中小型项目，sa-token 能够显著降低权限系统的开发成本。

在实际项目中，建议根据业务需求选择合适的持久化方案（内存或 redis），合理设计权限模型，并遵循安全最佳实践，以构建安全可靠的认证授权系统。

到此这篇关于sa-token 基础及 spring boot 集成实战指南的文章就介绍到这了,更多相关spring boot 集成内容请搜索代码网以前的文章或继续浏览下面的相关文章希望大家以后多多支持代码网！

Sa-Token 基础及 Spring Boot 集成实战指南

2025年08月25日 • Java •我要评论