diff --git a/README.md b/README.md index 9c3dd7c2..d68ca78b 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ logo

Sa-Token v1.25.0

-

一个轻量级 java 权限认证框架,让鉴权变得简单、优雅!

+

一个轻量级 Java 权限认证框架,让鉴权变得简单、优雅!

@@ -15,20 +15,76 @@ --- - -## 在线资料 - +## 前言: - [在线文档:http://sa-token.dev33.cn/](http://sa-token.dev33.cn/) -- [需求提交:我们深知一个优秀的项目需要海纳百川,点我在线提交需求](http://sa-app.dev33.cn/wall.html?name=sa-token) - -- [开源不易,求鼓励,点个star吧 !](###) - +- 我们将会尽力讲解每个功能的设计原因、应用场景,用心阅读文档,你学习到的将不止是 `Sa-Token` 框架本身,更是绝大多数场景下权限设计的最佳实践。 ## Sa-Token 介绍 -Sa-Token是一个轻量级Java权限认证框架,主要解决:登录认证、权限认证、Session会话、单点登录、OAuth2.0、微服务网关鉴权 等一系列权限相关问题 -框架集成简单、开箱即用、API设计清爽,通过Sa-Token,你将以一种极其简单的方式实现系统的权限认证部分 +**Sa-Token** 是一个轻量级 Java 权限认证框架,主要解决:**`登录认证`**、**`权限认证`**、**`Session会话`**、**`单点登录`**、**`OAuth2.0`**、**`微服务网关鉴权`** +等一系列权限相关问题。 + +Sa-Token 的 API 设计非常简单,有多简单呢?以登录认证为例,你只需要: + + +``` java +// 在登录时写入当前会话的账号id +StpUtil.login(10001); + +// 然后在任意需要校验登录处调用以下API +// 如果当前会话未登录,这句代码会抛出 `NotLoginException`异常 +StpUtil.checkLogin(); +``` + +至此,我们已经借助 Sa-Token 完成登录授权! + +此时的你小脑袋可能飘满了问号,就这么简单?自定义 Realm 呢?全局过滤器呢?我不用写各种配置文件吗? + +事实上在此我可以负责的告诉你,在 Sa-Token 中,登录授权就是如此的简单,不需要什么全局过滤器,不需要各种乱七八糟的配置!只需要这一行简单的API调用,即可完成会话的登录授权! + +当你受够 Shiro、SpringSecurity 等框架的三拜九叩之后,你就会明白,相对于这些传统老牌框架,Sa-Token 的 API 设计是多么的简单、优雅! + +权限认证示例(只有具备 `user:add` 权限的会话才可以进入请求) +``` java +@SaCheckPermission("user:add") +@RequestMapping("/user/insert") +public String insert(SysUser user) { + // ... + return "用户增加"; +} +``` + +将某个账号踢下线(待到对方再次访问系统时会抛出`NotLoginException`异常) +``` java +// 使账号id为 10001 的会话强制注销登录 +StpUtil.logoutByLoginId(10001); +``` + +除了以上的示例,Sa-Token还可以一行代码完成以下功能: +``` java +StpUtil.login(10001); // 标记当前会话登录的账号id +StpUtil.getLoginId(); // 获取当前会话登录的账号id +StpUtil.isLogin(); // 获取当前会话是否已经登录, 返回true或false +StpUtil.logout(); // 当前会话注销登录 +StpUtil.logoutByLoginId(10001); // 让账号为10001的会话注销登录(踢人下线) +StpUtil.hasRole("super-admin"); // 查询当前账号是否含有指定角色标识, 返回true或false +StpUtil.hasPermission("user:add"); // 查询当前账号是否含有指定权限, 返回true或false +StpUtil.getSession(); // 获取当前账号id的Session +StpUtil.getSessionByLoginId(10001); // 获取账号id为10001的Session +StpUtil.getTokenValueByLoginId(10001); // 获取账号id为10001的token令牌值 +StpUtil.login(10001, "PC"); // 指定设备标识登录,常用于“同端互斥登录” +StpUtil.logoutByLoginId(10001, "PC"); // 指定设备标识进行强制注销 (不同端不受影响) +StpUtil.openSafe(120); // 在当前会话开启二级认证,有效期为120秒 +StpUtil.checkSafe(); // 校验当前会话是否处于二级认证有效期内,校验失败会抛出异常 +StpUtil.switchTo(10044); // 将当前会话身份临时切换为其它账号 +``` + +即使不运行测试,相信您也能意会到绝大多数 API 的用法。 + + + +## Sa-Token 功能一览 - **登录认证** —— 单端登录、多端登录、同端互斥登录、七天内免登录 - **权限认证** —— 权限认证、角色认证、会话二级认证 @@ -59,47 +115,6 @@ Sa-Token是一个轻量级Java权限认证框架,主要解决:登录认证 - **开箱即用** —— 提供SpringMVC、WebFlux等常见web框架starter集成包,真正的开箱即用 - **更多功能正在集成中...** —— 如有您有好想法或者建议,欢迎加群交流 -##### Sa-Token 源码模块一览 -``` js -── sa-token - ├── sa-token-core // [核心] Sa-Token 核心模块 - ├── sa-token-starter // [整合] Sa-Token 与其它框架整合 - ├── sa-token-servlet // [整合] Sa-Token 整合 Servlet容器实现类包 - ├── sa-token-spring-boot-starter // [整合] Sa-Token 整合 SpringBoot 快速集成 - ├── sa-token-reactor-spring-boot-starter // [整合] Sa-Token 整合 Reactor响应式编程 快速集成 - ├── sa-token-solon-plugin // [整合] Sa-Token 整合 Solon 快速集成 - ├── sa-token-plugin // [插件] Sa-Token 插件合集 - ├── sa-token-dao-redis // [插件] Sa-Token 整合 Redis (使用jdk默认序列化方式) - ├── sa-token-dao-redis-jackson // [插件] Sa-Token 整合 Redis (使用jackson序列化方式) - ├── sa-token-spring-aop // [插件] Sa-Token 整合 SpringAOP 注解鉴权 - ├── sa-token-temp-jwt // [插件] Sa-Token 整合 jwt 临时令牌鉴权 - ├── sa-token-quick-login // [插件] Sa-Token 快速注入登录页插件 - ├── sa-token-alone-redis // [插件] Sa-Token 独立Redis插件,实现[权限缓存与业务缓存分离] - ├── sa-token-oauth2 // [插件] Sa-Token 实现 OAuth2.0 模块 - ├── sa-token-demo // [示例] Sa-Token 示例合集 - ├── sa-token-demo-springboot // [示例] Sa-Token 整合 SpringBoot - ├── sa-token-demo-webflux // [示例] Sa-Token 整合 WebFlux - ├── sa-token-demo-jwt // [示例] Sa-Token 集成 jwt - ├── sa-token-demo-solon // [示例] Sa-Token 集成 Solon - ├── sa-token-demo-quick-login // [示例] Sa-Token 集成 quick-login 模块 - ├── sa-token-demo-alone-redis // [示例] Sa-Token 集成 alone-redis 模块 - ├── sa-token-demo-sso1 // [示例] Sa-Token 集成 SSO单点登录-模式一 - ├── sa-token-demo-sso2-server // [示例] Sa-Token 集成 SSO单点登录-模式二 认证中心 - ├── sa-token-demo-sso2-client // [示例] Sa-Token 集成 SSO单点登录-模式二 应用端 - ├── sa-token-demo-sso3-server // [示例] Sa-Token 集成 SSO单点登录-模式三 认证中心 - ├── sa-token-demo-sso3-client // [示例] Sa-Token 集成 SSO单点登录-模式三 应用端 - ├── sa-token-demo-oauth2-server // [示例] Sa-Token 集成 OAuth2.0 (服务端) - ├── sa-token-demo-oauth2-client // [示例] Sa-Token 集成 OAuth2.0 (客户端) - ├── sa-token-doc // [文档] Sa-Token 开发文档 - ├──pom.xml // [依赖] 顶级pom文件 -``` - -##### Sa-Token 功能结构图 -![sa-token-js](https://color-test.oss-cn-qingdao.aliyuncs.com/sa-token/x/sa-token-js3.png 's-w') - -##### Sa-Token 认证流程图 -![sa-token-rz](https://color-test.oss-cn-qingdao.aliyuncs.com/sa-token/x/sa-token-rz2.png 's-w') - ## Sa-Token-SSO 单点登录 对于单点登录,网上教程大多以CAS模式为主,其实对于不同的系统架构,实现单点登录的步骤也大为不同,Sa-Token由简入难将其划分为三种模式: @@ -137,61 +152,11 @@ Sa-OAuth2 模块基于 [RFC-6749 标准](https://tools.ietf.org/html/rfc6749) 详细参考文档:[http://sa-token.dev33.cn/doc/index.html#/oauth2/readme](http://sa-token.dev33.cn/doc/index.html#/oauth2/readme) -## 代码示例 -Sa-Token的API调用非常简单,有多简单呢?以登录验证为例,你只需要: +## Sa-Token 功能结构图 +![sa-token-js](https://color-test.oss-cn-qingdao.aliyuncs.com/sa-token/x/sa-token-js3.png 's-w') -``` java -// 在登录时写入当前会话的账号id -StpUtil.login(10001); - -// 然后在任意需要校验登录处调用以下API -// 如果当前会话未登录,这句代码会抛出 `NotLoginException`异常 -StpUtil.checkLogin(); -``` -至此,我们已经借助Sa-Token框架完成登录授权! - -此时的你小脑袋可能飘满了问号,就这么简单?自定义Realm呢?全局过滤器呢?我不用写各种配置文件吗? - -事实上在此我可以负责的告诉你,在Sa-Token中,登录授权就是如此的简单,不需要什么全局过滤器,不需要各种乱七八糟的配置!只需要这一行简单的API调用,即可完成会话的登录授权! - -当你受够Shiro、Spring Security等框架的三拜九叩之后,你就会明白,相对于这些传统老牌框架,Sa-Token的API设计是多么的清爽! - -权限认证示例 (只有具有`user:add`权限的会话才可以进入请求) -``` java -@SaCheckPermission("user:add") -@RequestMapping("/user/insert") -public String insert(SysUser user) { - // ... - return "用户增加"; -} -``` - -将某个账号踢下线 (待到对方再次访问系统时会抛出`NotLoginException`异常) -``` java -// 使账号id为10001的会话注销登录 -StpUtil.logoutByLoginId(10001); -``` - -除了以上的示例,Sa-Token还可以一行代码完成以下功能: -``` java -StpUtil.login(10001); // 标记当前会话登录的账号id -StpUtil.getLoginId(); // 获取当前会话登录的账号id -StpUtil.isLogin(); // 获取当前会话是否已经登录, 返回true或false -StpUtil.logout(); // 当前会话注销登录 -StpUtil.logoutByLoginId(10001); // 让账号为10001的会话注销登录(踢人下线) -StpUtil.hasRole("super-admin"); // 查询当前账号是否含有指定角色标识, 返回true或false -StpUtil.hasPermission("user:add"); // 查询当前账号是否含有指定权限, 返回true或false -StpUtil.getSession(); // 获取当前账号id的Session -StpUtil.getSessionByLoginId(10001); // 获取账号id为10001的Session -StpUtil.getTokenValueByLoginId(10001); // 获取账号id为10001的token令牌值 -StpUtil.login(10001, "PC"); // 指定设备标识登录 -StpUtil.logoutByLoginId(10001, "PC"); // 指定设备标识进行强制注销 (不同端不受影响) -StpUtil.openSafe(120); // 在当前会话开启二级认证,有效期为120秒 -StpUtil.checkSafe(); // 校验当前会话是否处于二级认证有效期内,校验失败会抛出异常 -StpUtil.switchTo(10044); // 将当前会话身份临时切换为其它账号 -``` -Sa-Token API 众多,请恕此处无法为您逐一展示,更多示例请戳官方在线文档 +![sa-token-rz](https://color-test.oss-cn-qingdao.aliyuncs.com/sa-token/x/sa-token-rz2.png 's-w') ## Star 趋势 diff --git a/sa-token-doc/doc/README.md b/sa-token-doc/doc/README.md index 3971ee20..6fc6de4e 100644 --- a/sa-token-doc/doc/README.md +++ b/sa-token-doc/doc/README.md @@ -2,7 +2,7 @@ logo

Sa-Token v1.25.0

-
一个轻量级 java 权限认证框架,让鉴权变得简单、优雅!
+
一个轻量级 Java 权限认证框架,让鉴权变得简单、优雅!

@@ -27,7 +27,7 @@ -Sa-Token 的 API 调用非常简单,有多简单呢?以登录认证为例,你只需要: +Sa-Token 的 API 设计非常简单,有多简单呢?以登录认证为例,你只需要: ``` java // 在登录时写入当前会话的账号id