Sa-Token：轻量级Java权限认证框架使用指南

一、Sa-Token简介

Sa-Token 是一个专注于权限认证的轻量级 Java 框架，旨在简化登录认证、权限控制等功能的实现。其核心功能包括：

1. 登录认证：通过 Token 机制管理用户会话，支持单点登录（SSO）。
2. 权限认证：基于角色或权限码的细粒度权限控制。
3. 分布式会话：支持 Redis 集成，实现分布式环境下的会话共享。
4. 安全防护：提供防伪造 Token、防路径遍历攻击等安全机制。
5. 微服务鉴权：适配网关服务，支持微服务架构下的统一鉴权。
   与传统框架（如 Shiro、Spring Security）相比，Sa-Token 的 API 设计更简洁，例如通过 StpUtil 一行代码即可完成登录或鉴权。

---

二、核心功能与使用场景

1. 登录认证

   • 颁发 Token：用户登录后生成加密 Token，存储于 Redis 并返回客户端。

     // 用户ID绑定Token
     StpUtil.login(userId);
     String token = StpUtil.getTokenValue(); // 获取Token字符串
     

   • 验证 Token：通过注解或代码拦截请求，验证 Token 有效性。

     @SaCheckLogin // 需登录才能访问的接口
     public String getUserProfile() { ... }
     

2. 权限验证

   • 角色/权限校验：通过注解限制接口访问权限。

     @SaCheckPermission("user:add") // 需具备“user:add”权限
     public String addUser() { ... }
     

   • 路由拦截：配置全局拦截规则，按路径鉴权。

     registry.addInterceptor(new SaInterceptor(handler -> {
         SaRouter.match("/admin/**", r -> StpUtil.checkRole("admin"));
     }));
     

3. 单点登录（SSO）与OAuth2.0

   • 支持多系统间的统一登录与授权流程，简化第三方应用接入。

---

三、快速集成步骤

1. 添加依赖（Maven示例）

   <dependency>
       <groupId>cn.dev33</groupId>
       <artifactId>sa-token-spring-boot-starter</artifactId>
       <version>1.40.0</version> <!-- 推荐最新版本 -->
   </dependency>
   <!-- 集成Redis（分布式会话支持） -->
   <dependency>
       <groupId>cn.dev33</groupId>
       <artifactId>sa-token-dao-redis-jackson</artifactId>
       <version>1.40.0</version>
   </dependency>
   

2. 配置文件（application.yml）

   sa-token:
     token-name: satoken           # Token名称
     timeout: 2592000             # 有效期（默认30天）
     activity-timeout: -1         # 临时有效期（无操作永不过期）
     is-concurrent: true          # 允许同一账号并发登录
     token-style: uuid            # Token生成风格
     is-log: false                # 关闭日志输出
   

3. 自定义权限校验逻辑
   实现 StpInterface 接口，加载用户的角色和权限列表：

   @Component
   public class SaPermissionImpl implements StpInterface {
       @Override
       public List<String> getPermissionList(Object userId, String loginType) {
           // 从数据库或缓存查询权限列表
           return Arrays.asList("user:add", "user:delete");
       }
       @Override
       public List<String> getRoleList(Object userId, String loginType) {
           return Arrays.asList("admin");
       }
   }
   

---

四、安全增强与最佳实践

1. HTTPS 传输：防止 Token 在传输中被窃取。
2. 防伪造 Token：依赖 Redis 存储校验，避免算法破解。
3. 路径安全：启用防火墙策略，拦截含特殊字符（如 ;）的请求。
4. Cookie 安全配置：

   sa-token:
     cookie:
       domain: example.com
       secure: true     # 仅HTTPS传输
       sameSite: Lax    # 防CSRF攻击
   

---

五、总结

Sa-Token 凭借其简洁的 API 和丰富的功能，成为 Java 权限认证的高效解决方案。无论是单体应用还是微服务架构，均可通过少量配置快速集成，显著提升开发效率。官方文档（sa-token.cc）提供了详细示例和最新特性说明，推荐结合实践进一步探索。