Sa-Token 是由 Dromara 开源社区孵化的一款**轻量级 Java 权限认证框架**，以“**简单、优雅、功能强**”为核心，专注解决登录认证、权限校验、会话管理、单点登录、OAuth2.0 及微服务网关鉴权等一系列权限问题。

一、核心优势

• 极简API：一行代码完成登录、鉴权、踢人等操作，零配置可启动。
• 功能全面：覆盖登录、权限、会话、SSO、OAuth2.0、微服务网关等。
• 高扩展性：支持 Redis/JWT 持久化、自定义权限验证逻辑。
• 生态丰富：无缝适配 SpringBoot、WebFlux、Solon、Gateway 等。
• 轻量无侵入：核心包仅几百 KB，不污染业务代码。

二、核心功能

1. 登录认证（最常用）

• 会话登录
  java StpUtil.login(1001); // 账号ID=1001登录
• 校验登录
  java StpUtil.checkLogin(); // 未登录抛异常
• 获取当前用户
  java Object loginId = StpUtil.getLoginId(); // 账号ID String token = StpUtil.getTokenValue(); // 当前Token
• 登出
  java StpUtil.logout();
• 踢人下线
  java StpUtil.kickout(1001); // 账号ID=1001强制下线

2. 权限与角色认证（注解/代码）

注解式（推荐）

@RestController
@RequestMapping("/user")
public class UserController {
    // 必须登录
    @SaCheckLogin
    @GetMapping("/info")
    public String info() {
        return "用户信息：" + StpUtil.getLoginId();
    }

    // 必须有 admin 角色
    @SaCheckRole("admin")
    @GetMapping("/admin")
    public String admin() {
        return "管理员面板";
    }

    // 必须有 user:delete 权限
    @SaCheckPermission("user:delete")
    @DeleteMapping("/{id}")
    public String delete(@PathVariable Long id) {
        return "删除用户：" + id;
    }
}

代码式

// 校验角色
StpUtil.checkRole("admin");
// 校验权限
StpUtil.checkPermission("user:add");

自定义权限数据源（从DB/Redis读权限）

@Component
public class StpInterfaceImpl implements StpInterface {
    // 返回账号拥有的权限
    @Override
    public List<String> getPermissionList(Object loginId, String loginType) {
        // 从DB查：loginId 对应的权限
        return Arrays.asList("user:add", "user:delete");
    }
    // 返回账号拥有的角色
    @Override
    public List<String> getRoleList(Object loginId, String loginType) {
        return Arrays.asList("admin", "user");
    }
}

3. Session 会话

• Token-Session（当前Token专属）
  java SaSession session = StpUtil.getTokenSession(); session.set("key", "value"); Object val = session.get("key");
• Account-Session（账号全端共享）
  java SaSession session = StpUtil.getSessionByLoginId(1001);

4. 分布式与 Redis 集成

pom.xml

<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-redis</artifactId>
    <version>最新版</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>

application.yml

sa-token:
  token-name: satoken       # 请求头Token名
  timeout: 1800            # Token有效期（秒）
  is-concurrent: true      # 允许多端登录
  is-share: true           # Cookie共享
  token-style: uuid        # Token风格
  is-log: true             # 打印日志
spring:
  redis:
    host: 127.0.0.1
    port: 6379

5. 微服务网关鉴权（Gateway示例）

@Configuration
public class SaTokenConfig {
    @Bean
    public SaGatewayFilter saGatewayFilter() {
        return new SaGatewayFilter()
            .setExcludeUrl("/user/login") // 放行登录
            .setAuth(r -> {
                // 全局校验登录
                StpUtil.checkLogin();
            });
    }
}

6. 单点登录（SSO）

• 支持同域/跨域/不共享Redis三种模式。
• 服务端：@SaSsoServer
• 客户端：SaSsoUtil.checkLogin()

7. OAuth2.0

• 支持授权码、简化、密码、客户端凭证四种模式。
• 内置授权服务、资源服务、接口。

三、SpringBoot 快速集成

1. 引入依赖

<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-spring-boot-starter</artifactId>
    <version>1.44.0</version> <!-- 最新版 -->
</dependency>

2. 配置（可选）

sa-token:
  token-name: Authorization
  timeout: 2592000     # 30天
  active-timeout: -1   # 不活跃永不过期
  is-concurrent: true  # 允许多端登录
  is-read-cookie: true
  is-read-header: true

3. 登录接口

@PostMapping("/login")
public SaResult login(String username, String password) {
    // 1. 校验用户名密码（DB）
    if (!"admin".equals(username) || !"123456".equals(password)) {
        return SaResult.error("账号或密码错误");
    }
    // 2. 登录
    StpUtil.login(1001);
    // 3. 返回Token
    return SaResult.ok("登录成功").setData(StpUtil.getTokenInfo());
}

4. 全局异常处理

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(NotLoginException.class)
    public SaResult handleNotLogin() {
        return SaResult.error(401, "未登录，请先登录");
    }
    @ExceptionHandler(NotPermissionException.class)
    public SaResult handleNotPermission() {
        return SaResult.error(403, "无权限访问");
    }
}

四、与 Shiro/Spring Security 对比

五、适用场景

• 中小型项目快速鉴权
• 前后端分离、移动端
• 分布式/微服务统一鉴权
• 单点登录、OAuth2.0 系统
• 需要会话强控制（踢人、封禁）

六、总结

Sa-Token 以**极简API+全功能+高扩展**成为 Java 权限框架的优选，尤其适合追求开发效率、需要快速落地权限体系的现代项目。