From 47e879ad5e1a03f1e537865aabf21cec85e70421 Mon Sep 17 00:00:00 2001 From: shengzhang <2393584716@qq.com> Date: Sun, 31 Jan 2021 23:28:42 +0800 Subject: [PATCH] =?UTF-8?q?=E5=AE=8C=E5=96=84=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../java/cn/dev33/satoken/stp/StpLogic.java | 20 ++--- .../java/cn/dev33/satoken/stp/StpUtil.java | 50 +++++------ .../java/com/pj/satoken/StpInterfaceImpl.java | 8 +- sa-token-doc/doc/_sidebar.md | 5 +- sa-token-doc/doc/fun/token-info.md | 22 +++++ sa-token-doc/doc/more/common-questions.md | 17 ++-- sa-token-doc/doc/start/example.md | 17 ++-- sa-token-doc/doc/use/dao-extend.md | 4 +- sa-token-doc/doc/use/jur-auth.md | 78 ++++++++++------ sa-token-doc/doc/use/kick.md | 4 +- sa-token-doc/doc/use/login-auth.md | 88 ++++++++++++------- sa-token-doc/doc/use/mock-person.md | 54 ++++++------ sa-token-doc/doc/use/mutex-login.md | 12 ++- sa-token-doc/doc/use/not-cookie.md | 2 +- sa-token-doc/doc/use/search-session.md | 11 +-- sa-token-doc/doc/use/session.md | 59 ++++++++----- 16 files changed, 276 insertions(+), 175 deletions(-) create mode 100644 sa-token-doc/doc/fun/token-info.md diff --git a/sa-token-core/src/main/java/cn/dev33/satoken/stp/StpLogic.java b/sa-token-core/src/main/java/cn/dev33/satoken/stp/StpLogic.java index b1da3049..b328513a 100644 --- a/sa-token-core/src/main/java/cn/dev33/satoken/stp/StpLogic.java +++ b/sa-token-core/src/main/java/cn/dev33/satoken/stp/StpLogic.java @@ -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){ diff --git a/sa-token-core/src/main/java/cn/dev33/satoken/stp/StpUtil.java b/sa-token-core/src/main/java/cn/dev33/satoken/stp/StpUtil.java index 6ec62882..d69af20f 100644 --- a/sa-token-core/src/main/java/cn/dev33/satoken/stp/StpUtil.java +++ b/sa-token-core/src/main/java/cn/dev33/satoken/stp/StpUtil.java @@ -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); } diff --git a/sa-token-demo-springboot/src/main/java/com/pj/satoken/StpInterfaceImpl.java b/sa-token-demo-springboot/src/main/java/com/pj/satoken/StpInterfaceImpl.java index 8d30d9c9..28b56d20 100644 --- a/sa-token-demo-springboot/src/main/java/com/pj/satoken/StpInterfaceImpl.java +++ b/sa-token-demo-springboot/src/main/java/com/pj/satoken/StpInterfaceImpl.java @@ -17,8 +17,9 @@ public class StpInterfaceImpl implements StpInterface { * 返回一个账号所拥有的权限码集合 */ @Override - public List getPermissionList(Object login_id, String login_key) { - List list = new ArrayList(); // 本list仅做模拟，实际项目中要根据具体业务逻辑来查询权限 + public List getPermissionList(Object loginId, String loginKey) { + // 本list仅做模拟，实际项目中要根据具体业务逻辑来查询权限 + List list = new ArrayList(); list.add("101"); list.add("user-add"); list.add("user-delete"); @@ -33,7 +34,8 @@ public class StpInterfaceImpl implements StpInterface { */ @Override public List getRoleList(Object loginId, String loginKey) { - List list = new ArrayList(); // 本list仅做模拟，实际项目中要根据具体业务逻辑来查询角色 + // 本list仅做模拟，实际项目中要根据具体业务逻辑来查询角色 + List list = new ArrayList(); list.add("admin"); list.add("super-admin"); return list; diff --git a/sa-token-doc/doc/_sidebar.md b/sa-token-doc/doc/_sidebar.md index 5132b68d..54ac1bb3 100644 --- a/sa-token-doc/doc/_sidebar.md +++ b/sa-token-doc/doc/_sidebar.md @@ -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) diff --git a/sa-token-doc/doc/fun/token-info.md b/sa-token-doc/doc/fun/token-info.md new file mode 100644 index 00000000..4f561cb8 --- /dev/null +++ b/sa-token-doc/doc/fun/token-info.md @@ -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" // 登录设备标识 + }, +} +``` \ No newline at end of file diff --git a/sa-token-doc/doc/more/common-questions.md b/sa-token-doc/doc/more/common-questions.md index eec31188..3b42b37d 100644 --- a/sa-token-doc/doc/more/common-questions.md +++ b/sa-token-doc/doc/more/common-questions.md @@ -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=贡献代码) \ No newline at end of file +**可以**，请参照首页的提交pr步骤 ，[贡献代码](README?id=贡献代码) \ No newline at end of file diff --git a/sa-token-doc/doc/start/example.md b/sa-token-doc/doc/start/example.md index 80b7ed6a..fa716fdf 100644 --- a/sa-token-doc/doc/start/example.md +++ b/sa-token-doc/doc/start/example.md @@ -1,9 +1,10 @@ # 示例 +本篇将带你从零开始集成sa-token，从而让你快速熟悉sa-token的使用姿势
+以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 @@ -23,8 +24,8 @@ ``` #### 3、配置文件 -- 你可以**零配置启动项目** -- 但同时你也可以在`application.yml`中增加如下配置，定制性使用框架： +你可以**零配置启动项目**
+但同时你也可以在`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` 类型的配置文件，那也很好办:
+百度： [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`来完成配置 ## 详细了解 diff --git a/sa-token-doc/doc/use/dao-extend.md b/sa-token-doc/doc/use/dao-extend.md index 80eb9338..c201f70f 100644 --- a/sa-token-doc/doc/use/dao-extend.md +++ b/sa-token-doc/doc/use/dao-extend.md @@ -14,7 +14,7 @@ 1.12.1 ``` -优点：兼容性好，缺点：session序列化后基本不可读，对开发者来讲等同于乱码 +优点：兼容性好，缺点：Session序列化后基本不可读，对开发者来讲等同于乱码 ### 2. sa-token 整合 Redis (使用jackson序列化方式) @@ -26,7 +26,7 @@ 1.12.1 ``` -优点：session序列化后可读性强，可灵活手动修改，缺点：兼容性稍差 +优点：Session序列化后可读性强，可灵活手动修改，缺点：兼容性稍差
diff --git a/sa-token-doc/doc/use/jur-auth.md b/sa-token-doc/doc/use/jur-auth.md index c4bd5821..90e94135 100644 --- a/sa-token-doc/doc/use/jur-auth.md +++ b/sa-token-doc/doc/use/jur-auth.md @@ -2,21 +2,23 @@ --- -## 核心思想 +### 核心思想 -- 所谓权限验证，验证的核心就是当前账号是否拥有一个权限码 -- 有：就让你通过、没有：那么禁止访问 -- 再往底了说，就是每个账号都会拥有一个权限码集合，我来验证这个集合中是否包括我需要检测的那个权限码 -- 例如：当前账号拥有权限码集合：`["user:add", "user:delete", "user:get"]`，这时候我去验证权限码：`"user:update"`，则结果就是验证失败，禁止访问 -- 所以现在问题的核心就是: - 1. 如何获取一个账号所拥有的的权限码集合 - 2. 本次操作要验证的权限码是哪个 +所谓权限验证，验证的核心就是一个账号是否拥有一个权限码
+有，就让你通过。没有？那么禁止访问! -## 获取当前账号权限码集合 +再往底了说，就是每个账号都会拥有一个权限码集合，我来验证这个集合中是否包含指定的权限码
+例如：当前账号拥有权限码集合：`["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) \ No newline at end of file +### 拦截全局异常 +有同学要问，鉴权失败，抛出异常，然后呢？要把异常显示给用户看吗？**当然不可以！**
+你可以创建一个全局异常拦截器，统一返回给前端的格式，参考：[码云：GlobalException.java](https://gitee.com/sz6/sa-token/blob/master/sa-token-demo-springboot/src/main/java/com/pj/test/GlobalException.java) \ No newline at end of file diff --git a/sa-token-doc/doc/use/kick.md b/sa-token-doc/doc/use/kick.md index be0b1a49..021d5d89 100644 --- a/sa-token-doc/doc/use/kick.md +++ b/sa-token-doc/doc/use/kick.md @@ -10,7 +10,7 @@ 让指定loginId的会话注销登录（踢人下线），例如： ``` java - // 使账号id为10001的会话注销登录，待到10001再次访问系统时会抛出`NotLoginException`异常，场景值为-5 - StpUtil.logoutByLoginId(10001); +// 使账号id为10001的会话注销登录，待到10001再次访问系统时会抛出`NotLoginException`异常，场景值为-5 +StpUtil.logoutByLoginId(10001); ``` diff --git a/sa-token-doc/doc/use/login-auth.md b/sa-token-doc/doc/use/login-auth.md index d356d43f..1c232686 100644 --- a/sa-token-doc/doc/use/login-auth.md +++ b/sa-token-doc/doc/use/login-auth.md @@ -2,45 +2,71 @@ --- -## 核心思想 +### 核心思想 -- 所谓登录验证，说白了就是限制某些接口只有登录后才能访问（如：查询我的账号资料） -- 如何判断你有没有登录？当然是登录成功后我给你做个标记 -- 在需要鉴权的接口里检查标记，有标记者视为已登录，无标记者视为未登录 -- 根据以上思路，我们很容易想到以下api： +所谓登录验证，说白了就是限制某些接口只有登录后才能访问（如：查询我的账号资料）
+那么判断一个会话是否登录的依据是什么？当然是登录成功后框架给你做个标记！然后在需要鉴权的接口里检查此标记，有标记者视为已登录，无标记者视为未登录！ -## 具体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` 抛出的异常
+扩展：`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名称 diff --git a/sa-token-doc/doc/use/mock-person.md b/sa-token-doc/doc/use/mock-person.md index d3ea15e4..c9bf2233 100644 --- a/sa-token-doc/doc/use/mock-person.md +++ b/sa-token-doc/doc/use/mock-person.md @@ -2,20 +2,32 @@ --- -- 以上介绍的api都是操作当前账号，对当前账号进行各种鉴权操作，你可能会问，我能不能对别的账号进行一些操作？ -- 比如：查看账号`10001`有无某个权限码、获取id账号为`10002`的用户`User-Session`，等等... -- `sa-token`在api设计时充分考虑了这一点，暴露出多个api进行此类操作 +以上介绍的api都是操作当前账号，对当前账号进行各种鉴权操作，你可能会问，我能不能对别的账号进行一些操作？
+比如：查看账号`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()); diff --git a/sa-token-doc/doc/use/mutex-login.md b/sa-token-doc/doc/use/mutex-login.md index fa87080a..b2697da0 100644 --- a/sa-token-doc/doc/use/mutex-login.md +++ b/sa-token-doc/doc/use/mutex-login.md @@ -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"); ``` diff --git a/sa-token-doc/doc/use/not-cookie.md b/sa-token-doc/doc/use/not-cookie.md index 12d62254..25c3401a 100644 --- a/sa-token-doc/doc/use/not-cookie.md +++ b/sa-token-doc/doc/use/not-cookie.md @@ -1,7 +1,7 @@ # 无cookie模式 --- -### 何为无cookie +### 何为无cookie? - 常规PC端鉴权方法，一般由`cookie`进行 - 而`cookie`有两个特性：1、可由后端控制写入，2、每次请求自动提交 diff --git a/sa-token-doc/doc/use/search-session.md b/sa-token-doc/doc/use/search-session.md index 9a9aa8d2..736749af 100644 --- a/sa-token-doc/doc/use/search-session.md +++ b/sa-token-doc/doc/use/search-session.md @@ -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); ``` diff --git a/sa-token-doc/doc/use/session.md b/sa-token-doc/doc/use/session.md index 8ad2cd73..0152a2fe 100644 --- a/sa-token-doc/doc/use/session.md +++ b/sa-token-doc/doc/use/session.md @@ -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
例如以商品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) -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`所含方法与其大体类似