diff --git a/sa-token-doc/doc/_sidebar.md b/sa-token-doc/doc/_sidebar.md index 2a2121c9..1823a91f 100644 --- a/sa-token-doc/doc/_sidebar.md +++ b/sa-token-doc/doc/_sidebar.md @@ -69,6 +69,7 @@ - [和 jwt 集成](/plugin/jwt-extend) - [和 Dubbo 集成](/plugin/dubbo-extend) - [Sa-Token 插件开发指南](/fun/plugin-dev) + - [自定义 SaTokenContext 指南](/fun/sa-token-context) - **API手册** - [StpUtil-鉴权工具类](/api/stp-util) @@ -100,7 +101,6 @@ - [参考：把权限放在缓存里](/fun/jur-cache) - [解决跨域问题](/fun/cors-filter) - [技术选型：SSO 与 OAuth2 对比](/fun/sso-vs-oauth2) - - [自定义 SaTokenContext 指南](/fun/sa-token-context) - [框架源码所有技术栈](/fun/tech-stack) - [issue 提问模板](/fun/issue-template) - [为Sa-Token贡献代码](/fun/git-pr) diff --git a/sa-token-doc/doc/fun/sa-token-context.md b/sa-token-doc/doc/fun/sa-token-context.md index 761650d6..a0dd586c 100644 --- a/sa-token-doc/doc/fun/sa-token-context.md +++ b/sa-token-doc/doc/fun/sa-token-context.md @@ -14,7 +14,7 @@ 解决这个问题的关键就在于 `SaTokenContext` 接口，此接口的作用是屏蔽掉不同 Web 框架之间的差异，提供统一的调用API： -![sa-token-context](https://oss.dev33.cn/sa-token/doc/sa-token-context.png 's-w') +![sa-token-context](https://oss.dev33.cn/sa-token/doc/sa-token-context.svg 's-w') SaTokenContext只是一个接口，没有工作能力，这也就意味着 SaTokenContext 接口的实现是必须的。 diff --git a/sa-token-doc/doc/up/global-listener.md b/sa-token-doc/doc/up/global-listener.md index fc17ce9f..1e202cfd 100644 --- a/sa-token-doc/doc/up/global-listener.md +++ b/sa-token-doc/doc/up/global-listener.md @@ -1,15 +1,26 @@ # 全局侦听器 -接口`SaTokenListener`是Sa-Token的全局侦听器，通过实现此接口，你可以在用户登陆、退出、被踢下线等关键性操作时进行一些AOP操作。 - -框架对此侦听器的默认实现是log日志输出，你可以通过配置`sa-token.is-log=true`开启。 - -下面我们演示一下如何自定义侦听器的实现： - --- +### 1、工作原理 -### 自定义侦听器实现 +Sa-Token 提供一种侦听器机制，通过注册侦听器，你可以订阅框架的一些关键性事件，例如：用户登录、退出、被踢下线等。 + +事件触发流程大致如下： + +![sa-token-listener](https://oss.dev33.cn/sa-token/doc/sa-token-listener.svg 's-w') + +框架默认内置了侦听器 `SaTokenListenerForConsolePrint` 实现：[代码参考](https://gitee.com/dromara/sa-token/blob/master/sa-token-core/src/main/java/cn/dev33/satoken/listener/SaTokenListenerForConsolePrint.java) +，功能是控制台 log 打印输出，你可以通过配置`sa-token.is-log=true`开启。 + +要注册自定义的侦听器也非常简单： +1. 新建类实现 `SaTokenListener` 接口。 +2. 将实现类注册到 `SaTokenEventCenter` 事件发布中心。 + + +### 2、自定义侦听器实现 + +##### 2.1、新建实现类： 新建`MySaTokenListener.java`，继承`SaTokenListener`接口，并添加上注解`@Component`，保证此类被`SpringBoot`扫描到： @@ -23,51 +34,161 @@ public class MySaTokenListener implements SaTokenListener { /** 每次登录时触发 */ @Override public void doLogin(String loginType, Object loginId, String tokenValue, SaLoginModel loginModel) { - // ... + System.out.println("---------- 自定义侦听器实现 doLogin"); } /** 每次注销时触发 */ @Override public void doLogout(String loginType, Object loginId, String tokenValue) { - // ... + System.out.println("---------- 自定义侦听器实现 doLogout"); } /** 每次被踢下线时触发 */ @Override public void doKickout(String loginType, Object loginId, String tokenValue) { - // ... + System.out.println("---------- 自定义侦听器实现 doKickout"); } /** 每次被顶下线时触发 */ @Override public void doReplaced(String loginType, Object loginId, String tokenValue) { - // ... + System.out.println("---------- 自定义侦听器实现 doReplaced"); } /** 每次被封禁时触发 */ @Override public void doDisable(String loginType, Object loginId, long disableTime) { - // ... + System.out.println("---------- 自定义侦听器实现 doDisable"); } /** 每次被解封时触发 */ @Override public void doUntieDisable(String loginType, Object loginId) { - // ... + System.out.println("---------- 自定义侦听器实现 doUntieDisable"); } /** 每次创建Session时触发 */ @Override public void doCreateSession(String id) { - // ... + System.out.println("---------- 自定义侦听器实现 doCreateSession"); } /** 每次注销Session时触发 */ @Override public void doLogoutSession(String id) { - // ... + System.out.println("---------- 自定义侦听器实现 doLogoutSession"); } } ``` +##### 2.2、将侦听器注册到事件中心： + +以上代码由于添加了 `@Component` 注解，会被 SpringBoot 扫描并自动注册到事件中心，此时我们无需手动注册。 + +如果我们没有添加 `@Component` 注解或者项目属于非 IOC 自动注入环境，则需要我们手动将这个侦听器注册到事件中心： + +``` java +// 将侦听器注册到事件发布中心 +SaTokenEventCenter.registerListener(new MySaTokenListener()); +``` + +事件中心的其它一些常用方法： + +``` java +// 获取已注册的所有侦听器 +SaTokenEventCenter.getListenerList(); + +// 重置侦听器集合 +SaTokenEventCenter.setListenerList(listenerList); + +// 注册一个侦听器 +SaTokenEventCenter.registerListener(listener); + +// 注册一组侦听器 +SaTokenEventCenter.registerListenerList(listenerList); + +// 移除一个侦听器 +SaTokenEventCenter.removeListener(listener); + +// 移除指定类型的所有侦听器 +SaTokenEventCenter.removeListener(cls); + +// 清空所有已注册的侦听器 +SaTokenEventCenter.clearListener(); + +// 判断是否已经注册了指定侦听器 +SaTokenEventCenter.hasListener(listener); + +// 判断是否已经注册了指定类型的侦听器 +SaTokenEventCenter.hasListener(cls); +``` + +##### 2.3、启动测试： +在 `TestController` 中添加登录测试代码： +``` java +// 测试登录接口 +@RequestMapping("login") +public SaResult login() { + System.out.println("登录前"); + StpUtil.login(10001); + System.out.println("登录后"); + return SaResult.ok(); +} +``` + +启动项目，访问登录接口，观察控制台输出： + +![sa-token-listener-println](https://oss.dev33.cn/sa-token/doc/sa-token-listener-println.png 's-w-sh') + + +### 3、其它注意点 + +##### 3.1、你可以通过继承 `SaTokenListenerForSimple` 快速实现一个侦听器： + +``` java +@Component +public class MySaTokenListener implements SaTokenListenerForSimple { + /* + * SaTokenListenerForSimple 对所有事件提供了空实现，通过继承此类，你只需重写一部分方法即可实现一个可用的侦听器。 + */ + /** 每次登录时触发 */ + @Override + public void doLogin(String loginType, Object loginId, String tokenValue, SaLoginModel loginModel) { + System.out.println("---------- 自定义侦听器实现 doLogin"); + } +} +``` + +##### 3.2、使用匿名内部类的方式注册： +``` java +// 登录时触发 +SaTokenEventCenter.registerListener(new SaTokenListenerForSimple() { + @Override + public void doLogin(String loginType, Object loginId, String tokenValue, SaLoginModel loginModel) { + System.out.println("---------------- doLogin"); + } +}); +``` + +##### 3.3、使用 try-catch 包裹不安全的代码： +如果你认为你的事件处理代码是不安全的（代码可能在运行时抛出异常），你则需要使用 `try-catch` 包裹代码，以防因为抛出异常导致 Sa-Token 的整个登录流程被强制中断。 + +``` java +// 登录时触发 +SaTokenEventCenter.registerListener(new SaTokenListenerForSimple() { + @Override + public void doLogin(String loginType, Object loginId, String tokenValue, SaLoginModel loginModel) { + try { + // 不安全代码需要写在 try-catch 里 + // ...... + } catch (Exception e) { + e.printStackTrace(); + } + } +}); +``` + +##### 3.4、疑问：一个项目可以注册多个侦听器吗？ +可以，多个侦听器间彼此独立，互不影响，按照注册顺序依次接受到事件通知。 +