mirror of
https://gitee.com/dromara/sa-token.git
synced 2025-08-23 13:06:43 +08:00
完善文档
This commit is contained in:
click33
parent
9fda298ea6
commit
528379f77b
@ -60,8 +60,14 @@ public interface SaTokenContext {
|
||||
}
|
||||
```
|
||||
|
||||
你可能对 `SaRequest` 比较疑惑，这个对象是干什么用的？正如每个 Web 框架都有 Request 概念的抽象，Sa-Token 也封装了 `Request`、`Response`、`Storage`三者的抽象，
|
||||
因此在实现 `SaTokenContext` 之前，你必须先实现这三个 Model 接口。
|
||||
你可能对 `SaRequest` 比较疑惑，这个对象是干什么用的？正如每个 Web 框架都有 Request 概念的抽象，Sa-Token 也封装了 `Request`、`Response`、`Storage`三者的抽象：
|
||||
|
||||
- `Request`：请求对象，携带着一次请求的所有参数数据。参考：[SaRequest.java](https://gitee.com/dromara/sa-token/blob/master/sa-token-core/src/main/java/cn/dev33/satoken/context/model/SaRequest.java)。
|
||||
- `Response`：响应对象，携带着对客户端一次响应的所有数据。参考：[SaResponse.java](https://gitee.com/dromara/sa-token/blob/master/sa-token-core/src/main/java/cn/dev33/satoken/context/model/SaResponse.java)。
|
||||
- `Storage`：请求上下文对象，提供 [一次请求范围内] 的上下文数据读写。参考：[SaStorage.java](https://gitee.com/dromara/sa-token/blob/master/sa-token-core/src/main/java/cn/dev33/satoken/context/model/SaStorage.java)。
|
||||
|
||||
|
||||
因此，在实现 `SaTokenContext` 之前，你必须先实现这三个 Model 接口。
|
||||
|
||||
先别着急动手，如果你的 Web 框架是基于 Servlet 规范开发的，那么 Sa-Token 已经为你封装好了三个 Model 接口的实现，你要做的就是引入 `sa-token-servlet`包即可：
|
||||
|
||||
|
||||
@ -2,8 +2,26 @@
|
||||
|
||||
<!-- 本篇介绍Token有效期的详细用法 -->
|
||||
|
||||
Sa-Token 提供两种Token自动过期策略，分别是`timeout`与`activity-timeout`，其详细用法如下：
|
||||
Sa-Token 提供两种Token自动过期策略，分别是`timeout`与`activity-timeout`，配置方法如下：
|
||||
|
||||
``` yml
|
||||
sa-token:
|
||||
# Token 有效期，单位：秒，默认30天, -1代表永不过期
|
||||
timeout: 2592000
|
||||
# Token 临时有效期 (指定时间内无操作就视为 Token 过期) 单位: 秒，-1代表不设限
|
||||
activity-timeout: -1
|
||||
```
|
||||
|
||||
两者的区别，可以通过下面的例子体现：
|
||||
|
||||
> 1. 假设你到银行要存钱，首先就要办理一张卡 （要访问系统接口先登录）。
|
||||
> 2. 银行为你颁发一张储蓄卡（系统为你颁发一个Token），以后每次存取钱都要带上这张卡（后续每次访问系统都要提交 Token）。
|
||||
> 3. 银行为这张卡设定两个过期时间：
|
||||
> - 第一个是 `timeout`，代表这张卡的长久有效期，就是指这张卡最长能用多久，假设 `timeout=3年`，那么3年后此卡将被银行删除，想要继续来银行办理业务必须重新办卡（Token 过期后想要访问系统必须重新登录）。
|
||||
> - 第二个就是 `activity-timeout`，代表这张卡的临时有效期，就是指这张卡必须每隔多久来银行一次，假设 `activity-timeout=1月` ，你如果超过1月不来办一次业务，银行就将你的卡冻结，列为长期不动户（Token 长期不访问系统，被冻结，但不会被删除）。
|
||||
> 4. 两个过期策略可以单独配置，也可以同时配置，只要有其中一个有效期超出了范围，这张卡就会变得不可用（两个有效期只要有一个过期了，Token就无法成功访问系统了）。
|
||||
|
||||
下面是对两个过期策略的详细解释：
|
||||
|
||||
### timeout
|
||||
1. `timeout`代表Token的长久有效期，单位/秒，例如将其配置为 2592000 (30天)，代表在30天后，Token必定过期，无法继续使用
|
||||
|
||||
@ -7,7 +7,7 @@
|
||||
|
||||
<!------------------------------ tabs:start ------------------------------>
|
||||
|
||||
<!------------- tab:SpringMVC环境 （ServletAPI） ------------->
|
||||
<!------------- tab:SpringBoot环境 （ServletAPI） ------------->
|
||||
如果你使用的框架基于 ServletAPI 构建（ SpringMVC、SpringBoot等 ），请引入此包
|
||||
``` xml
|
||||
<!-- Sa-Token 权限认证, 在线文档：http://sa-token.dev33.cn/ -->
|
||||
@ -102,7 +102,7 @@
|
||||
|
||||
## Gradle依赖
|
||||
<!-- tabs:start -->
|
||||
<!-- tab:SpringMVC环境 （ServletAPI） -->
|
||||
<!-- tab:SpringBoot环境 （ServletAPI） -->
|
||||
``` xml
|
||||
implementation 'cn.dev33:sa-token-spring-boot-starter:${sa.top.version}'
|
||||
```
|
||||
|
||||
@ -10,13 +10,13 @@ Sa-Token提供以下API助你直接操作会话列表：
|
||||
## 具体API
|
||||
|
||||
``` java
|
||||
// 查询所有token
|
||||
// 查询所有已登录的 Token
|
||||
StpUtil.searchTokenValue(String keyword, int start, int size, boolean sortType);
|
||||
|
||||
// 查询所有账号Session会话
|
||||
// 查询所有账号 Session 会话
|
||||
StpUtil.searchSessionId(String keyword, int start, int size, boolean sortType);
|
||||
|
||||
// 查询所有令牌Session会话
|
||||
// 查询所有令牌 Session 会话
|
||||
StpUtil.searchTokenSessionId(String keyword, int start, int size, boolean sortType);
|
||||
```
|
||||
|
||||
@ -25,17 +25,53 @@ StpUtil.searchTokenSessionId(String keyword, int start, int size, boolean sortTy
|
||||
- `keyword`: 查询关键字，只有包括这个字符串的 token 值才会被查询出来。
|
||||
- `start`: 数据开始处索引, 值为-1时代表一次性取出所有数据。
|
||||
- `size`: 要获取的数据条数。
|
||||
- `sortType`: 排序方式（true=正序，false=反序）。
|
||||
- `sortType`: 排序方式（true=正序：先登录的在前，false=反序：后登录的在前）。
|
||||
|
||||
使用示例：
|
||||
简单样例：
|
||||
``` java
|
||||
// 查询value包括1000的所有token，结果集从第0条开始，返回10条
|
||||
// 查询 value 包括 1000 的所有 token，结果集从第 0 条开始，返回 10 条
|
||||
List<String> tokenList = StpUtil.searchTokenValue("1000", 0, 10, true);
|
||||
for (String token : tokenList) {
|
||||
System.out.println(token);
|
||||
}
|
||||
```
|
||||
|
||||
#### 深入：`StpUtil.searchTokenValue` 和 `StpUtil.searchSessionId` 有哪些区别？
|
||||
|
||||
- StpUtil.searchTokenValue 查询的是登录产生的所有 Token。
|
||||
- StpUtil.searchSessionId 查询的是所有已登录账号会话id。
|
||||
|
||||
举个例子，项目配置如下：
|
||||
``` yml
|
||||
sa-token:
|
||||
# 允许同一账号在多个设备一起登录
|
||||
is-concurrent: true
|
||||
# 同一账号每次登录产生不同的token
|
||||
is-share: false
|
||||
```
|
||||
|
||||
假设此时账号A在 电脑、手机、平板 依次登录（共3次登录），账号B在 电脑、手机 依次登录（共2次登录），那么：
|
||||
|
||||
- `StpUtil.searchTokenValue` 将返回一共 5 个Token。
|
||||
- `StpUtil.searchSessionId` 将返回一共 2 个 SessionId。
|
||||
|
||||
综上，若要遍历系统所有已登录的会话，代码将大致如下：
|
||||
``` java
|
||||
// 获取所有已登录的会话id
|
||||
List<String> sessionIdList = StpUtil.searchSessionId("", -1, -1, false);
|
||||
|
||||
for (String sessionId : sessionIdList) {
|
||||
|
||||
// 根据会话id，查询对应的 SaSession 对象，此处一个 SaSession 对象即代表一个登录的账号
|
||||
SaSession session = StpUtil.getSessionBySessionId(sessionId);
|
||||
|
||||
// 查询这个账号都在哪些设备登录了，依据上面的示例，账号A 的 tokenSign 数量是 3，账号B 的 tokenSign 数量是 2
|
||||
List<TokenSign> tokenSignList = session.getTokenSignList();
|
||||
System.out.println("会话id：" + sessionId + "，共在 " + tokenSignList.size() + " 设备登录");
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
<br/>
|
||||
|
||||
|
||||
@ -210,3 +210,18 @@ public SaResult getList() {
|
||||
|
||||
**注意点：此注解的忽略效果只针对 SaInterceptor拦截器 和 AOP注解鉴权 生效，对自定义拦截器与过滤器不生效。**
|
||||
|
||||
|
||||
### 7、关闭注解校验
|
||||
|
||||
`SaInterceptor` 只要注册到项目中，默认就会打开注解校验，如果要关闭此能力，需要：
|
||||
|
||||
``` java
|
||||
@Override
|
||||
public void addInterceptors(InterceptorRegistry registry) {
|
||||
registry.addInterceptor(
|
||||
new SaInterceptor(handle -> {
|
||||
SaRouter.match("/**").check(r -> StpUtil.checkLogin());
|
||||
}).isAnnotation(false) // 指定关闭掉注解鉴权能力，这样框架就只会做路由拦截校验了
|
||||
).addPathPatterns("/**");
|
||||
}
|
||||
```
|
||||
Loading…
Reference in New Issue
Block a user