mirror of
https://gitee.com/dromara/sa-token.git
synced 2025-04-05 17:37:53 +08:00
完善文档
This commit is contained in:
shengzhang
parent
40331c2e3f
commit
47e879ad5e
@ -763,7 +763,7 @@ public class StpLogic {
|
||||
// =================== 角色验证操作 ===================
|
||||
|
||||
/**
|
||||
* 指定账号id是否含有角色标识
|
||||
* 指定账号id是否含有角色标识, 返回true或false
|
||||
* @param loginId 账号id
|
||||
* @param role 角色标识
|
||||
* @return 是否含有指定角色标识
|
||||
@ -774,7 +774,7 @@ public class StpLogic {
|
||||
}
|
||||
|
||||
/**
|
||||
* 当前账号id是否含有指定角色标识
|
||||
* 当前账号是否含有指定角色标识, 返回true或false
|
||||
* @param role 角色标识
|
||||
* @return 是否含有指定角色标识
|
||||
*/
|
||||
@ -783,7 +783,7 @@ public class StpLogic {
|
||||
}
|
||||
|
||||
/**
|
||||
* 当前账号是否含有指定角色标识，没有就抛出异常
|
||||
* 当前账号是否含有指定角色标识, 如果验证未通过，则抛出异常: NotRoleException
|
||||
* @param role 角色标识
|
||||
*/
|
||||
public void checkRole(String role) {
|
||||
@ -793,7 +793,7 @@ public class StpLogic {
|
||||
}
|
||||
|
||||
/**
|
||||
* 当前账号是否含有指定角色标识, [指定多个，必须全都有]
|
||||
* 当前账号是否含有指定角色标识 [指定多个，必须全部验证通过]
|
||||
* @param roleArray 角色标识数组
|
||||
*/
|
||||
public void checkRoleAnd(String... roleArray){
|
||||
@ -807,7 +807,7 @@ public class StpLogic {
|
||||
}
|
||||
|
||||
/**
|
||||
* 当前账号是否含有指定角色标识, [指定多个，有一个就可以通过]
|
||||
* 当前账号是否含有指定角色标识 [指定多个，只要其一验证通过即可]
|
||||
* @param roleArray 角色标识数组
|
||||
*/
|
||||
public void checkRoleOr(String... roleArray){
|
||||
@ -828,7 +828,7 @@ public class StpLogic {
|
||||
// =================== 权限验证操作 ===================
|
||||
|
||||
/**
|
||||
* 指定账号id是否含有指定权限
|
||||
* 指定账号id是否含有指定权限, 返回true或false
|
||||
* @param loginId 账号id
|
||||
* @param permission 权限码
|
||||
* @return 是否含有指定权限
|
||||
@ -839,7 +839,7 @@ public class StpLogic {
|
||||
}
|
||||
|
||||
/**
|
||||
* 当前账号id是否含有指定权限
|
||||
* 当前账号是否含有指定权限, 返回true或false
|
||||
* @param permission 权限码
|
||||
* @return 是否含有指定权限
|
||||
*/
|
||||
@ -848,7 +848,7 @@ public class StpLogic {
|
||||
}
|
||||
|
||||
/**
|
||||
* 当前账号是否含有指定权限， 没有就抛出异常
|
||||
* 当前账号是否含有指定权限, 如果验证未通过，则抛出异常: NotPermissionException
|
||||
* @param permission 权限码
|
||||
*/
|
||||
public void checkPermission(String permission) {
|
||||
@ -858,7 +858,7 @@ public class StpLogic {
|
||||
}
|
||||
|
||||
/**
|
||||
* 当前账号是否含有指定权限, [指定多个，必须全都有]
|
||||
* 当前账号是否含有指定权限 [指定多个，必须全部验证通过]
|
||||
* @param permissionArray 权限码数组
|
||||
*/
|
||||
public void checkPermissionAnd(String... permissionArray){
|
||||
@ -872,7 +872,7 @@ public class StpLogic {
|
||||
}
|
||||
|
||||
/**
|
||||
* 当前账号是否含有指定权限, [指定多个，有一个就可以通过]
|
||||
* 当前账号是否含有指定权限 [指定多个，只要其一验证通过即可]
|
||||
* @param permissionArray 权限码数组
|
||||
*/
|
||||
public void checkPermissionOr(String... permissionArray){
|
||||
|
||||
@ -310,7 +310,7 @@ public class StpUtil {
|
||||
// =================== 角色验证操作 ===================
|
||||
|
||||
/**
|
||||
* 指定账号id是否含有角色标识
|
||||
* 指定账号id是否含有角色标识, 返回true或false
|
||||
* @param loginId 账号id
|
||||
* @param role 角色标识
|
||||
* @return 是否含有指定角色标识
|
||||
@ -320,7 +320,7 @@ public class StpUtil {
|
||||
}
|
||||
|
||||
/**
|
||||
* 当前账号id是否含有指定角色标识
|
||||
* 当前账号是否含有指定角色标识, 返回true或false
|
||||
* @param role 角色标识
|
||||
* @return 是否含有指定角色标识
|
||||
*/
|
||||
@ -329,7 +329,7 @@ public class StpUtil {
|
||||
}
|
||||
|
||||
/**
|
||||
* 当前账号是否含有指定角色标识，没有就抛出异常
|
||||
* 当前账号是否含有指定角色标识, 如果验证未通过，则抛出异常: NotRoleException
|
||||
* @param role 角色标识
|
||||
*/
|
||||
public static void checkRole(String role) {
|
||||
@ -337,7 +337,7 @@ public class StpUtil {
|
||||
}
|
||||
|
||||
/**
|
||||
* 当前账号是否含有指定角色标识, [指定多个，必须全都有]
|
||||
* 当前账号是否含有指定角色标识 [指定多个，必须全部验证通过]
|
||||
* @param roleArray 角色标识数组
|
||||
*/
|
||||
public static void checkRoleAnd(String... roleArray){
|
||||
@ -345,7 +345,7 @@ public class StpUtil {
|
||||
}
|
||||
|
||||
/**
|
||||
* 当前账号是否含有指定角色标识, [指定多个，有一个就可以通过]
|
||||
* 当前账号是否含有指定角色标识 [指定多个，只要其一验证通过即可]
|
||||
* @param roleArray 角色标识数组
|
||||
*/
|
||||
public static void checkRoleOr(String... roleArray){
|
||||
@ -356,46 +356,46 @@ public class StpUtil {
|
||||
// =================== 权限验证操作 ===================
|
||||
|
||||
/**
|
||||
* 指定账号id是否含有指定权限
|
||||
* 指定账号id是否含有指定权限, 返回true或false
|
||||
* @param loginId 账号id
|
||||
* @param permissionCode 权限码
|
||||
* @param permission 权限码
|
||||
* @return 是否含有指定权限
|
||||
*/
|
||||
public static boolean hasPermission(Object loginId, String permissionCode) {
|
||||
return stpLogic.hasPermission(loginId, permissionCode);
|
||||
public static boolean hasPermission(Object loginId, String permission) {
|
||||
return stpLogic.hasPermission(loginId, permission);
|
||||
}
|
||||
|
||||
/**
|
||||
* 当前账号id是否含有指定权限
|
||||
* @param permissionCode 权限码
|
||||
* 当前账号是否含有指定权限, 返回true或false
|
||||
* @param permission 权限码
|
||||
* @return 是否含有指定权限
|
||||
*/
|
||||
public static boolean hasPermission(String permissionCode) {
|
||||
return stpLogic.hasPermission(permissionCode);
|
||||
public static boolean hasPermission(String permission) {
|
||||
return stpLogic.hasPermission(permission);
|
||||
}
|
||||
|
||||
/**
|
||||
* 当前账号是否含有指定权限， 没有就抛出异常
|
||||
* @param permissionCode 权限码
|
||||
* 当前账号是否含有指定权限, 如果验证未通过，则抛出异常: NotPermissionException
|
||||
* @param permission 权限码
|
||||
*/
|
||||
public static void checkPermission(String permissionCode) {
|
||||
stpLogic.checkPermission(permissionCode);
|
||||
public static void checkPermission(String permission) {
|
||||
stpLogic.checkPermission(permission);
|
||||
}
|
||||
|
||||
/**
|
||||
* 当前账号是否含有指定权限, [指定多个，必须全都有]
|
||||
* @param permissionCodeArray 权限码数组
|
||||
* 当前账号是否含有指定权限 [指定多个，必须全部验证通过]
|
||||
* @param permissionArray 权限码数组
|
||||
*/
|
||||
public static void checkPermissionAnd(String... permissionCodeArray) {
|
||||
stpLogic.checkPermissionAnd(permissionCodeArray);
|
||||
public static void checkPermissionAnd(String... permissionArray) {
|
||||
stpLogic.checkPermissionAnd(permissionArray);
|
||||
}
|
||||
|
||||
/**
|
||||
* 当前账号是否含有指定权限, [指定多个，有一个就可以通过]
|
||||
* @param permissionCodeArray 权限码数组
|
||||
* 当前账号是否含有指定权限 [指定多个，只要其一验证通过即可]
|
||||
* @param permissionArray 权限码数组
|
||||
*/
|
||||
public static void checkPermissionOr(String... permissionCodeArray) {
|
||||
stpLogic.checkPermissionOr(permissionCodeArray);
|
||||
public static void checkPermissionOr(String... permissionArray) {
|
||||
stpLogic.checkPermissionOr(permissionArray);
|
||||
}
|
||||
|
||||
|
||||
|
||||
@ -17,8 +17,9 @@ public class StpInterfaceImpl implements StpInterface {
|
||||
* 返回一个账号所拥有的权限码集合
|
||||
*/
|
||||
@Override
|
||||
public List<String> getPermissionList(Object login_id, String login_key) {
|
||||
List<String> list = new ArrayList<String>(); // 本list仅做模拟，实际项目中要根据具体业务逻辑来查询权限
|
||||
public List<String> getPermissionList(Object loginId, String loginKey) {
|
||||
// 本list仅做模拟，实际项目中要根据具体业务逻辑来查询权限
|
||||
List<String> list = new ArrayList<String>();
|
||||
list.add("101");
|
||||
list.add("user-add");
|
||||
list.add("user-delete");
|
||||
@ -33,7 +34,8 @@ public class StpInterfaceImpl implements StpInterface {
|
||||
*/
|
||||
@Override
|
||||
public List<String> getRoleList(Object loginId, String loginKey) {
|
||||
List<String> list = new ArrayList<String>(); // 本list仅做模拟，实际项目中要根据具体业务逻辑来查询角色
|
||||
// 本list仅做模拟，实际项目中要根据具体业务逻辑来查询角色
|
||||
List<String> list = new ArrayList<String>();
|
||||
list.add("admin");
|
||||
list.add("super-admin");
|
||||
return list;
|
||||
|
||||
@ -10,8 +10,8 @@
|
||||
- [权限验证](/use/jur-auth)
|
||||
- [Session会话](/use/session)
|
||||
- [踢人下线](/use/kick)
|
||||
- [持久层扩展(集成Redis)](/use/dao-extend)
|
||||
- [无Cookie模式(前后台分离)](/use/not-cookie)
|
||||
- [持久层扩展（集成Redis）](/use/dao-extend)
|
||||
- [无Cookie模式（前后台分离）](/use/not-cookie)
|
||||
- [模拟他人](/use/mock-person)
|
||||
- [多账号验证](/use/many-account)
|
||||
- [同端互斥登录](/use/mutex-login)
|
||||
@ -29,6 +29,7 @@
|
||||
- **附录**
|
||||
- [未登录场景值](/fun/not-login-scene)
|
||||
- [token有效期详解](/fun/token-timeout)
|
||||
- [TokenInfo参数详解](/fun/token-info)
|
||||
|
||||
|
||||
|
||||
|
||||
22
sa-token-doc/doc/fun/token-info.md
Normal file
22
sa-token-doc/doc/fun/token-info.md
Normal file
@ -0,0 +1,22 @@
|
||||
# SaTokenInfo 参数详解
|
||||
|
||||
token信息Model: 用来描述一个token的常用参数
|
||||
|
||||
``` js
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "ok",
|
||||
"data": {
|
||||
"tokenName": "satoken", // token名称
|
||||
"tokenValue": "e67b99f1-3d7a-4a8d-bb2f-e888a0805633", // token值
|
||||
"isLogin": true, // 此token是否已经登录
|
||||
"loginId": "10001", // 此token对应的LoginId，未登录时为null
|
||||
"loginKey": "login", // LoginKey账号体系标识
|
||||
"tokenTimeout": 2591977, // token剩余有效期 (单位: 秒)
|
||||
"sessionTimeout": 2591977, // User-Session剩余有效时间 (单位: 秒)
|
||||
"tokenSessionTimeout": -2, // Token-Session剩余有效时间 (单位: 秒)
|
||||
"tokenActivityTimeout": -1, // token剩余无操作有效时间 (单位: 秒)
|
||||
"loginDevice": "default-device" // 登录设备标识
|
||||
},
|
||||
}
|
||||
```
|
||||
@ -3,19 +3,24 @@
|
||||
---
|
||||
|
||||
### 用这个框架我需要很多配置吗?
|
||||
- 零配置开箱即用，但同时也支持自定义配置：参考：[框架配置](use/config)
|
||||
零配置开箱即用，但同时也支持自定义配置：参考：[框架配置](use/config)
|
||||
|
||||
|
||||
### 如何踢人下线?
|
||||
- 参考：[踢人下线](use/kick)
|
||||
参考：[踢人下线](use/kick)
|
||||
|
||||
|
||||
### 能否集成redis?
|
||||
- 参考：[持久层扩展](use/dao-extend)
|
||||
参考：[持久层扩展](use/dao-extend)
|
||||
|
||||
|
||||
### 能否使用在APP、小程序等前后台分离项目中?
|
||||
- 参考：[无cookie模式](use/not-cookie)
|
||||
参考：[无cookie模式](use/not-cookie)
|
||||
|
||||
|
||||
### 还是有不明白到的地方?
|
||||
- 请在`github`提交`issues`，或者加入qq群交流（群链接在[首页](README?id=交流群)）
|
||||
请在`github`提交`issues`，或者加入qq群交流（群链接在[首页](README?id=交流群)）
|
||||
|
||||
|
||||
### 我能为这个框架贡献代码吗？
|
||||
- **可以**，请参照首页的提交pr步骤 ，[贡献代码](README?id=贡献代码)
|
||||
**可以**，请参照首页的提交pr步骤 ，[贡献代码](README?id=贡献代码)
|
||||
@ -1,9 +1,10 @@
|
||||
# 示例
|
||||
|
||||
本篇将带你从零开始集成sa-token，从而让你快速熟悉sa-token的使用姿势 <br>
|
||||
以maven + springboot为例
|
||||
|
||||
---
|
||||
|
||||
> - 本篇将带你从零开始集成sa-token，从而让你快速熟悉sa-token的使用姿势
|
||||
> - 以maven + springboot为例
|
||||
|
||||
## springboot环境
|
||||
|
||||
@ -11,7 +12,7 @@
|
||||
在IDE中新建一个Springboot项目，例如：`sa-token-demo-springboot`（不会的同学请自行百度或者参考github示例）
|
||||
|
||||
#### 2、设置jar包依赖
|
||||
- 在 `pom.xml` 中添加依赖：
|
||||
在 `pom.xml` 中添加依赖：
|
||||
|
||||
``` xml
|
||||
<!-- sa-token 权限认证, 在线文档：http://sa-token.dev33.cn/ -->
|
||||
@ -23,8 +24,8 @@
|
||||
```
|
||||
|
||||
#### 3、配置文件
|
||||
- 你可以**零配置启动项目**
|
||||
- 但同时你也可以在`application.yml`中增加如下配置，定制性使用框架：
|
||||
你可以**零配置启动项目** <br>
|
||||
但同时你也可以在`application.yml`中增加如下配置，定制性使用框架：
|
||||
|
||||
``` java
|
||||
spring:
|
||||
@ -44,8 +45,8 @@ spring:
|
||||
token-style: uuid
|
||||
```
|
||||
|
||||
> - 如果你习惯于 `application.properties` 类型的配置文件，那也很好办:
|
||||
> - 百度： [springboot properties与yml 配置文件的区别](https://www.baidu.com/s?ie=UTF-8&wd=springboot%20properties%E4%B8%8Eyml%20%E9%85%8D%E7%BD%AE%E6%96%87%E4%BB%B6%E7%9A%84%E5%8C%BA%E5%88%AB)
|
||||
如果你习惯于 `application.properties` 类型的配置文件，那也很好办: <br>
|
||||
百度： [springboot properties与yml 配置文件的区别](https://www.baidu.com/s?ie=UTF-8&wd=springboot%20properties%E4%B8%8Eyml%20%E9%85%8D%E7%BD%AE%E6%96%87%E4%BB%B6%E7%9A%84%E5%8C%BA%E5%88%AB)
|
||||
|
||||
#### 4、创建主类
|
||||
在项目中新建包 `com.pj` ，在此包内新建主类 `SaTokenDemoApplication.java`，输入以下代码：
|
||||
@ -67,7 +68,7 @@ public class SaTokenDemoApplication {
|
||||
|
||||
|
||||
## 普通spring环境
|
||||
- 普通spring环境与springboot环境大体无异，只不过需要在项目根目录手动创建配置文件`sa-token.properties`来完成配置
|
||||
普通spring环境与springboot环境大体无异，只不过需要在项目根目录手动创建配置文件`sa-token.properties`来完成配置
|
||||
|
||||
|
||||
## 详细了解
|
||||
|
||||
@ -14,7 +14,7 @@
|
||||
<version>1.12.1</version>
|
||||
</dependency>
|
||||
```
|
||||
优点：兼容性好，缺点：session序列化后基本不可读，对开发者来讲等同于乱码
|
||||
优点：兼容性好，缺点：Session序列化后基本不可读，对开发者来讲等同于乱码
|
||||
|
||||
|
||||
### 2. sa-token 整合 Redis (使用jackson序列化方式)
|
||||
@ -26,7 +26,7 @@
|
||||
<version>1.12.1</version>
|
||||
</dependency>
|
||||
```
|
||||
优点：session序列化后可读性强，可灵活手动修改，缺点：兼容性稍差
|
||||
优点：Session序列化后可读性强，可灵活手动修改，缺点：兼容性稍差
|
||||
|
||||
|
||||
<br>
|
||||
|
||||
@ -2,21 +2,23 @@
|
||||
---
|
||||
|
||||
|
||||
## 核心思想
|
||||
### 核心思想
|
||||
|
||||
- 所谓权限验证，验证的核心就是当前账号是否拥有一个权限码
|
||||
- 有：就让你通过、没有：那么禁止访问
|
||||
- 再往底了说，就是每个账号都会拥有一个权限码集合，我来验证这个集合中是否包括我需要检测的那个权限码
|
||||
- 例如：当前账号拥有权限码集合：`["user:add", "user:delete", "user:get"]`，这时候我去验证权限码：`"user:update"`，则结果就是验证失败，禁止访问
|
||||
- 所以现在问题的核心就是:
|
||||
1. 如何获取一个账号所拥有的的权限码集合
|
||||
2. 本次操作要验证的权限码是哪个
|
||||
所谓权限验证，验证的核心就是一个账号是否拥有一个权限码 <br/>
|
||||
有，就让你通过。没有？那么禁止访问!
|
||||
|
||||
## 获取当前账号权限码集合
|
||||
再往底了说，就是每个账号都会拥有一个权限码集合，我来验证这个集合中是否包含指定的权限码 <br/>
|
||||
例如：当前账号拥有权限码集合：`["user:add", "user:delete", "user:get"]`，这时候我来验证权 `"user:update"`，则结果就是：**验证失败，禁止访问**
|
||||
|
||||
所以现在问题的核心就是:
|
||||
1. 如何获取一个账号所拥有的的权限码集合
|
||||
2. 本次操作需要验证的权限码是哪个
|
||||
|
||||
### 获取当前账号权限码集合
|
||||
因为每个项目的需求不同，其权限设计也千变万化，【获取当前账号权限码集合】这一操作不可能内置到框架中，
|
||||
所以`sa-token`将此操作以接口的方式暴露给你，以方便的你根据自己的业务逻辑进行重写
|
||||
|
||||
- 你需要做的就是新建一个类，重写`StpInterface`接口，例如以下代码：
|
||||
你需要做的就是新建一个类，实现`StpInterface`接口，例如以下代码：
|
||||
|
||||
``` java
|
||||
package com.pj.satoken;
|
||||
@ -29,7 +31,7 @@ import cn.dev33.satoken.stp.StpInterface;
|
||||
/**
|
||||
* 自定义权限验证接口扩展
|
||||
*/
|
||||
@Component // 保证此类被springboot扫描，完成sa-token的自定义权限验证扩展
|
||||
@Component // 保证此类被SpringBoot扫描，完成sa-token的自定义权限验证扩展
|
||||
public class StpInterfaceImpl implements StpInterface {
|
||||
|
||||
/**
|
||||
@ -63,31 +65,51 @@ public class StpInterfaceImpl implements StpInterface {
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
- 可参考代码：[码云：StpInterfaceImpl.java](https://gitee.com/sz6/sa-token/blob/master/sa-token-demo-springboot/src/main/java/com/pj/satoken/StpInterfaceImpl.java)
|
||||
可参考代码：[码云：StpInterfaceImpl.java](https://gitee.com/sz6/sa-token/blob/master/sa-token-demo-springboot/src/main/java/com/pj/satoken/StpInterfaceImpl.java)
|
||||
|
||||
|
||||
|
||||
## 验证是否包含指定权限码
|
||||
### 权限验证
|
||||
然后就可以用以下api来鉴权了
|
||||
|
||||
#### StpUtil.hasPermission(Object pcode)
|
||||
- 查询当前账号是否含有指定权限，返回true或false
|
||||
``` java
|
||||
// 当前账号是否含有指定权限, 返回true或false
|
||||
StpUtil.hasPermission("user:update");
|
||||
|
||||
#### StpUtil.checkPermission(Object pcode)
|
||||
- 检测当前账号是否含有指定权限，如果有则安全通过，如果没有则抛出异常：`NotPermissionException`
|
||||
- 扩展：`NotPermissionException` 对象可通过 `getLoginKey()` 方法获取具体是哪个 `StpLogic` 抛出的异常
|
||||
// 当前账号是否含有指定权限, 如果验证未通过，则抛出异常: NotPermissionException
|
||||
StpUtil.checkPermission("user:update");
|
||||
|
||||
#### StpUtil.checkPermissionAnd(Object... pcode)
|
||||
- 检测当前账号是否含有指定权限【指定多个，必须全都有，否则抛出异常】
|
||||
// 当前账号是否含有指定权限 [指定多个，必须全部验证通过]
|
||||
StpUtil.checkPermissionAnd("user:update", "user:delete");
|
||||
|
||||
#### StpUtil.checkPermissionOr(Object... pcode)
|
||||
- 检测当前账号是否含有指定权限【指定多个，有一个就可以了，全都没有才会抛出异常】
|
||||
// 当前账号是否含有指定权限 [指定多个，只要其一验证通过即可]
|
||||
StpUtil.checkPermissionOr("user:update", "user:delete");
|
||||
```
|
||||
|
||||
扩展：`NotPermissionException` 对象可通过 `getLoginKey()` 方法获取具体是哪个 `StpLogic` 抛出的异常
|
||||
|
||||
|
||||
### 角色验证
|
||||
在sa-token中，角色和权限可以独立验证
|
||||
|
||||
``` java
|
||||
// 当前账号是否含有指定角色标识, 返回true或false
|
||||
StpUtil.hasRole("user:update");
|
||||
|
||||
// 当前账号是否含有指定角色标识, 如果验证未通过，则抛出异常: NotRoleException
|
||||
StpUtil.checkRole("user:update");
|
||||
|
||||
// 当前账号是否含有指定角色标识 [指定多个，必须全部验证通过]
|
||||
StpUtil.checkRoleAnd("user:update", "user:delete");
|
||||
|
||||
// 当前账号是否含有指定角色标识 [指定多个，只要其一验证通过即可]
|
||||
StpUtil.checkRoleOr("user:update", "user:delete");
|
||||
```
|
||||
|
||||
扩展：`NotRoleException` 对象可通过 `getLoginKey()` 方法获取具体是哪个 `StpLogic` 抛出的异常
|
||||
|
||||
|
||||
|
||||
|
||||
## 拦截全局异常
|
||||
- 有同学要问，鉴权失败，抛出异常，然后呢？要把异常显示给用户看吗？
|
||||
- 当然不能把异常抛给用户看，你可以创建一个全局异常拦截器，统一返回给前端的格式，例如以下示例：
|
||||
- 参考：[码云：GlobalException.java](https://gitee.com/sz6/sa-token/blob/master/sa-token-demo-springboot/src/main/java/com/pj/test/GlobalException.java)
|
||||
### 拦截全局异常
|
||||
有同学要问，鉴权失败，抛出异常，然后呢？要把异常显示给用户看吗？**当然不可以！** <br>
|
||||
你可以创建一个全局异常拦截器，统一返回给前端的格式，参考：[码云：GlobalException.java](https://gitee.com/sz6/sa-token/blob/master/sa-token-demo-springboot/src/main/java/com/pj/test/GlobalException.java)
|
||||
@ -10,7 +10,7 @@
|
||||
让指定loginId的会话注销登录（踢人下线），例如：
|
||||
|
||||
``` java
|
||||
// 使账号id为10001的会话注销登录，待到10001再次访问系统时会抛出`NotLoginException`异常，场景值为-5
|
||||
StpUtil.logoutByLoginId(10001);
|
||||
// 使账号id为10001的会话注销登录，待到10001再次访问系统时会抛出`NotLoginException`异常，场景值为-5
|
||||
StpUtil.logoutByLoginId(10001);
|
||||
```
|
||||
|
||||
|
||||
@ -2,45 +2,71 @@
|
||||
---
|
||||
|
||||
|
||||
## 核心思想
|
||||
### 核心思想
|
||||
|
||||
- 所谓登录验证，说白了就是限制某些接口只有登录后才能访问（如：查询我的账号资料）
|
||||
- 如何判断你有没有登录？当然是登录成功后我给你做个标记
|
||||
- 在需要鉴权的接口里检查标记，有标记者视为已登录，无标记者视为未登录
|
||||
- 根据以上思路，我们很容易想到以下api：
|
||||
所谓登录验证，说白了就是限制某些接口只有登录后才能访问（如：查询我的账号资料） <br>
|
||||
那么判断一个会话是否登录的依据是什么？当然是登录成功后框架给你做个标记！然后在需要鉴权的接口里检查此标记，有标记者视为已登录，无标记者视为未登录！
|
||||
|
||||
|
||||
## 具体API
|
||||
|
||||
#### StpUtil.setLoginId(Object loginId)
|
||||
- 标记当前会话登录的账号id
|
||||
- 建议的参数类型：`long | int | String`， 不可以传入复杂类型，如：`User`、`Admin`等等
|
||||
### 登录与注销
|
||||
根据以上思路，我们很容易想到以下api：
|
||||
|
||||
#### StpUtil.logout()
|
||||
- 当前会话注销登录
|
||||
``` java
|
||||
// 标记当前会话登录的账号id
|
||||
// 建议的参数类型：long | int | String， 不可以传入复杂类型，如：User、Admin等等
|
||||
StpUtil.setLoginId(Object loginId);
|
||||
|
||||
#### StpUtil.isLogin()
|
||||
- 获取当前会话是否已经登录，返回true=已登录，false=未登录
|
||||
// 当前会话注销登录
|
||||
StpUtil.logout();
|
||||
|
||||
#### StpUtil.checkLogin()
|
||||
- 检验当前会话是否已经登录, 如果未登录，则抛出异常：`NotLoginException`
|
||||
- 扩展：`NotLoginException` 对象可通过 `getLoginKey()` 方法获取具体是哪个 `StpLogic` 抛出的异常
|
||||
- 扩展：`NotLoginException` 对象可通过 `getType()` 方法获取具体的场景值，详细参考章节：[未登录场景值](/fun/not-login-scene)
|
||||
// 获取当前会话是否已经登录，返回true=已登录，false=未登录
|
||||
StpUtil.isLogin();
|
||||
|
||||
#### StpUtil.getLoginId()
|
||||
- 获取当前会话登录id, 如果未登录，则抛出异常：`NotLoginException`
|
||||
- 类似API还有：
|
||||
- `StpUtil.getLoginIdAsString()` 获取当前会话登录id, 并转化为`String`类型
|
||||
- `StpUtil.getLoginIdAsInt()` 获取当前会话登录id, 并转化为`int`类型
|
||||
- `StpUtil.getLoginIdAsLong()` 获取当前会话登录id, 并转化为`long`类型
|
||||
// 检验当前会话是否已经登录, 如果未登录，则抛出异常：`NotLoginException`
|
||||
StpUtil.checkLogin()
|
||||
```
|
||||
|
||||
#### StpUtil.getLoginId(T defaultValue)
|
||||
- 获取当前会话登录id, 如果未登录，则返回默认值 （`defaultValue`可以为任意类型）
|
||||
- 类似API还有：
|
||||
- `StpUtil.getLoginIdDefaultNull()` 获取当前会话登录id, 如果未登录，则返回null
|
||||
扩展：`NotLoginException` 对象可通过 `getLoginKey()` 方法获取具体是哪个 `StpLogic` 抛出的异常 <br>
|
||||
扩展：`NotLoginException` 对象可通过 `getType()` 方法获取具体的场景值，详细参考章节：[未登录场景值](/fun/not-login-scene)
|
||||
|
||||
|
||||
### 会话查询
|
||||
``` java
|
||||
// 获取当前会话登录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);
|
||||
|
||||
```
|
||||
|
||||
|
||||
### 其它API
|
||||
``` java
|
||||
// 获取指定token对应的登录id，如果未登录，则返回 null
|
||||
StpUtil.getLoginIdByToken(String tokenValue);
|
||||
|
||||
// 获取当前`StpLogic`的token名称
|
||||
StpUtil.getTokenName();
|
||||
|
||||
// 获取当前会话的token值
|
||||
StpUtil.getTokenValue();
|
||||
|
||||
// 获取当前会话的token信息参数
|
||||
StpUtil.getTokenInfo();
|
||||
```
|
||||
|
||||
有关TokenInfo参数详解，请参考：[参考：TokenInfo参数详解](/fun/token-info)
|
||||
|
||||
#### StpUtil.getLoginIdByToken(String tokenValue)
|
||||
- 获取指定token对应的登录id，如果未登录，则返回 null
|
||||
|
||||
#### StpUtil.getTokenName()
|
||||
- 获取当前`StpLogic`的token名称
|
||||
|
||||
@ -2,20 +2,32 @@
|
||||
---
|
||||
|
||||
|
||||
- 以上介绍的api都是操作当前账号，对当前账号进行各种鉴权操作，你可能会问，我能不能对别的账号进行一些操作？
|
||||
- 比如：查看账号`10001`有无某个权限码、获取id账号为`10002`的用户`User-Session`，等等...
|
||||
- `sa-token`在api设计时充分考虑了这一点，暴露出多个api进行此类操作
|
||||
以上介绍的api都是操作当前账号，对当前账号进行各种鉴权操作，你可能会问，我能不能对别的账号进行一些操作？<br>
|
||||
比如：查看账号`10001`有无某个权限码、获取id账号为`10002`的用户`User-Session`，等等...
|
||||
|
||||
sa-token在api设计时充分考虑了这一点，暴露出多个api进行此类操作
|
||||
|
||||
|
||||
## 有关操作其它账号的api
|
||||
|
||||
``` java
|
||||
StpUtil.getTokenValueByLoginId(10001); // 获取指定账号10001的`tokenValue`值
|
||||
StpUtil.logoutByLoginId(10001); // 将账号10001的会话注销登录（踢人下线）
|
||||
StpUtil.getSessionByLoginId(10001); // 获取账号10001的Session对象, 如果session尚未创建, 则新建并返回
|
||||
StpUtil.getSessionByLoginId(10001, false); // 获取账号10001的Session对象, 如果session尚未创建, 则返回null
|
||||
StpUtil.hasRole("super-admin"); // 获取账号10001是否含有指定角色标识
|
||||
StpUtil.hasPermission("user:add"); // 获取账号10001是否含有指定权限码
|
||||
// 获取指定账号10001的`tokenValue`值
|
||||
StpUtil.getTokenValueByLoginId(10001);
|
||||
|
||||
// 将账号10001的会话注销登录（踢人下线）
|
||||
StpUtil.logoutByLoginId(10001);
|
||||
|
||||
// 获取账号10001的Session对象, 如果session尚未创建, 则新建并返回
|
||||
StpUtil.getSessionByLoginId(10001);
|
||||
|
||||
// 获取账号10001的Session对象, 如果session尚未创建, 则返回null
|
||||
StpUtil.getSessionByLoginId(10001, false);
|
||||
|
||||
// 获取账号10001是否含有指定角色标识
|
||||
StpUtil.hasRole("super-admin");
|
||||
|
||||
// 获取账号10001是否含有指定权限码
|
||||
StpUtil.hasPermission("user:add");
|
||||
```
|
||||
|
||||
|
||||
@ -24,27 +36,19 @@ StpUtil.hasPermission("user:add"); // 获取账号10001是否含有
|
||||
|
||||
有时候，我们需要直接将当前会话的身份切换为其它账号，比如：
|
||||
``` java
|
||||
StpUtil.switchTo(10044); // 将当前会话[身份临时切换]为其它账号
|
||||
StpUtil.getLoginId(); // 此时再调用此方法会返回 10044 (我们临时切换到的账号id)
|
||||
StpUtil.endSwitch(); // 结束 [身份临时切换]
|
||||
// 将当前会话[身份临时切换]为其它账号
|
||||
StpUtil.switchTo(10044);
|
||||
|
||||
// 此时再调用此方法会返回 10044 (我们临时切换到的账号id)
|
||||
StpUtil.getLoginId();
|
||||
|
||||
// 结束 [身份临时切换]
|
||||
StpUtil.endSwitch();
|
||||
```
|
||||
|
||||
你还可以: 直接在一个代码段里方法内，临时切换身份为指定loginId (此方式无需手动调用`StpUtil.endSwitch()`关闭身份切换)
|
||||
``` java
|
||||
System.out.println("------- [身份临时切换]调用开始...");
|
||||
StpUtil.switchTo(10044, new SaFunction() {
|
||||
@Override
|
||||
public void run() {
|
||||
System.out.println("是否正在身份临时切换中: " + StpUtil.isSwitch());
|
||||
System.out.println("获取当前登录账号id: " + StpUtil.getLoginId());
|
||||
}
|
||||
});
|
||||
System.out.println("------- [身份临时切换]调用结束...");
|
||||
```
|
||||
|
||||
如果你使用的JDK版本是1.8或以上，上面这一坨可以简写为以下形式：
|
||||
``` java
|
||||
System.out.println("------- [身份临时切换]调用开始...");
|
||||
StpUtil.switchTo(10044, () -> {
|
||||
System.out.println("是否正在身份临时切换中: " + StpUtil.isSwitch());
|
||||
System.out.println("获取当前登录账号id: " + StpUtil.getLoginId());
|
||||
|
||||
@ -13,27 +13,31 @@
|
||||
|
||||
#### 指定设备标识登录
|
||||
``` java
|
||||
StpUtil.setLoginId(10001, "PC"); // 指定`账号id`和`设备标识`进行登录
|
||||
// 指定`账号id`和`设备标识`进行登录
|
||||
StpUtil.setLoginId(10001, "PC");
|
||||
```
|
||||
调用此方法登录后，同设备的会被顶下线(不同设备不受影响)，再次访问系统时会抛出 `NotLoginException` 异常，场景值=`-4`
|
||||
|
||||
|
||||
#### 指定设备标识强制注销
|
||||
``` java
|
||||
StpUtil.logoutByLoginId(10001, "PC"); // 指定`账号id`和`设备标识`进行强制注销 (踢人下线)
|
||||
// 指定`账号id`和`设备标识`进行强制注销 (踢人下线)
|
||||
StpUtil.logoutByLoginId(10001, "PC");
|
||||
```
|
||||
如果第二个参数填写null或不填，代表将这个账号id所有在线端踢下线，被踢出者再次访问系统时会抛出 `NotLoginException` 异常，场景值=`-5`
|
||||
|
||||
|
||||
#### 查询当前登录的设备标识
|
||||
``` java
|
||||
StpUtil.getLoginDevice(); // 指返回当前token的登录设备
|
||||
// 返回当前token的登录设备
|
||||
StpUtil.getLoginDevice();
|
||||
```
|
||||
|
||||
|
||||
#### id反查token
|
||||
``` java
|
||||
StpUtil.getTokenValueByLoginId(10001, "APP"); // 获取指定loginId指定设备端的tokenValue
|
||||
// 获取指定loginId指定设备端的tokenValue
|
||||
StpUtil.getTokenValueByLoginId(10001, "APP");
|
||||
```
|
||||
|
||||
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
# 无cookie模式
|
||||
---
|
||||
|
||||
### 何为无cookie
|
||||
### 何为无cookie?
|
||||
|
||||
- 常规PC端鉴权方法，一般由`cookie`进行
|
||||
- 而`cookie`有两个特性：1、可由后端控制写入，2、每次请求自动提交
|
||||
|
||||
@ -8,19 +8,14 @@ sa-token提供以下API助你直接操作会话列表
|
||||
|
||||
## 具体API
|
||||
|
||||
#### 查询所有token
|
||||
``` java
|
||||
// 查询所有token
|
||||
StpUtil.searchTokenValue(String keyword, int start, int size);
|
||||
```
|
||||
|
||||
#### 查询所有账号Session会话
|
||||
``` java
|
||||
// 查询所有账号Session会话
|
||||
StpUtil.searchSessionId(String keyword, int start, int size);
|
||||
```
|
||||
|
||||
|
||||
#### 查询所有令牌Session会话
|
||||
``` java
|
||||
// 查询所有令牌Session会话
|
||||
StpUtil.searchTokenSessionId(String keyword, int start, int size);
|
||||
```
|
||||
|
||||
|
||||
@ -2,43 +2,62 @@
|
||||
---
|
||||
|
||||
Session是会话中专业的数据缓存组件，在`sa-token`中Session分为三种, 分别是：
|
||||
- `账号Session`: 指的是框架为每个`loginId`分配的`Session`
|
||||
- `令牌Session`: 指的是框架为每个`token`分配的`Session`
|
||||
- `User-Session`: 指的是框架为每个`loginId`分配的`Session`
|
||||
- `Token-Session`: 指的是框架为每个`token`分配的`Session`
|
||||
- `自定义Session`: 指的是以一个`特定的值`作为SessionId，来分配的`Session`
|
||||
|
||||
|
||||
## 账号Session
|
||||
### User-Session
|
||||
有关账号Session的API如下：
|
||||
``` java
|
||||
StpUtil.getSession(); // 获取当前账号id的Session (必须是登录后才能调用)
|
||||
StpUtil.getSession(true); // 获取当前账号id的Session, 并决定在Session尚未创建时，是否新建并返回
|
||||
StpUtil.getSessionByLoginId(10001); // 获取账号id为10001的Session
|
||||
StpUtil.getSessionByLoginId(10001, true); // 获取账号id为10001的Session, 并决定在Session尚未创建时，是否新建并返回
|
||||
StpUtil.getSessionBySessionId("xxxx-xxxx"); // 获取SessionId为xxxx-xxxx的Session, 在Session尚未创建时, 返回null
|
||||
// 获取当前账号id的Session (必须是登录后才能调用)
|
||||
StpUtil.getSession();
|
||||
|
||||
// 获取当前账号id的Session, 并决定在Session尚未创建时，是否新建并返回
|
||||
StpUtil.getSession(true);
|
||||
|
||||
// 获取账号id为10001的Session
|
||||
StpUtil.getSessionByLoginId(10001);
|
||||
|
||||
// 获取账号id为10001的Session, 并决定在Session尚未创建时，是否新建并返回
|
||||
StpUtil.getSessionByLoginId(10001, true);
|
||||
|
||||
// 获取SessionId为xxxx-xxxx的Session, 在Session尚未创建时, 返回null
|
||||
StpUtil.getSessionBySessionId("xxxx-xxxx");
|
||||
```
|
||||
|
||||
|
||||
## 令牌Session
|
||||
### Token-Session
|
||||
有关令牌Session的API如下：
|
||||
``` java
|
||||
StpUtil.getTokenSession(); // 获取当前token的专属Session
|
||||
StpUtil.getTokenSessionByToken(token); // 获取指定token的专属Session
|
||||
// 获取当前token的专属Session
|
||||
StpUtil.getTokenSession();
|
||||
|
||||
// 获取指定token的专属Session
|
||||
StpUtil.getTokenSessionByToken(token);
|
||||
```
|
||||
在未登录状态下是否可以获取`Token-Session`？这取决于你配置的`tokenSessionCheckLogin`值是否为false，详见：[框架配置](/use/config?id=所有可配置项)
|
||||
|
||||
|
||||
## 自定义Session
|
||||
### 自定义Session
|
||||
自定义Session指的是以一个`特定的值`作为SessionId来分配的`Session`, 借助自定义Session，你可以为系统中的任意元素分配相应的session<br>
|
||||
例如以商品id作为key为每个商品分配一个Session，以便于缓存和商品相关的数据，其相关API如下：
|
||||
``` java
|
||||
SaSessionCustomUtil.isExists("goods-10001"); // 查询指定key的Session是否存在
|
||||
SaSessionCustomUtil.getSessionById("goods-10001"); // 获取指定key的Session，如果没有，则新建并返回
|
||||
SaSessionCustomUtil.getSessionById("goods-10001", false); // 获取指定key的Session，如果没有，第二个参数决定是否新建并返回
|
||||
SaSessionCustomUtil.deleteSessionById("goods-10001"); // 删除指定key的Session
|
||||
// 查询指定key的Session是否存在
|
||||
SaSessionCustomUtil.isExists("goods-10001");
|
||||
|
||||
// 获取指定key的Session，如果没有，则新建并返回
|
||||
SaSessionCustomUtil.getSessionById("goods-10001");
|
||||
|
||||
// 获取指定key的Session，如果没有，第二个参数决定是否新建并返回
|
||||
SaSessionCustomUtil.getSessionById("goods-10001", false);
|
||||
|
||||
// 删除指定key的Session
|
||||
SaSessionCustomUtil.deleteSessionById("goods-10001");
|
||||
```
|
||||
在未登录状态下是否可以获取令牌Session？这取决于你配置的`tokenSessionCheckLogin`值是否为false，详见：[框架配置](/use/config?id=所有可配置项)
|
||||
|
||||
|
||||
## Session相关操作
|
||||
### Session相关操作
|
||||
那么获取到的`SaSession`具体有哪些方法可供操作？
|
||||
``` java
|
||||
session.getId(); // 返回此Session的id
|
||||
@ -50,9 +69,9 @@ session.removeAttribute('name'); // 在Session上移除一个值
|
||||
session.clearAttribute(); // 清空此Session的所有值
|
||||
session.containsAttribute('name'); // 获取此Session是否含有指定key (返回true或false)
|
||||
session.attributeKeys(); // 获取此Session会话上所有key (返回Set<String>)
|
||||
session.getDataMap(); // 返回此Session会话上的底层数据对象（如果更新map里的值，请调用session.update()方法避免数据过时）
|
||||
session.getDataMap(); // 返回此Session会话上的底层数据对象（如果更新map里的值，请调用session.update()方法避免产生脏数据）
|
||||
session.update(); // 将这个Session从持久库更新一下
|
||||
session.logout(); // 注销此Session会话
|
||||
session.logout(); // 注销此Session会话 (从持久库删除此Session)
|
||||
```
|
||||
具体可参考`javax.servlet.http.HttpSession`，`SaSession`所含方法与其大体类似
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user