mirror of
https://gitee.com/dromara/sa-token.git
synced 2024-12-02 03:47:50 +08:00
优化 Readme
This commit is contained in:
click33
parent
bcc1e0cc93
commit
be51ff27a1
173
README.md
173
README.md
@ -2,7 +2,7 @@
|
||||
<img alt="logo" src="https://gitee.com/dromara/sa-token/raw/master/sa-token-doc/doc/logo.png" width="150" height="150">
|
||||
</p>
|
||||
<h1 align="center" style="margin: 30px 0 30px; font-weight: bold;">Sa-Token v1.25.0</h1>
|
||||
<h4 align="center">一个轻量级 java 权限认证框架，让鉴权变得简单、优雅！</h4>
|
||||
<h4 align="center">一个轻量级 Java 权限认证框架，让鉴权变得简单、优雅！</h4>
|
||||
<p align="center">
|
||||
<a href="https://gitee.com/dromara/sa-token/stargazers"><img src="https://gitee.com/dromara/sa-token/badge/star.svg"></a>
|
||||
<a href="https://gitee.com/dromara/sa-token/members"><img src="https://gitee.com/dromara/sa-token/badge/fork.svg"></a>
|
||||
@ -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 认证流程图
|
||||
|
||||
|
||||
|
||||
## 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 功能结构图
|
||||
|
||||
|
||||
``` 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 众多，请恕此处无法为您逐一展示，更多示例请戳官方在线文档
|
||||
|
||||
|
||||
|
||||
## Star 趋势
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
<img alt="logo" src="https://gitee.com/dromara/sa-token/raw/master/sa-token-doc/doc/logo.png" width="150" height="150">
|
||||
</p>
|
||||
<h1 align="center" style="margin: 30px 0 30px; font-weight: bold;">Sa-Token v1.25.0</h1>
|
||||
<h5 align="center">一个轻量级 java 权限认证框架，让鉴权变得简单、优雅！</h5>
|
||||
<h5 align="center">一个轻量级 Java 权限认证框架，让鉴权变得简单、优雅！</h5>
|
||||
<p align="center">
|
||||
<a href="https://gitee.com/dromara/sa-token/stargazers"><img src="https://gitee.com/dromara/sa-token/badge/star.svg"></a>
|
||||
<a href="https://gitee.com/dromara/sa-token/members"><img src="https://gitee.com/dromara/sa-token/badge/fork.svg"></a>
|
||||
@ -27,7 +27,7 @@
|
||||
|
||||
<!-- 框架集成简单、开箱即用、API设计清爽，通过Sa-Token，你将以一种极其简单的方式实现系统的权限认证部分 -->
|
||||
|
||||
Sa-Token 的 API 调用非常简单，有多简单呢？以登录认证为例，你只需要：
|
||||
Sa-Token 的 API 设计非常简单，有多简单呢？以登录认证为例，你只需要：
|
||||
|
||||
``` java
|
||||
// 在登录时写入当前会话的账号id
|
||||
|
||||
Loading…
Reference in New Issue
Block a user