diff --git a/sa-token-doc/doc/_sidebar.md b/sa-token-doc/doc/_sidebar.md index 7305cc64..3ff13264 100644 --- a/sa-token-doc/doc/_sidebar.md +++ b/sa-token-doc/doc/_sidebar.md @@ -3,8 +3,8 @@ - **开始** - [介绍](/) - [引入](/start/download) - - [在SpringBoot环境集成](/start/example) - - [在WebFlux环境集成](/start/webflux-example) + - [在 SpringBoot 环境集成](/start/example) + - [在 WebFlux 环境集成](/start/webflux-example) - **基础** - [登录认证](/use/login-auth) diff --git a/sa-token-doc/doc/start/download.md b/sa-token-doc/doc/start/download.md index be0ec82b..35d3a10e 100644 --- a/sa-token-doc/doc/start/download.md +++ b/sa-token-doc/doc/start/download.md @@ -195,7 +195,7 @@ implementation 'cn.dev33:sa-token-core:${sa.top.version}' ## jar包下载 [点击下载：sa-token-1.6.0.jar](https://oss.dev33.cn/sa-token/sa-token-1.6.0.jar) -(注意：当前仅提供`v1.6.0`版本jar包下载，更多版本请前往maven中央仓库获取，[直达链接](https://search.maven.org/search?q=sa-token)) +注：当前仅提供 `v1.6.0` 版本jar包下载，更多版本请前往 maven 中央仓库获取，[直达链接](https://search.maven.org/search?q=sa-token) diff --git a/sa-token-doc/doc/start/example.md b/sa-token-doc/doc/start/example.md index d1dce1ac..b2430014 100644 --- a/sa-token-doc/doc/start/example.md +++ b/sa-token-doc/doc/start/example.md @@ -2,8 +2,7 @@ 本篇带你从零开始集成 Sa-Token，从而快速熟悉框架的使用姿势。 -整合示例地址： [/sa-token-demo/sa-token-demo-springboot](https://gitee.com/dromara/sa-token/tree/master/sa-token-demo/sa-token-demo-springboot)， -如遇到难点可结合示例源码进行学习测试。 +整合示例在官方仓库的`/sa-token-demo/sa-token-demo-springboot`文件夹下，如遇到难点可结合源码进行学习测试。 --- diff --git a/sa-token-doc/doc/start/webflux-example.md b/sa-token-doc/doc/start/webflux-example.md index 6af65459..7ac19e56 100644 --- a/sa-token-doc/doc/start/webflux-example.md +++ b/sa-token-doc/doc/start/webflux-example.md @@ -1,16 +1,16 @@ # Spring WebFlux 集成 Sa-Token 示例 **Reactor** 是一种非阻塞的响应式模型，本篇将以 **WebFlux** 为例，展示 Sa-Token 与 Reactor 响应式模型框架相整合的示例， -**你可以用同样方式去对接其它Reactor模型框架（Netty、ShenYu、SpringCloud Gateway等）** +**你可以用同样方式去对接其它 Reactor 模型框架（Netty、ShenYu、SpringCloud Gateway等）** 整合示例在官方仓库的`/sa-token-demo/sa-token-demo-webflux`文件夹下，如遇到难点可结合源码进行测试学习 -!> WebFlux常用于微服务网关架构中，如果您的应用基于单体架构且非 Reactor 模型，可以先跳过本章 +!> WebFlux 常用于微服务网关架构中，如果您的应用基于单体架构且非 Reactor 模型，可以先跳过本章 --- ### 1、创建项目 -在IDE中新建一个SpringBoot项目，例如：`sa-token-demo-webflux`（不会的同学请自行百度或者参考github示例） +在 IDE 中新建一个 SpringBoot 项目，例如：`sa-token-demo-webflux` ### 2、添加依赖 @@ -40,7 +40,7 @@ public class SaTokenDemoApplication { ``` ### 4、创建全局过滤器 -新建`SaTokenConfigure.java`，注册Sa-Token的全局过滤器 +新建`SaTokenConfigure.java`，注册 Sa-Token 的全局过滤器 ``` java /** * [Sa-Token 权限认证] 全局配置类 @@ -71,7 +71,7 @@ public class SaTokenConfigure { } } ``` -?> 你只需要按照此格式复制代码即可，有关过滤器的详细用法，会在之后的章节详细介绍 +你只需要按照此格式复制代码即可，有关过滤器的详细用法，会在之后的章节详细介绍。 ### 5、创建测试Controller @@ -108,7 +108,7 @@ public class UserController { ![运行结果](https://oss.dev33.cn/sa-token/doc/test-is-login.png) -**注意事项** +**注意事项：** 更多使用示例请参考官方仓库demo diff --git a/sa-token-doc/doc/use/jur-auth.md b/sa-token-doc/doc/use/jur-auth.md index dbc7d760..c02c8913 100644 --- a/sa-token-doc/doc/use/jur-auth.md +++ b/sa-token-doc/doc/use/jur-auth.md @@ -2,36 +2,31 @@ --- -### 核心思想 +### 设计思路 -所谓权限认证，认证的核心就是一个账号是否拥有一个权限码
-有，就让你通过。没有？那么禁止访问! +所谓权限认证，核心逻辑就是判断一个账号是否拥有指定权限：
+- 有，就让你通过。 +- 没有？那么禁止访问！ -再往底了说，就是每个账号都会拥有一个权限码集合，我来校验这个集合中是否包含指定的权限码
-例如：当前账号拥有权限码集合：`["user-add", "user-delete", "user-get"]`，这时候我来校验权限 `"user-update"`，则其结果就是：**验证失败，禁止访问**
+深入到底层数据中，就是每个账号都会拥有一个权限码集合，框架来校验这个集合中是否包含指定的权限码。 + +例如：当前账号拥有权限码集合 `["user-add", "user-delete", "user-get"]`，这时候我来校验权限 `"user-update"`，则其结果就是：**验证失败，禁止访问**。
-所以现在问题的核心就是: -1. 如何获取一个账号所拥有的的权限码集合 -2. 本次操作需要验证的权限码是哪个 +所以现在问题的核心就是： +1. 如何获取一个账号所拥有的的权限码集合？ +2. 本次操作需要验证的权限码是哪个？ ### 获取当前账号权限码集合 -因为每个项目的需求不同，其权限设计也千变万化，因此【获取当前账号权限码集合】这一操作不可能内置到框架中， -所以 Sa-Token 将此操作以接口的方式暴露给你，以方便的你根据自己的业务逻辑进行重写 +因为每个项目的需求不同，其权限设计也千变万化，因此 [ 获取当前账号权限码集合 ] 这一操作不可能内置到框架中， +所以 Sa-Token 将此操作以接口的方式暴露给你，以方便你根据自己的业务逻辑进行重写。 -你需要做的就是新建一个类，实现`StpInterface`接口，例如以下代码： +你需要做的就是新建一个类，实现 `StpInterface`接口，例如以下代码： ``` java -package com.pj.satoken; - -import java.util.ArrayList; -import java.util.List; -import org.springframework.stereotype.Component; -import cn.dev33.satoken.stp.StpInterface; - /** * 自定义权限验证接口扩展 */ @@ -69,6 +64,10 @@ public class StpInterfaceImpl implements StpInterface { } ``` +**参数解释：** +- loginId：账号id，即你在调用 `StpUtil.login(id)` 时写入的标识值。 +- loginType：账号体系标识，此处可以暂时忽略，在 [ 多账户认证 ] 章节下会对这个概念做详细的解释。 + 可参考代码：[码云：StpInterfaceImpl.java](https://gitee.com/dromara/sa-token/blob/master/sa-token-demo/sa-token-demo-springboot/src/main/java/com/pj/satoken/StpInterfaceImpl.java) @@ -76,7 +75,10 @@ public class StpInterfaceImpl implements StpInterface { ### 权限认证 然后就可以用以下api来鉴权了 -``` java +``` java +// 获取：当前账号所拥有的权限集合 +StpUtil.getPermissionList(); + // 判断：当前账号是否含有指定权限, 返回true或false StpUtil.hasPermission("user-update"); @@ -87,7 +89,7 @@ StpUtil.checkPermission("user-update"); StpUtil.checkPermissionAnd("user-update", "user-delete"); // 校验：当前账号是否含有指定权限 [指定多个，只要其一验证通过即可] -StpUtil.checkPermissionOr("user-update", "user-delete"); +StpUtil.checkPermissionOr("user-update", "user-delete"); ``` 扩展：`NotPermissionException` 对象可通过 `getLoginType()` 方法获取具体是哪个 `StpLogic` 抛出的异常 @@ -97,6 +99,9 @@ StpUtil.checkPermissionOr("user-update", "user-delete"); 在Sa-Token中，角色和权限可以独立验证 ``` java +// 获取：当前账号所拥有的角色集合 +StpUtil.getRoleList(); + // 判断：当前账号是否拥有指定角色, 返回true或false StpUtil.hasRole("super-admin"); @@ -115,13 +120,27 @@ StpUtil.checkRoleOr("super-admin", "shop-admin"); ### 拦截全局异常 -有同学要问，鉴权失败，抛出异常，然后呢？要把异常显示给用户看吗？**当然不可以！**
+有同学要问，鉴权失败，抛出异常，然后呢？要把异常显示给用户看吗？**当然不可以！** + 你可以创建一个全局异常拦截器，统一返回给前端的格式，参考： -[码云：GlobalException.java](https://gitee.com/dromara/sa-token/blob/master/sa-token-demo/sa-token-demo-springboot/src/main/java/com/pj/current/GlobalException.java) + +``` java +@RestControllerAdvice +public class GlobalExceptionHandler { + // 全局异常拦截 + @ExceptionHandler + public SaResult handlerException(Exception e) { + e.printStackTrace(); + return SaResult.error(e.getMessage()); + } +} +``` + +可参考：[码云：GlobalException.java](https://gitee.com/dromara/sa-token/blob/master/sa-token-demo/sa-token-demo-springboot/src/main/java/com/pj/current/GlobalException.java) ### 权限通配符 -Sa-Token允许你根据通配符指定泛权限，例如当一个账号拥有`user*`的权限时，`user-add`、`user-delete`、`user-update`都将匹配通过 +Sa-Token允许你根据通配符指定**泛权限**，例如当一个账号拥有`user*`的权限时，`user-add`、`user-delete`、`user-update`都将匹配通过 ``` java // 当拥有 user* 权限时 @@ -140,26 +159,26 @@ StpUtil.hasPermission("index.css"); // false StpUtil.hasPermission("index.html"); // false ``` -上帝权限：当一个账号拥有 `"*"` 权限时，他可以验证通过任何权限码 (角色认证同理) +!> 上帝权限：当一个账号拥有 `"*"` 权限时，他可以验证通过任何权限码 （角色认证同理） ### 如何把权限精确到按钮级？ -权限精确到按钮级的意思就是指：**权限范围可以控制到页面上的每一个按钮是否显示** +权限精确到按钮级的意思就是指：**权限范围可以控制到页面上的每一个按钮是否显示**。 -思路：如此精确的范围控制只依赖后端已经难以完成，此时需要前端进行一定的逻辑判断 +思路：如此精确的范围控制只依赖后端已经难以完成，此时需要前端进行一定的逻辑判断。 如果是前后端一体项目，可以参考：[Thymeleaf 标签方言](/plugin/thymeleaf-extend)，如果是前后端分离项目，则： -1. 在登录时，把当前账号拥有的所有权限码一次性返回给前端 -2. 前端将权限码集合保存在`localStorage`或其它全局状态管理对象中 -3. 在需要权限控制的按钮上，使用js进行逻辑判断，例如在`vue`框架中我们可以使用如下写法： +1. 在登录时，把当前账号拥有的所有权限码一次性返回给前端。 +2. 前端将权限码集合保存在`localStorage`或其它全局状态管理对象中。 +3. 在需要权限控制的按钮上，使用 js 进行逻辑判断，例如在`Vue`框架中我们可以使用如下写法： ``` js ``` -其中：`arr`是当前用户拥有的权限码数组，`user:delete`是显示按钮需要拥有的权限码，`删除按钮`是用户拥有权限码才可以看到的内容 +其中：`arr`是当前用户拥有的权限码数组，`user:delete`是显示按钮需要拥有的权限码，`删除按钮`是用户拥有权限码才可以看到的内容。 -注意：以上写法只为提供一个参考示例，不同框架有不同写法，开发者可根据项目技术栈灵活封装进行调用 +注意：以上写法只为提供一个参考示例，不同框架有不同写法，大家可根据项目技术栈灵活封装进行调用。 ### 前端有了鉴权后端还需要鉴权吗？ diff --git a/sa-token-doc/doc/use/login-auth.md b/sa-token-doc/doc/use/login-auth.md index a300a780..e67c636a 100644 --- a/sa-token-doc/doc/use/login-auth.md +++ b/sa-token-doc/doc/use/login-auth.md @@ -2,23 +2,74 @@ --- -### 核心思想 +### 设计思路 -所谓登录认证，说白了就是限制某些API接口必须登录后才能访问（例：查询我的账号资料）
-那么如何判断一个会话是否登录？框架会在登录成功后给你做个标记，每次登录认证时校验这个标记，有标记者视为已登录，无标记者视为未登录！ +对于一些登录之后才能访问的接口（例如：查询我的账号资料），我们通常的做法是增加一层接口校验： + +- 如果校验通过，则：正常返回数据。 +- 如果校验未通过，则：抛出异常，告知其需要先进行登录。 + +那么，判断会话是否登录的依据是什么？我们先来简单分析一下登录访问流程： + +1. 用户提交 `name` + `password` 参数，调用登录接口。 +2. 登录成功，返回这个用户的 Token 会话凭证。 +3. 用户后续的每次请求，都携带上这个 Token。 +4. 服务器根据 Token 判断此会话是否登录成功。 + +所谓登录认证，指的就是服务器校验账号密码，为用户颁发 Token 会话凭证的过程，这个 Token 也是我们后续通过接口校验的关键所在。 ### 登录与注销 -根据以上思路，我们很容易想到以下api： +根据以上思路，我们需要一个会话登录的函数： ``` java -// 标记当前会话登录的账号id -// 建议的参数类型：long | int | String， 不可以传入复杂类型，如：User、Admin等等 +// 会话登录：参数填写要登录的账号id，建议的数据类型：long | int | String， 不可以传入复杂类型，如：User、Admin 等等 StpUtil.login(Object id); +``` +只此一句代码，便可以使会话登录成功，实际上，Sa-Token 在背后做了大量的工作，包括但不限于： + +1. 检查此账号是否已被封禁 +2. 检查此账号是否之前已有登录 +3. 为账号生成 `Token` 凭证与 `Session` 会话 +4. 通知全局侦听器，xx 账号登录成功 +5. 将 `Token` 注入到请求上下文 +6. 等等其它工作…… + +你暂时不需要完整的了解整个登录过程，你只需要记住关键一点：`Sa-Token 为这个账号创建了一个Token凭证，且通过 Cookie 上下文返回给了前端`。 + +所以一般情况下，我们的登录接口代码，会大致类似如下： + +``` java +// 会话登录接口 +@RequestMapping("doLogin") +public SaResult doLogin(String name, String pwd) { + // 第一步：比对前端提交的账号名称、密码 + if("zhang".equals(name) && "123456".equals(pwd)) { + // 第二步：根据账号id，进行登录 + StpUtil.login(10001); + return SaResult.ok("登录成功"); + } + return SaResult.error("登录失败"); +} +``` + +如果你对以上代码阅读没有压力，你可能会注意到略显奇怪的一点：此处仅仅做了会话登录，但并没有主动向前端返回 Token 信息。 +是因为不需要吗？严格来讲是需要的，只不过 `StpUtil.login(id)` 方法利用了 Cookie 自动注入的特性，省略了你手写返回 Token 的代码。 + +如果你对 Cookie 功能还不太了解，也不用担心，我们会在之后的 [ 前后端分离 ] 章节中详细的阐述 Cookie 功能，现在你只需要了解最基本的两点： + +- Cookie 可以从后端控制往浏览器中写入 Token 值。 +- Cookie 会在每次请求时自动提交 Token 值。 + +因此，在 Cookie 功能的加持下，我们可以仅靠 `StpUtil.login(id)` 一句代码就完成登录认证。 + +除了登录方法，我们还需要： + +``` java // 当前会话注销登录 StpUtil.logout(); @@ -26,12 +77,11 @@ StpUtil.logout(); StpUtil.isLogin(); // 检验当前会话是否已经登录, 如果未登录，则抛出异常：`NotLoginException` -StpUtil.checkLogin() +StpUtil.checkLogin(); ``` -##### `NotLoginException`异常对象扩展： -1. 通过 `getLoginType()` 方法获取具体是哪个 `StpLogic` 抛出的异常
-2. 通过 `getType()` 方法获取具体的场景值，详细参考章节：[未登录场景值](/fun/not-login-scene) +异常 `NotLoginException` 代表当前会话暂未登录，可能的原因有很多： +前端没有提交 Token、前端提交的 Token 是无效的、前端提交的 Token 已经过期 …… 等等，可参照此篇：[未登录场景值](/fun/not-login-scene)，了解如何获取未登录的场景值。 ### 会话查询 @@ -54,29 +104,32 @@ StpUtil.getLoginId(T defaultValue); ``` -### 其它API +### Token 查询 ``` java -// 获取指定token对应的账号id，如果未登录，则返回 null -StpUtil.getLoginIdByToken(String tokenValue); +// 获取当前会话的token值 +StpUtil.getTokenValue(); // 获取当前`StpLogic`的token名称 StpUtil.getTokenName(); -// 获取当前会话的token值 -StpUtil.getTokenValue(); +// 获取指定token对应的账号id，如果未登录，则返回 null +StpUtil.getLoginIdByToken(String tokenValue); + +// 获取当前会话剩余有效期（单位：s，返回-1代表永久有效） +StpUtil.getTokenTimeout(); // 获取当前会话的token信息参数 StpUtil.getTokenInfo(); ``` +有关`TokenInfo`参数详解，请参考：[TokenInfo参数详解](/fun/token-info) + ### 来个小测试，加深一下理解 新建 `LoginController`，复制以下代码 ``` java /** * 登录测试 - * @author kong - * */ @RestController @RequestMapping("/acc/") @@ -115,7 +168,5 @@ public class LoginController { } ``` -> 有关`TokenInfo`参数详解，请参考：[TokenInfo参数详解](/fun/token-info) -