Spring Boot 集成 Sa-Token：权限认证从未如此简单！

视频看了几百小时还迷糊？关注我，几分钟让你秒懂！

在开发 Web 项目时，登录认证、权限控制、会话管理几乎是每个系统都绕不开的需求。传统方案如 Spring Security 虽然强大，但配置复杂、学习成本高；而 JWT 又要自己处理 token 刷新、登出等问题。

有没有一个 轻量、简单、功能全 的权限框架？

答案就是 —— Sa-Token！

今天我们就用 Spring Boot + Java，手把手教你集成 Sa-Token，实现 登录、鉴权、角色权限、踢人下线 等核心功能，10 分钟搞定权限系统！

🧩 一、Sa-Token 是什么？

Sa-Token 是一个 国产、轻量、高效 的 Java 权限认证框架，主打：

• ✅ 登录认证（Token 管理）
• ✅ 权限验证（角色 & 权限码）
• ✅ Session 会话（分布式无状态）
• ✅ 踢人下线、账号封禁
• ✅ 单点登录（SSO）、OAuth2 支持
• ✅ 零配置启动，API 极简

官网：https://sa-token.dev33.cn

🔧 二、快速集成（5 步搞定）

1. 添加 Maven 依赖

<dependency>
<groupId>cn.dev33</groupId>
<artifactId>sa-token-spring-boot-starter</artifactId>
<version>1.38.0</version> <!– 建议使用最新版 –>
</dependency>

⚠️ 注意：不需要额外引入 Redis 依赖！Sa-Token 默认使用内存存储，生产环境建议配 Redis。

2. 配置 application.yml（可选）

sa-token:
# token 名称（默认 satoken）
token-name: Authorization
# token 有效期（秒），默认 7 天
timeout: 2592000
# token 最低活跃时间（秒），默认 0（不刷新）
active-timeout: 1800
# 是否允许同一账号多地登录（true=允许，false=踢掉前一个）
is-concurrent: true
# 是否启用二级认证（如短信验证码）
is-share: false
# token 风格（默认为：uuid）
token-style: uuid
# 是否输出日志
is-log: true

💡 初学者可以先不配，全部用默认值！

3. 模拟用户登录接口

@RestController
public class LoginController {

// 模拟数据库用户（实际应查数据库）
private static final Map<String, String> USER_DB = Map.of(
"admin", "123456",
"user", "123456"
);

@PostMapping("/login")
public String login(@RequestParam String username, @RequestParam String password) {
// 1. 校验账号密码
if (!USER_DB.containsKey(username) || !USER_DB.get(username).equals(password)) {
return "账号或密码错误";
}

// 2. 写入当前登录用户 ID（Sa-Token 自动创建 Token 并绑定会话）
StpUtil.login(10001L); // 假设 admin 的 ID 是 10001

// 3. 返回 Token（前端需保存到 localStorage 或 Cookie）
return "登录成功，Token: " + StpUtil.getTokenValue();
}

@GetMapping("/logout")
public String logout() {
StpUtil.logout(); // 当前会话注销
return "已退出登录";
}
}

✅ 调用 StpUtil.login(userId) 后，Sa-Token 会自动生成 Token 并关联用户会话！

4. 受保护的接口（需要登录才能访问）

@RestController
public class UserController {

// 必须登录才能访问
@GetMapping("/user/info")
public Object getUserInfo() {
// 获取当前登录用户 ID
Long userId = StpUtil.getLoginIdAsLong();
return Map.of("userId", userId, "username", "admin");
}

// 必须具有 admin 角色
@GetMapping("/admin/setting")
public String adminSetting() {
// 校验是否具有 admin 角色（会抛异常，若无权限）
StpUtil.checkRole("admin");
return "管理员设置页面";
}

// 必须具有 user:delete 权限
@GetMapping("/user/delete")
public String deleteUser() {
StpUtil.checkPermission("user:delete");
return "删除用户成功";
}
}

5. 全局拦截器（自动鉴权）

Sa-Token 提供了 注解式鉴权 和 路由拦截器 两种方式。我们这里用更灵活的 拦截器。

@Configuration
public class SaTokenConfigure implements WebMvcConfigurer {

// 注册 Sa-Token 拦截器
@Override
public void addInterceptors(InterceptorRegistry registry) {
// 所有请求都校验 Token（除了 /login 等公开接口）
registry.addInterceptor(new SaRouteInterceptor())
.addPathPatterns("/**")
.excludePathPatterns("/login", "/doc.html", "/webjars/**", "/swagger-resources/**");
}
}

✅ 这样，所有未登录的请求访问 /user/info 都会返回 401！

🔐 三、权限模型：角色 vs 权限码

Sa-Token 支持两种权限控制：

如何给用户分配角色/权限？

重写 StpInterface 接口：

@Component
public class StpInterfaceImpl implements StpInterface {

// 返回用户拥有的角色集合
@Override
public List<String> getRoleList(Object loginId, String loginType) {
// 模拟：ID=10001 的用户是 admin
if ("10001".equals(loginId.toString())) {
return Arrays.asList("admin");
}
return Arrays.asList("user");
}

// 返回用户拥有的权限码集合
@Override
public List<String> getPermissionList(Object loginId, String loginType) {
if ("10001".equals(loginId.toString())) {
return Arrays.asList("user:add", "user:delete", "user:update");
}
return Arrays.asList("user:add");
}
}

✅ Sa-Token 会在调用 checkRole() 或 checkPermission() 时自动调用此接口！

🚨 四、反例：常见错误配置

❌ 反例1：忘记注册拦截器

// 没有 addInterceptors -> 所有接口无需登录也能访问！

后果：安全漏洞，任何人都能调用 /admin/setting！

❌ 反例2：登录后没返回 Token 给前端

@PostMapping("/login")
public void login(…) {
StpUtil.login(10001L);
// 忘记 return token！
}

后果：前端不知道 Token 是什么，后续请求无法携带，一直 401！

❌ 反例3：生产环境用内存存储（默认）

Sa-Token 默认将会话存在 JVM 内存中，重启服务所有用户掉线！

✅ 正确做法：集成 Redis

<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>

Sa-Token 会自动检测 Redis，无需额外配置！

🛠 五、高级功能（一键实现）

✅ 六、注意事项

🎯 总结

• Sa-Token 极简集成，5 行代码搞定登录；
• 支持 角色 + 权限码 双模型，灵活控制；
• 内置 踢人、会话查询、单点登录 等企业级功能；
• 自动适配 Redis，分布式无忧；
• 比 Spring Security 简单 10 倍，比 JWT 更安全！

从此，权限认证不再是难题！

视频看了几百小时还迷糊？关注我，几分钟让你秒懂！