Sa-Token+JWT集成到SpringBoot完整指南

一、Sa-Token 是干什么的？

简单来说，Sa-Token 就是一套 Ja va 认证授权框架，干的事无非这几件：

┌────────────┬───────────────────────────────────────────────────────┐
│ 功能       │ 说明                                                 │
├────────────┼───────────────────────────────────────────────────────┤
│ 登录认证   │ 用户输入账号密码 → 签发 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/a vatar → 任何人都能下载

改造后

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

Header: Authorization: token值

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

三、集成步骤

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:
签名密钥，随便写一段字符串
secret-key: abcdefghijklmnopqrstuvwxyz0123456789
token 签发者
issuer: test-project

3.3 SaTokenConfig.ja va — 配置拦截器

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

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.ja va — 加登录接口

// ========== 登录 ==========
@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 就能验证身份，适合分布式场景。

五、业务代码中如何使用

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");

六、前端请求方式

# 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      │ 登录认证、token 管理、权限校验、请求拦截         │
├───────────────┼────────────────────────────────────────────────┤
│ JWT           │ Token 的格式标准（用户信息编码在 token 中）     │
├───────────────┼────────────────────────────────────────────────┤
│ SaInterceptor │ 自动拦截未登录请求，不用每个 Controller 写判断 │
├───────────────┼────────────────────────────────────────────────┤
│ StpUtil       │ 核心工具类，登录/登出/获取用户/校验权限         │
└───────────────┴────────────────────────────────────────────────┘