sa-token使用

男娘i 2023-10-07 22:42 6阅读 0赞

## 简介 ##

一个轻量级 Java 权限认证框架，个人认为比Spring Security、shrio使用更简单，配置更方便！

本文仅介绍简单使用的功能，详细使用可访问官方开发文档

官方开发文档地址：[https://sa-token.cc][https_sa-token.cc]

## 使用 ##

### [SpringBoot 集成 Sa-Token 示例][SpringBoot _ Sa-Token] ###

1.  #### **添加依赖** ####

<dependency>
        <groupId>cn.dev33</groupId>
        <artifactId>sa-token-spring-boot-starter</artifactId>
        <version>1.34.0</version>
    </dependency>

注：如果你使用的 SpringBoot 3.x，只需要将 sa-token-spring-boot-starter 修改为 sa-token-spring-boot3-starter 即可。

1.  #### **配置文件添加使用需求** ####

server:
        # 端口
        port: 8081
    
    ############## Sa-Token 配置 (文档: https://sa-token.cc) ##############
    sa-token: 
        # token名称 (同时也是cookie名称)
        token-name: satoken
        # token有效期，单位s 默认30天, -1代表永不过期 
        timeout: 2592000
        # token临时有效期 (指定时间内无操作就视为token过期) 单位: 秒
        activity-timeout: -1
        # 是否允许同一账号并发登录 (为true时允许一起登录, 为false时新登录挤掉旧登录) 
        is-concurrent: true
        # 在多人登录同一账号时，是否共用一个token (为true时所有登录共用一个token, 为false时每次登录新建一个token) 
        is-share: true
        # token风格
        token-style: uuid
        # 是否输出操作日志 
        is-log: false

**以上两步就已经完成了基础配置**

### 业务使用 ###

#### [登录认证][Link 1] ####

以下功能在代码中可直接使用

// 登录功能（账号密码校验成功后使用）：参数填写要登录的账号id，建议的数据类型：long | int | String， 不可以传入复杂类型，如：User、Admin 等等
    StpUtil.login(Object id);  
    
    // 当前会话注销登录
    StpUtil.logout();
    
    // 获取当前会话是否已经登录，返回true=已登录，false=未登录
    StpUtil.isLogin();
    
    // 检验当前会话是否已经登录, 如果未登录，则抛出异常：`NotLoginException`
    StpUtil.checkLogin();
    
    // 获取当前会话账号id, 如果未登录，则抛出异常：`NotLoginException`
    StpUtil.getLoginId();
    
    // 类似查询API还有：
    StpUtil.getLoginIdAsString();    // 获取当前会话账号id, 并转化为`String`类型
    StpUtil.getLoginIdAsInt();       // 获取当前会话账号id, 并转化为`int`类型
    StpUtil.getLoginIdAsLong();      // 获取当前会话账号id, 并转化为`long`类型
    
    // ---------- 指定未登录情形下返回的默认值 ----------
    
    // 获取当前会话账号id, 如果未登录，则返回null 
    StpUtil.getLoginIdDefaultNull();
    
    // 获取当前会话账号id, 如果未登录，则返回默认值 （`defaultValue`可以为任意类型）
    StpUtil.getLoginId(T defaultValue);
    
    // 获取当前会话的token值
    StpUtil.getTokenValue();
    
    // 获取当前`StpLogic`的token名称
    StpUtil.getTokenName();
    
    // 获取指定token对应的账号id，如果未登录，则返回 null
    StpUtil.getLoginIdByToken(String tokenValue);
    
    // 获取当前会话剩余有效期（单位：s，返回-1代表永久有效）
    StpUtil.getTokenTimeout();
    
    // 获取当前会话的token信息参数
    StpUtil.getTokenInfo();

登录之后相关的就是权限功能

#### [权限认证][Link 2] ####

所谓权限认证，核心逻辑就是判断一个账号是否拥有指定权限：

*  有，就让你通过。

*  没有？那么禁止访问！

深入到底层数据中，就是每个账号都会拥有一个权限码集合，框架来校验这个集合中是否包含指定的权限码。

例如：当前账号拥有权限码集合 \["user-add", "user-delete", "user-get"\]，这时候我来校验权限 "user-update"，则其结果就是：**验证失败，禁止访问**。

[**获取当前账号权限码集合**][Link 3]

因为每个项目的需求不同，其权限设计也千变万化，因此 \[ 获取当前账号权限码集合 \] 这一操作不可能内置到框架中， 所以 Sa-Token 将此操作以接口的方式暴露给你，以方便你根据自己的业务逻辑进行重写。

你需要做的就是新建一个类，实现 StpInterface接口，例如以下代码：

/**
     * 自定义权限验证接口扩展
     */
    @Component    // 保证此类被SpringBoot扫描，完成Sa-Token的自定义权限验证扩展 
    public class StpInterfaceImpl implements StpInterface {
    
        /**
         * 返回一个账号所拥有的权限码集合 
         */
        @Override
        public List<String> getPermissionList(Object loginId, String loginType) {
            // 本list仅做模拟，实际项目中要根据具体业务逻辑来查询权限
            List<String> list = new ArrayList<String>();    
            list.add("101");
            list.add("user.add");
            list.add("user.update");
            list.add("user.get");
            // list.add("user.delete");
            list.add("art.*");
            return list;
        }
    
        /**
         * 返回一个账号所拥有的角色标识集合 (权限与角色可分开校验)
         */
        @Override
        public List<String> getRoleList(Object loginId, String loginType) {
            // 本list仅做模拟，实际项目中要根据具体业务逻辑来查询角色
            List<String> list = new ArrayList<String>();    
            list.add("admin");
            list.add("super-admin");
            return list;
        }
    
    }

然后就可以用以下api来鉴权了（推荐使用注解鉴权）

// 获取：当前账号所拥有的权限集合
    StpUtil.getPermissionList();
    
    // 判断：当前账号是否含有指定权限, 返回 true 或 false
    StpUtil.hasPermission("user.add");        
    
    // 校验：当前账号是否含有指定权限, 如果验证未通过，则抛出异常: NotPermissionException 
    StpUtil.checkPermission("user.add");        
    
    // 校验：当前账号是否含有指定权限 [指定多个，必须全部验证通过]
    StpUtil.checkPermissionAnd("user.add", "user.delete", "user.get");        
    
    // 校验：当前账号是否含有指定权限 [指定多个，只要其一验证通过即可]
    StpUtil.checkPermissionOr("user.add", "user.delete", "user.get");    
    
    // 获取：当前账号所拥有的角色集合
    StpUtil.getRoleList();
    
    // 判断：当前账号是否拥有指定角色, 返回 true 或 false
    StpUtil.hasRole("super-admin");        
    
    // 校验：当前账号是否含有指定角色标识, 如果验证未通过，则抛出异常: NotRoleException
    StpUtil.checkRole("super-admin");        
    
    // 校验：当前账号是否含有指定角色标识 [指定多个，必须全部验证通过]
    StpUtil.checkRoleAnd("super-admin", "shop-admin");        
    
    // 校验：当前账号是否含有指定角色标识 [指定多个，只要其一验证通过即可] 
    StpUtil.checkRoleOr("super-admin", "shop-admin");

#### 注解实现 ####

##### [**1、注册拦截器**][1]**（添加注解鉴权（鉴权逻辑和业务逻辑分离开），也可以不使用）** #####

以SpringBoot2.0为例，新建配置类SaTokenConfigure.java

@Configuration
    public class SaTokenConfigure implements WebMvcConfigurer {
        // 注册 Sa-Token 拦截器，打开注解式鉴权功能 
        @Override
        public void addInterceptors(InterceptorRegistry registry) {
            // 注册 Sa-Token 拦截器，打开注解式鉴权功能 
            registry.addInterceptor(new SaInterceptor()).addPathPatterns("/**");    
        }
    }

##### **2.**[**使用注解鉴权**][Link 4] #####

功能：

@SaCheckLogin: 登录校验 —— 只有登录之后才能进入该方法。
    @SaCheckRole("admin"): 角色校验 —— 必须具有指定角色标识才能进入该方法。
    @SaCheckPermission("user:add"): 权限校验 —— 必须具有指定权限才能进入该方法。
    @SaCheckSafe: 二级认证校验 —— 必须二级认证之后才能进入该方法。
    @SaCheckBasic: HttpBasic校验 —— 只有通过 Basic 认证后才能进入该方法。
    @SaIgnore：忽略校验 —— 表示被修饰的方法或类无需进行注解鉴权和路由拦截器鉴权。
    @SaCheckDisable("comment")：账号服务封禁校验 —— 校验当前账号指定服务是否被封禁。

使用示例：

// 登录校验：只有登录之后才能进入该方法 
    @SaCheckLogin                        
    @RequestMapping("info")
    public String info() {
        return "查询用户信息";
    }
    
    // 角色校验：必须具有指定角色才能进入该方法 
    @SaCheckRole("super-admin")        
    @RequestMapping("add")
    public String add() {
        return "用户增加";
    }
    
    // 权限校验：必须具有指定权限才能进入该方法 
    @SaCheckPermission("user-add")        
    @RequestMapping("add")
    public String add() {
        return "用户增加";
    }
    
    // 二级认证校验：必须二级认证之后才能进入该方法 
    @SaCheckSafe()        
    @RequestMapping("add")
    public String add() {
        return "用户增加";
    }
    
    // Http Basic 校验：只有通过 Basic 认证后才能进入该方法 
    @SaCheckBasic(account = "sa:123456")
    @RequestMapping("add")
    public String add() {
        return "用户增加";
    }
    
    // 校验当前账号是否被封禁 comment 服务，如果已被封禁会抛出异常，无法进入方法 
    @SaCheckDisable("comment")                
    @RequestMapping("send")
    public String send() {
        return "查询用户信息";
    }

##### [**3、设定校验模式**][3] #####

@SaCheckRole与@SaCheckPermission注解可设置校验模式，例如：

// 注解式鉴权：只要具有其中一个权限即可通过校验 
    @RequestMapping("atJurOr")
    @SaCheckPermission(value = {"user-add", "user-all", "user-delete"}, mode = SaMode.OR)        
    public SaResult atJurOr() {
        return SaResult.data("用户信息");
    }

mode有两种取值：

*  SaMode.AND, 标注一组权限，会话必须全部具有才可通过校验。

*  SaMode.OR, 标注一组权限，会话只要具有其一即可通过校验。

##### [**4、角色权限双重 “or校验”**][4_ _or] #####

假设有以下业务场景：一个接口在具有权限 user.add 或角色 admin 时可以调通。怎么写？

// 角色权限双重 “or校验”：具备指定权限或者指定角色即可通过校验
    @RequestMapping("userAdd")
    @SaCheckPermission(value = "user.add", orRole = "admin")        
    public SaResult userAdd() {
        return SaResult.data("用户信息");
    }

##### [**5、忽略认证**][5] #####

使用 @SaIgnore 可表示一个接口忽略认证：

@SaCheckLogin
    @RestController
    public class TestController {
    
        // ... 其它方法 
    
        // 此接口加上了 @SaIgnore 可以游客访问 
        @SaIgnore
        @RequestMapping("getList")
        public SaResult getList() {
            // ... 
            return SaResult.ok(); 
        }
    }

如上代码表示：TestController 中的所有方法都需要登录后才可以访问，但是 getList 接口可以匿名游客访问。

*  @SaIgnore 修饰方法时代表这个方法可以被游客访问，修饰类时代表这个类中的所有接口都可以游客访问。

*  @SaIgnore 具有最高优先级，当 @SaIgnore 和其它鉴权注解一起出现时，其它鉴权注解都将被忽略。

*  @SaIgnore 同样可以忽略掉 Sa-Token 拦截器中的路由鉴权，在下面的 \[路由拦截鉴权\] 章节中我们会讲到。

使用拦截器模式，只能在Controller层进行注解鉴权，如需在任意层级使用注解鉴权，访问官方文档

#### 前后台分离使用(APP、小程序等) ####

##### [**1、后端将 token 返回到前端**][1_ token] #####

1.  首先调用 StpUtil.login(id) 进行登录。

1.  调用 StpUtil.getTokenInfo() 返回当前会话的 token 详细参数。

*  此方法返回一个对象，其有两个关键属性：tokenName和tokenValue（token 的名称和 token 的值）。

*  将此对象传递到前台，让前端人员将这两个值保存到本地。

代码示例：

// 登录接口
    @RequestMapping("doLogin")
    public SaResult doLogin() {
        // 第1步，先登录上 
        StpUtil.login(10001);
        // 第2步，获取 Token  相关参数 
        SaTokenInfo tokenInfo = StpUtil.getTokenInfo();
        // 第3步，返回给前端 
        return SaResult.data(tokenInfo);
    }

##### [**2、前端将 token 提交到后端**][2_ token] #####

1.  无论是app还是小程序，其传递方式都大同小异。

1.  那就是，将 token 塞到请求header里 ，格式为：\{tokenName: tokenValue\}。

1.  以经典跨端框架 [uni-app][] 为例：

**方式1，简单粗暴**

// 1、首先在登录时，将 tokenValue 存储在本地，例如：
    uni.setStorageSync('tokenValue', tokenValue);
    
    // 2、在发起ajax请求的地方，获取这个值，并塞到header里 
    uni.request({
        url: 'https://www.example.com/request', // 仅为示例，并非真实接口地址。
        header: {
            "content-type": "application/x-www-form-urlencoded",
            "satoken": uni.getStorageSync('tokenValue')        // 关键代码, 注意参数名字是 satoken 
        },
        success: (res) => {
            console.log(res.data);    
        }
    });

**方式2，更加灵活**

// 1、首先在登录时，将tokenName和tokenValue一起存储在本地，例如：
    uni.setStorageSync('tokenName', tokenName); 
    uni.setStorageSync('tokenValue', tokenValue); 
    
    // 2、在发起ajax的地方，获取这两个值, 并组织到head里 
    var tokenName = uni.getStorageSync('tokenName');    // 从本地缓存读取tokenName值
    var tokenValue = uni.getStorageSync('tokenValue');    // 从本地缓存读取tokenValue值
    var header = {
        "content-type": "application/x-www-form-urlencoded"
    };
    if (tokenName != undefined && tokenName != '') {
        header[tokenName] = tokenValue;
    }
    
    // 3、后续在发起请求时将 header 对象塞到请求头部 
    uni.request({
        url: 'https://www.example.com/request', // 仅为示例，并非真实接口地址。
        header: header,
        success: (res) => {
            console.log(res.data);    
        }
    });

[https_sa-token.cc]: https://sa-token.cc/
[SpringBoot _ Sa-Token]: https://sa-token.cc/doc.html#/start/example?id=springboot-%e9%9b%86%e6%88%90-sa-token-%e7%a4%ba%e4%be%8b
[Link 1]: https://sa-token.cc/doc.html#/use/login-auth?id=%e7%99%bb%e5%bd%95%e8%ae%a4%e8%af%81
[Link 2]: https://sa-token.cc/doc.html#/use/jur-auth?id=%e6%9d%83%e9%99%90%e8%ae%a4%e8%af%81
[Link 3]: https://sa-token.cc/doc.html#/use/jur-auth?id=%e8%8e%b7%e5%8f%96%e5%bd%93%e5%89%8d%e8%b4%a6%e5%8f%b7%e6%9d%83%e9%99%90%e7%a0%81%e9%9b%86%e5%90%88
[1]: https://sa-token.cc/doc.html#/use/at-check?id=_1%e3%80%81%e6%b3%a8%e5%86%8c%e6%8b%a6%e6%88%aa%e5%99%a8
[Link 4]: https://sa-token.cc/doc.html#/use/at-check?id=_2%e3%80%81%e4%bd%bf%e7%94%a8%e6%b3%a8%e8%a7%a3%e9%89%b4%e6%9d%83
[3]: https://sa-token.cc/doc.html#/use/at-check?id=_3%e3%80%81%e8%ae%be%e5%ae%9a%e6%a0%a1%e9%aa%8c%e6%a8%a1%e5%bc%8f
[4_ _or]: https://sa-token.cc/doc.html#/use/at-check?id=_4%e3%80%81%e8%a7%92%e8%89%b2%e6%9d%83%e9%99%90%e5%8f%8c%e9%87%8d-or%e6%a0%a1%e9%aa%8c
[5]: https://sa-token.cc/doc.html#/use/at-check?id=_5%e3%80%81%e5%bf%bd%e7%95%a5%e8%ae%a4%e8%af%81
[1_ token]: https://sa-token.cc/doc.html#/up/not-cookie?id=_1%e3%80%81%e5%90%8e%e7%ab%af%e5%b0%86-token-%e8%bf%94%e5%9b%9e%e5%88%b0%e5%89%8d%e7%ab%af
[2_ token]: https://sa-token.cc/doc.html#/up/not-cookie?id=_2%e3%80%81%e5%89%8d%e7%ab%af%e5%b0%86-token-%e6%8f%90%e4%ba%a4%e5%88%b0%e5%90%8e%e7%ab%af
[uni-app]: https://uniapp.dcloud.io/