SpringBoot集成Sa-Token与JWT完整指南

一、Sa-Token 是什么？它主要实现哪些功能？

简单来说，Sa-Token 是一套基于 Java 的认证授权框架，主要完成以下功能：

┌────────────┬───────────────────────────────────────────────────────┐
│ 功能       │ 说明                                                 │
├────────────┼───────────────────────────────────────────────────────┤
│ 登录认证   │ 用户输入账号密码后，系统签发 token，后续请求需携带 token 访问 │
├────────────┼───────────────────────────────────────────────────────┤
│ 权限校验   │ 判断用户是否拥有某个权限或角色                       │
├────────────┼───────────────────────────────────────────────────────┤
│ Token 管理 │ token 的生成、存储、过期、续期                         │
├────────────┼───────────────────────────────────────────────────────┤
│ 拦截器     │ 自动拦截未登录的请求，返回 401 状态码                   │
└────────────┴───────────────────────────────────────────────────────┘

JWT（JSON Web Token）是一种轻量级的 Token 格式。Sa-Token 默认使用随机字符串作为 token，如果你需要自包含的令牌，切换到 JWT 格式也非常简便。

二、集成 Sa-Token 前后项目功能对比

改造前（现在）

• POST /api/users → 任何人都可以访问，无需登录认证
• GET /api/users/1 → 任何人都能查询用户信息
• GET /api/users/1/avatar → 任何人都能下载头像

改造后

• POST /api/users/login → 登录接口，返回 token
• GET /api/users/1 → 需要携带有效 token 才能访问

Header: Authorization: token值

• DELETE /api/users/1 → 需要管理员权限才能删除

三、Spring Boot 集成 Sa-Token + JWT 具体步骤

3.1 在 pom.xml 中添加依赖

    cn.dev33
    sa-token-spring-boot3-starter
    1.39.0



cn.dev33
sa-token-redis-jackson
1.39.0



cn.dev33
sa-token-jwt
1.39.0

3.2 application.yml 配置文件

############## Sa-Token 配置 ##############
sa-token:
  # token 名称，同时作为 cookie 名称
  token-name: Authorization
  # token 有效期（秒），7 天
  timeout: 604800
  # 是否允许同一账号同时在线
  is-concurrent: true
  # 是否允许同一账号多地登录
  is-share: true
  # token 风格（可选：uuid、simple-uuid、random-32、random-64、random-128）
  token-style: uuid
  # 是否输出操作日志
  is-log: true
配置 JWT
jwt:
JWT 签名密钥，可自定义字符串
secret-key: abcdefghijklmnopqrstuvwxyz0123456789
token 签发者
issuer: test-project

3.3 SaTokenConfig.java — 配置拦截器

新建文件：src/main/java/com/test/config/SaTokenConfig.java

package com.test.config;
import cn.dev33.satoken.interceptor.SaInterceptor;
import cn.dev33.satoken.router.SaRouter;
import cn.dev33.satoken.stp.StpUtil;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Configuration
public class SaTokenConfig implements WebMvcConfigurer {
@Override
public void addInterceptors(InterceptorRegistry registry) {
    // 注册 Sa-Token 拦截器
    registry.addInterceptor(new SaInterceptor(handle -> {
        // 登录校验：拦截需要登录的路径
        SaRouter.match("/api/**")
                .notMatch("/api/users/login")
                .notMatch("/api/users/register")
                .check(r -> StpUtil.checkLogin());
    // 角色校验示例：仅 admin 角色可删除用户
    SaRouter.match("/api/users/**", r -> {
        if (handle.getRequest().getMethod().equals("DELETE")) {
            StpUtil.checkRole("admin");
        }
    });
})).addPathPatterns("/**");
}
}

3.4 修改 UserController.java — 添加登录接口

