diff --git a/sa-token-doc/doc/fun/sa-token-context.md b/sa-token-doc/doc/fun/sa-token-context.md index 1bcf707b..369d1b0d 100644 --- a/sa-token-doc/doc/fun/sa-token-context.md +++ b/sa-token-doc/doc/fun/sa-token-context.md @@ -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`包即可： diff --git a/sa-token-doc/doc/fun/token-timeout.md b/sa-token-doc/doc/fun/token-timeout.md index 469640d1..6c82d65b 100644 --- a/sa-token-doc/doc/fun/token-timeout.md +++ b/sa-token-doc/doc/fun/token-timeout.md @@ -2,8 +2,26 @@ -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必定过期，无法继续使用 diff --git a/sa-token-doc/doc/start/download.md b/sa-token-doc/doc/start/download.md index 8d72f53f..8c0c52bb 100644 --- a/sa-token-doc/doc/start/download.md +++ b/sa-token-doc/doc/start/download.md @@ -7,7 +7,7 @@ - + 如果你使用的框架基于 ServletAPI 构建（ SpringMVC、SpringBoot等 ），请引入此包 ``` xml @@ -102,7 +102,7 @@ ## Gradle依赖 - + ``` xml implementation 'cn.dev33:sa-token-spring-boot-starter:${sa.top.version}' ``` diff --git a/sa-token-doc/doc/up/search-session.md b/sa-token-doc/doc/up/search-session.md index 3e6d6c31..0f74aa68 100644 --- a/sa-token-doc/doc/up/search-session.md +++ b/sa-token-doc/doc/up/search-session.md @@ -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 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 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 tokenSignList = session.getTokenSignList(); + System.out.println("会话id：" + sessionId + "，共在 " + tokenSignList.size() + " 设备登录"); +} +``` + +
diff --git a/sa-token-doc/doc/use/route-check.md b/sa-token-doc/doc/use/route-check.md index 99ca4b83..7369f891 100644 --- a/sa-token-doc/doc/use/route-check.md +++ b/sa-token-doc/doc/use/route-check.md @@ -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("/**"); +} +``` \ No newline at end of file