一文详解 Sa-Token 中的 SaSession 对象

Sa-Token 是一个轻量级 java 权限认证框架，主要解决登录认证、权限认证、单点登录、OAuth2、微服务网关鉴权 等一系列权限相关问题。

Gitee 开源地址：https://gitee.com/dromara/sa-token

本文将详细介绍 Sa-Token 中的不同 SaSession 对象的区别，以及各种方便的存取值的方法。
一、Session 是什么？

Session 是会话中专业的数据缓存组件，通过 Session 我们可以很方便的缓存一些高频读写数据，提高程序性能，例如：

1. // 在登录时缓存user对象
2. StpUtil.getSession().set("user", user);
4. // 然后我们就可以在任意处使用这个user对象
5. SysUser user = (SysUser) StpUtil.getSession().get("user");

复制代码

在 Sa-Token 中，SaSession 分为三种，分别是：

• User-Session: 指的是框架为每个 账号id 分配的 SaSession。
  
• Token-Session: 指的是框架为每个 token 分配的 SaSession。
  
• Custom-Session: 指的是以一个 特定的值 作为SessionId，来分配的 Session。
  

假设三个客户端登录同一账号，且配置了不共享token，那么此时的Session模型是：

简而言之：

• User-Session  以UserId为主，只要token指向的UserId一致，那么对应的Session对象就一致。
  
• Token-Session 以token为主，只要token不同，那么对应的Session对象就不同。
  
• Custom-Session 以特定的key为主，不同key对应不同的Session对象，同样的key指向同一个Session对象。
  

二、获取 User-Session

有关账号Session的API如下：

1. // 获取当前账号id的Session (必须是登录后才能调用)
2. StpUtil.getSession();
4. // 获取当前账号id的Session, 并决定在Session尚未创建时，是否新建并返回
5. StpUtil.getSession(true);
7. // 获取账号id为10001的Session
8. StpUtil.getSessionByLoginId(10001);
10. // 获取账号id为10001的Session, 并决定在Session尚未创建时，是否新建并返回
11. StpUtil.getSessionByLoginId(10001, true);
13. // 获取SessionId为xxxx-xxxx的Session, 在Session尚未创建时, 返回null
14. StpUtil.getSessionBySessionId("xxxx-xxxx");

复制代码

三、获取 Token-Session

有关令牌Session的API如下：

1. // 获取当前 Token 的 Token-Session 对象
2. StpUtil.getTokenSession();
4. // 获取指定 Token 的 Token-Session 对象
5. StpUtil.getTokenSessionByToken(token);

复制代码

四、获取自定义Session

自定义Session指的是以一个特定的值作为SessionId来分配的Session, 借助自定义Session，你可以为系统中的任意元素分配相应的session

例如以商品id作为key为每个商品分配一个Session，以便于缓存和商品相关的数据，其相关API如下：

1. // 查询指定key的Session是否存在
2. SaSessionCustomUtil.isExists("goods-10001");
4. // 获取指定key的Session，如果没有，则新建并返回
5. SaSessionCustomUtil.getSessionById("goods-10001");
7. // 获取指定key的Session，如果没有，第二个参数决定是否新建并返回  
8. SaSessionCustomUtil.getSessionById("goods-10001", false);   
10. // 删除指定key的Session
11. SaSessionCustomUtil.deleteSessionById("goods-10001");

复制代码

五、在 Session 上存取值

1. // 写值
2. session.set("name", "zhang");
4. // 写值 (只有在此key原本无值的时候才会写入)
5. session.setDefaultValue("name", "zhang");
7. // 取值
8. session.get("name");
10. // 取值 (指定默认值)
11. session.get("name", "<defaultValue>");
13. // 取值 (若无值则执行参数方法, 之后将结果保存到此键名下,并返回此结果   若有值则直接返回, 无需执行参数方法)
14. session.get("name", () -> {
15.             return ...;
16.         });
18. // ---------- 数据类型转换： ----------
19. session.getInt("age");         // 取值 (转int类型)
20. session.getLong("age");        // 取值 (转long类型)
21. session.getString("name");     // 取值 (转String类型)
22. session.getDouble("result");   // 取值 (转double类型)
23. session.getFloat("result");    // 取值 (转float类型)
24. session.getModel("key", Student.class);     // 取值 (指定转换类型)
25. session.getModel("key", Student.class, <defaultValue>);  // 取值 (指定转换类型, 并指定值为Null时返回的默认值)
27. // 是否含有某个key (返回true或false)
28. session.has("key");
30. // 删值
31. session.delete('name');         
33. // 清空所有值
34. session.clear();                 
36. // 获取此 Session 的所有key (返回Set<String>)
37. session.keys();      

复制代码

六、其它操作

1. // 返回此 Session 的id
2. session.getId();                          
4. // 返回此 Session 的创建时间 (时间戳)
5. session.getCreateTime();                  
7. // 返回此 Session 会话上的底层数据对象（如果更新map里的值，请调用session.update()方法避免产生脏数据）
8. session.getDataMap();                     
10. // 将这个 Session 从持久库更新一下
11. session.update();                        
13. // 注销此 Session 会话 (从持久库删除此Session)
14. session.logout();                        

复制代码

七、SaSession 环境隔离说明

有同学经常会把 SaSession 与 HttpSession 进行混淆，例如：

1. @PostMapping("/resetPoints")
2. public void reset(HttpSession session) {
3.         // 在 HttpSession 上写入一个值
4.     session.setAttribute("name", 66);
5.         // 在 SaSession 进行取值
6.     System.out.println(StpUtil.getSession().get("name"));        // 输出null
7. }

复制代码

要点：

• SaSession 与 HttpSession 没有任何关系，在HttpSession上写入的值，在SaSession中无法取出。
  
• HttpSession并未被框架接管，在使用Sa-Token时，请在任何情况下均使用SaSession，不要使用HttpSession。
  

八、未登录场景下获取 Token-Session

默认场景下，只有登录后才能通过 StpUtil.getTokenSession() 获取 Token-Session。
如果想要在未登录场景下获取 Token-Session ，有两种方法：

• 方法一：将全局配置项 tokenSessionCheckLogin 改为 false。
  
• 方法二：使用匿名 Token-Session
  

1. // 获取当前 Token 的匿名 Token-Session （可在未登录情况下使用的 Token-Session）
2. StpUtil.getAnonTokenSession();

复制代码

注意点：如果前端没有提交 Token ，或者提交的 Token 是一个无效 Token 的话，框架将不会根据此 Token 创建 Token-Session 对象，
而是随机一个新的 Token 值来创建 Token-Session 对象，此 Token 值可以通过 StpUtil.getTokenValue() 获取到。
参考资料

• Sa-Token 文档：https://sa-token.cc
  
• Gitee 仓库地址：https://gitee.com/dromara/sa-token
  
• GitHub 仓库地址：https://github.com/dromara/sa-token
  

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！