// ========== 登录接口 ==========
@PostMapping("/login")
public Map login(@RequestBody Map params) {
    String username = params.get("username");
    String password = params.get("password");
// 校验用户名和密码
User user = userService.getUserByUsername(username);
if (user == null || !user.getPassword().equals(password)) {
    return Map.of("success", false, "message", "用户名或密码错误");
}
// 登录成功，生成 token
StpUtil.login(user.getId());
String tokenValue = StpUtil.getTokenValue();
return Map.of("success", true, "message", "登录成功", "token", tokenValue, "user", user);
}
@GetMapping("/logout")
public Map logout() {
StpUtil.logout();
return Map.of("success", true, "message", "退出成功");
}
// 查看当前登录用户信息
@GetMapping("/me")
public Map me() {
long userId = StpUtil.getLoginIdAsLong();
User user = userService.getUserById(userId);
return Map.of("success", true, "user", user);
}

四、JWT 在 Sa-Token 认证流程中的作用

用户登录成功
↓
StpUtil.login(用户ID)
↓
Sa-Token 生成 Token
↓
默认格式：随机字符串 → "d8f9a0e1-2b3c-4d5e-..."
JWT 格式：令牌 → "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
↓
返回给前端
↓
前端每次请求携带此 token

JWT 的核心优势在于：Token 本身包含了用户信息（如用户ID、过期时间等），服务端无需查询数据库或 Redis 即可验证身份，非常适合分布式部署场景。

五、在业务代码中如何使用 Sa-Token 进行权限管理

5.1 获取当前登录用户

// 在 Controller 或 Service 中
long userId = StpUtil.getLoginIdAsLong(); // 获取当前登录用户的 ID
User user = userService.getUserById(userId);

5.2 校验权限与角色

// 判断是否已登录
StpUtil.isLogin()      // 返回 true/false
StpUtil.checkLogin()   // 未登录则抛出异常，返回 401
// 判断角色
StpUtil.hasRole("admin")    // 返回 true/false
StpUtil.checkRole("admin")  // 无权限则抛出异常
// 判断权限标识
StpUtil.hasPermission("user:delete")  // 返回 true/false

5.3 设置用户角色和权限

在登录成功时或 User 实体中定义：

// 登录成功后为用户分配角色
StpUtil.login(userId);
StpUtil.getTokenSession().set("role", "admin");

六、前端通过 HTTP 请求与 Sa-Token 交互示例

# 步骤1：登录获取 token
curl -X POST http://localhost:8080/api/users/login 
  -H "Content-Type: application/json" 
  -d '{"username":"admin","password":"123456"}'
返回：
{"success":true,"token":"eyJhbGciOiJIUzI1NiIs...","user":{...}}
步骤2：后续请求携带 token
curl http://localhost:8080/api/users/1 
-H "Authorization: eyJhbGciOiJIUzI1NiIs..."
步骤3：查看个人信息
curl http://localhost:8080/api/users/me
-H "Authorization: eyJhbGciOiJIUzI1NiIs..."

七、生产环境部署注意事项

1. 密码必须加密存储

当前数据库中的密码为明文 123456，生产环境务必使用加密算法：

// 注册时加密
String encodedPassword = BCrypt.gensalt().encode(password);
// 登录时校验
boolean matches = BCrypt.checkpw(inputPassword, user.getPassword());

2. 返回用户信息时需隐藏密码字段

// 序列化时忽略密码字段
@JsonIgnore
private String password;

3. 合理配置拦截器路径

• /api/users/login → 不拦截（允许用户登录）
• /api/users/register → 不拦截（允许用户注册）
• /api/** → 拦截（需要登录）
• /api/admin/** → 拦截（需要管理员角色）

八、总结：Sa-Token + JWT 集成方案总览

┌───────────────┬────────────────────────────────────────────────┐
│ 组件          │ 在这个项目中的作用                             │
├───────────────┼────────────────────────────────────────────────┤
│ Sa-Token      │ 登录认证、token 管理、权限校验、请求拦截         │
├───────────────┼────────────────────────────────────────────────┤
│ JWT           │ Token 的格式标准（用户信息编码在 token 中）     │
├───────────────┼────────────────────────────────────────────────┤
│ SaInterceptor │ 自动拦截未登录请求，无需在每个 Controller 中编写判断逻辑 │
├───────────────┼────────────────────────────────────────────────┤
│ StpUtil       │ 核心工具类，提供登录/登出/获取用户/校验权限等操作 │
└───────────────┴────────────────────────────────────────────────┘