lsm/sa-token
1
0
Fork 0
mirror of https://gitee.com/dromara/sa-token.git synced 2025-09-19 10:08:07 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

完善 v1.30.0 的文档

Browse Source
This commit is contained in:
click33
2022-05-06 10:31:46 +08:00
parent a30b85fc9f
commit 7e399fb63a
14 changed files with 208 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
sa-token-core/src/main/java/cn/dev33/satoken/exception/SaExceptionCode.java
View File

@@ -8,7 +8,7 @@ package cn.dev33.satoken.exception;
*/
public class SaExceptionCode {
/** 代表未指定异常细分状态码 */
/** 代表这个异常在抛出时未指定异常细分状态码 */
public static final int CODE_UNDEFINED = -1;
}

27
sa-token-demo/sa-token-demo-springboot/pom.xml
View File

@@ -39,26 +39,6 @@
<version>${sa-token-version}</version>
</dependency>
<!-- Sa-Token 整合 Redis (使用jdk默认序列化方式) -->
<!-- <dependency>
<groupId>cn.dev33</groupId>
<artifactId>sa-token-dao-redis</artifactId>
<version>${sa-token-version}</version>
</dependency> -->
<!-- Sa-Token整合 Redis (使用jackson序列化方式) -->
<!-- <dependency>
<groupId>cn.dev33</groupId>
<artifactId>sa-token-dao-redis-jackson</artifactId>
<version>${sa-token-version}</version>
</dependency> -->
<!-- 提供Redis连接池 -->
<!-- <dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-pool2</artifactId>
</dependency> -->
<!-- Sa-Token整合SpringAOP实现注解鉴权 -->
<!-- <dependency>
<groupId>cn.dev33</groupId>
@@ -73,13 +53,6 @@
<optional>true</optional>
</dependency>
<!-- hutool工具类，用来生成雪花算法唯一id -->
<!-- <dependency>
<groupId>cn.hutool</groupId>
<artifactId>hutool-all</artifactId>
<version>5.5.4</version>
</dependency> -->
</dependencies>

1
sa-token-doc/doc/_sidebar.md
View File

@@ -85,6 +85,7 @@
- [Token有效期详解](/fun/token-timeout)
- [Session模型详解](/fun/session-model)
- [TokenInfo参数详解](/fun/token-info)
- [异常细分状态码](/fun/exception-code)
- [解决反向代理 uri 丢失的问题](/fun/curr-domain)
- [参考：把权限放在缓存里](/fun/jur-cache)
- [解决跨域问题](/fun/cors-filter)

107
sa-token-doc/doc/fun/exception-code.md Normal file
View File

@@ -0,0 +1,107 @@
# 异常细分状态码
---
### 获取异常细分状态码
Sa-Token 中的基础异常类是 `SaTokenException`，在此基础上，又针对一些特定场景划分出诸如 `NotLoginException`、`NotPermissionException` 等。
但是框架中异常抛出点远远多于异常种类的划分，比如在 SSO 插件中，[ redirect 重定向地址无效 ] 和 [ ticket 参数值无效 ] 都会导致 SSO 授权的失败，
但是它们抛出的异常都是 `SaSsoException`，如果你需要对这两种异常情形做出不同的处理，仅仅判断异常的 ClassType 显然不够。
为了解决上述需求，Sa-Token 对每个异常抛出点都会指定一个特定的 code 值，就像这样：
``` java
if(SaFoxUtil.isUrl(url) == false) {
throw new SaSsoException("无效redirect：" + url).setCode(SaSsoExceptionCode.CODE_20001);
}
```
就像是打上一个特定的标记，不同异常情形标记的 code 码值也会不同，这就为你精细化异常处理提供了前提。
要在捕获异常时获取这个 code 码也非常简单：
``` java
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(SaTokenException.class)
public SaResult handlerSaTokenException(SaTokenException e) {
// 根据不同异常细分状态码返回不同的提示
if(e.getCode() == 20001) {
return SaResult.error("redirect 重定向 url 是一个无效地址");
}
if(e.getCode() == 20002) {
return SaResult.error("redirect 重定向 url 不在 allowUrl 允许的范围内");
}
if(e.getCode() == 20004) {
return SaResult.error("提供的 ticket 是无效的");
}
// 更多 code 码判断 ...
// 默认的提示
return SaResult.error("服务器繁忙，请稍后重试...");
}
}
```
SaToken 中的所有异常都是继承于 `SaTokenException` 的，也就是说，所有异常你都可以通过 `e.getCode()` 的方式获取对应的异常细分状态码。
### 异常细分状态码-参照表
!> 目前仅对 sso 插件和 jwt 插件做了异常状态码细分，后续版本升级会支持更多模块
**sa-token-code 核心包：**
| code码值 | 含义 |
| :-------- | :-------- |
| -1 | 代表这个异常在抛出时未指定异常细分状态码 |
**sa-token-sso 单点登录相关：**
| code码值 | 含义 |
| :-------- | :-------- |
| 20001 | `redirect` 重定向 url 是一个无效地址 |
| 20002 | `redirect` 重定向 url 不在 allowUrl 允许的范围内 |
| 20003 | 接口调用方提供的 `secretkey` 秘钥无效 |
| 20004 | 提供的 `ticket` 是无效的 |
| 20005 | 在模式三下，sso-client 调用 sso-server 端 校验ticket接口 时，得到的响应是校验失败 |
| 20006 | 在模式三下，sso-client 调用 sso-server 端 单点注销接口 时，得到的响应是注销失败 |
| 20007 | http 请求调用 提供的 `timestamp` 与当前时间的差距超出允许的范围 |
| 20008 | http 请求调用 提供的 `sign` 无效 |
| 20009 | 本地系统没有配置 `secretkey` 字段 |
**sa-token-jwt 插件相关：**
| code码值 | 含义 |
| :-------- | :-------- |
| 40101 | 对 jwt 字符串解析失败 |
| 40102 | 此 jwt 的签名无效 |
| 40103 | 此 jwt 的 `loginType` 字段不符合预期 |
| 40104 | 此 jwt 已超时 |

2
sa-token-doc/doc/more/common-questions.md
View File

@@ -102,7 +102,7 @@ jwt 的招牌便是无须借助服务端完成会话管理，如果集成`jwt`
### 框架抛出的权限不足异常，我想根据自定义提示信息，可以吗？
可以，在全局异常拦截器里捕获`NotPermissionException`，可以通过`getCode()`获取没有通过认证的权限码，可以据此自定义返回信息
可以，在全局异常拦截器里捕获`NotPermissionException`，可以通过`getPermission()`获取没有通过认证的权限码，可以据此自定义返回信息
### 我的项目权限模型不是RBAC模型，很复杂，可以集成吗？

1
sa-token-doc/doc/more/sa-token-donate.md
View File

@@ -19,6 +19,7 @@ Sa-Token 采用 Apache-2.0 开源协议，**承诺框架本身与官网文档永
| 赞助人 | 赞助金额 | 留言 | 时间 |
| :-------- | :-------- | :-------- | :-------- |
| [别处理](https://gitee.com/zshnb) | ¥ 10.0 | 非常好的项目，希望能一直做下去 | 2022-05-01 |
| [李洪星](https://gitee.com/li_hong_xing) | ¥ 10.0 | 解决了很多之前项目中遇到的问题。感谢您的开源项目！ | 2022-04-29 |
| [乡村阿土哥](https://gitee.com/895995040) | ¥ 10.0 | 感谢您的开源项目！ | 2022-04-29 |
| [Horatio201](https://gitee.com/horatio201) | ¥ 20.0 | 太牛了！ | 2022-04-25 |

2
sa-token-doc/doc/more/update-log.md
View File

@@ -24,7 +24,7 @@
- 升级：SpringBoot 相关组件依赖版本升级至 `2.5.12`
- 文档：在线文档所有 `AjaxJson` 改为 `SaResult`
- 文档：“多账号认证” -> 改为 “多账户认证”
- 升级：顶级异常类 `SaTokenException` 增加 code 异常细分状态码。 **[重要]**
- 升级：顶级异常类 `SaTokenException` 增加 code 异常细分状态码。[详见](/fun/exception-code) **[重要]**
- **注意升级：受异常细分状态码影响，`NotPermissionException` 类中 `getCode()` 方法改为 `getPermission()`。** **[不向下兼容]**
- SSO 模块升级：
- 重构：SSO 模块从核心包拆分为独立插件 `sa-token-sso` **[重要]**

5
sa-token-doc/doc/plugin/dao-extend.md
View File

@@ -7,8 +7,9 @@
框架已提供的集成包包括：
- 默认方式：储存在内存中，位于core核心包
- sa-token-dao-redis：Redis集成包，使用jdk默认序列化方式
- sa-token-dao-redis-jackson：Redis集成包，使用jackson序列化方式
- sa-token-dao-redis：Redis集成包，使用 jdk 默认序列化方式
- sa-token-dao-redis-jackson：Redis集成包，使用 jackson 序列化方式
- sa-token-dao-redisx：Redisx 集成包
有关Redis集成，详细参考：[集成Redis](/up/integ-redis)，更多存储方式欢迎提交PR

10
sa-token-doc/doc/sso/sso-questions.md
View File

@@ -34,6 +34,16 @@
解决方案：在 sso-client 也新建上这个类，而且包名需要与 sso-server 端的一致（直接从 sso-server 把实体类复制过来就好了）
### 问：如果 sso-client 端我没有集成 sa-token-sso，如何对接？
需要手动调用 http 请求来对接 sso-server 开放的接口，参考示例：[sa-token-demo-sso3-client-nosdk](https://gitee.com/dromara/sa-token/tree/master/sa-token-demo/sa-token-demo-sso3-client-nosdk)
### 问：如果 sso-client 端不是 java语言，可以对接吗？
可以，只不过有点麻烦，基本思路和上个问题一致，需要手动调用 http 请求来对接 sso-server 开放的接口，参考：
[SSO-Server 认证中心开放接口](/sso/sso-apidoc)
### 还有其它问题？
可以加群反馈一下，比较典型的问题我们解决之后都会提交到此页面方便大家快速排查

13
sa-token-doc/doc/sso/sso-server.md
View File

@@ -17,6 +17,13 @@
<version>${sa.top.version}</version>
</dependency>
<!-- Sa-Token 插件：整合SSO -->
<dependency>
<groupId>cn.dev33</groupId>
<artifactId>sa-token-sso</artifactId>
<version>${sa.top.version}</version>
</dependency>
<!-- Sa-Token 整合 Redis (使用 jackson 序列化方式) -->
<dependency>
<groupId>cn.dev33</groupId>
@@ -42,10 +49,10 @@
</dependency>
```
除了 **sa-token-spring-boot-starter** 以外，其它包都是可选的：
- 在SSO模式三时 Redis 相关包是可选的
除了 `sa-token-spring-boot-starter` 和 `sa-token-sso` 以外，其它包都是可选的：
- 在 SSO 模式三时 Redis 相关包是可选的
- 在前后端分离模式下可以删除 thymeleaf 相关包
- 在不需要SSO模式三单点注销的情况下可以删除 http 工具包
- 在不需要 SSO 模式三单点注销的情况下可以删除 http 工具包
建议先完整测试三种模式之后再对pom依赖进行酌情删减。

6
sa-token-doc/doc/sso/sso-type1.md
View File

@@ -65,6 +65,12 @@ sa-token:
<artifactId>sa-token-spring-boot-starter</artifactId>
<version>${sa-token-version}</version>
</dependency>
<!-- Sa-Token 插件：整合SSO -->
<dependency>
<groupId>cn.dev33</groupId>
<artifactId>sa-token-sso</artifactId>
<version>${sa.top.version}</version>
</dependency>
<!-- Sa-Token 整合redis (使用jackson序列化方式) -->
<dependency>

6
sa-token-doc/doc/sso/sso-type2.md
View File

@@ -65,6 +65,12 @@ sa-token:
<artifactId>sa-token-spring-boot-starter</artifactId>
<version>${sa.top.version}</version>
</dependency>
<!-- Sa-Token 插件：整合SSO -->
<dependency>
<groupId>cn.dev33</groupId>
<artifactId>sa-token-sso</artifactId>
<version>${sa.top.version}</version>
</dependency>
<!-- Sa-Token 整合redis (使用jackson序列化方式) -->
<dependency>

66
sa-token-doc/doc/start/download.md
View File

@@ -7,8 +7,8 @@
<!------------------------------ tabs:start ------------------------------>
<!-- tab:SpringMVC环境 （ServletAPI） -->
如果你使用的框架基于 ServletAPI 构建（ SpringMVC、SpringBoot、Zuul等 ），请引入此包
<!------------- tab:SpringMVC环境 （ServletAPI） ------------->
如果你使用的框架基于 ServletAPI 构建（ SpringMVC、SpringBoot等 ），请引入此包
``` xml
<!-- Sa-Token 权限认证, 在线文档：http://sa-token.dev33.cn/ -->
<dependency>
@@ -18,7 +18,7 @@
</dependency>
```
<!-- tab:WebFlux环境 （Reactor） -->
<!------------- tab:WebFlux环境 （Reactor） ------------->
注：如果你使用的框架基于 Reactor 模型构建（Netty、WebFlux、ShenYu、SC Gateway等），请引入此包
``` xml
<!-- Sa-Token 权限认证（Reactor响应式集成）, 在线文档：http://sa-token.dev33.cn/ -->
@@ -29,7 +29,40 @@
</dependency>
```
<!-- tab:Servlet容器环境 -->
<!------------- tab:Solon 集成 ------------->
参考：[Solon官网](https://solon.noear.org/)
``` xml
<!-- Sa-Token 整合 Solon, 在线文档：http://sa-token.dev33.cn/ -->
<dependency>
<groupId>cn.dev33</groupId>
<artifactId>sa-token-solon-plugin</artifactId>
<version>${sa.top.version}</version>
</dependency>
```
<!------------- tab:JFinal 集成 ------------->
参考：[JFinal官网](https://jfinal.com/)
``` xml
<!-- Sa-Token 整合 JFinal, 在线文档：http://sa-token.dev33.cn/ -->
<dependency>
<groupId>cn.dev33</groupId>
<artifactId>sa-token-jfinal-plugin</artifactId>
<version>${sa.top.version}</version>
</dependency>
```
<!------------- tab:Jboot 集成 ------------->
参考：[Jboot官网](http://www.jboot.com.cn/)
``` xml
<!-- Sa-Token 整合 Jboot, 在线文档：http://sa-token.dev33.cn/ -->
<dependency>
<groupId>cn.dev33</groupId>
<artifactId>sa-token-jboot-plugin</artifactId>
<version>${sa.top.version}</version>
</dependency>
```
<!------------- tab:裸Servlet容器环境 ------------->
注：如果你的项目没有使用Spring，但是Web框架是基于 ServletAPI 规范的，可以引入此包
``` xml
<!-- Sa-Token 权限认证（ServletAPI规范）, 在线文档：http://sa-token.dev33.cn/ -->
@@ -41,7 +74,7 @@
```
引入此依赖需要自定义 SaTokenContext 实现，参考：[自定义 SaTokenContext 指南](/fun/sa-token-context)
<!-- tab:其它 -->
<!------------- tab:其它 ------------->
注：如果你的项目既没有使用 SpringMVC、WebFlux，也不是基于 ServletAPI 规范，那么可以引入core核心包
``` xml
<!-- Sa-Token 权限认证（core核心包）, 在线文档：http://sa-token.dev33.cn/ -->
@@ -52,6 +85,7 @@
</dependency>
```
引入此依赖需要自定义 SaTokenContext 实现，参考：[自定义 SaTokenContext 指南](/fun/sa-token-context)
<!---------------------------- tabs:end ------------------------------>
@@ -61,18 +95,37 @@
``` xml
implementation 'cn.dev33:sa-token-spring-boot-starter:${sa.top.version}'
```
<!-- tab:WebFlux环境 （Reactor） -->
``` xml
implementation 'cn.dev33:sa-token-reactor-spring-boot-starter:${sa.top.version}'
```
<!-- tab:Servlet容器环境 -->
<!-- tab:Solon 集成 -->
``` xml
implementation 'cn.dev33:sa-token-solon-plugin:${sa.top.version}'
```
<!-- tab:JFinal 集成 -->
``` xml
implementation 'cn.dev33:sa-token-jfinal-plugin:${sa.top.version}'
```
<!-- tab:Jboot 集成 -->
``` xml
implementation 'cn.dev33:sa-token-jboot-plugin:${sa.top.version}'
```
<!-- tab:裸Servlet容器环境 -->
``` xml
implementation 'cn.dev33:sa-token-servlet:${sa.top.version}'
```
<!-- tab:其它 -->
``` xml
implementation 'cn.dev33:sa-token-core:${sa.top.version}'
```
<!-- tabs:end -->
注：JDK版本：`v1.8+`，SpringBoot：`建议2.0以上`
@@ -108,6 +161,7 @@ implementation 'cn.dev33:sa-token-core:${sa.top.version}'
├── sa-token-jwt // [插件] Sa-Token 整合 jwt 登录认证
├── sa-token-demo // [示例] Sa-Token 示例合集
├── sa-token-demo-springboot // [示例] Sa-Token 整合 SpringBoot
├── sa-token-demo-springboot-redis // [示例] Sa-Token 整合 SpringBoot
├── sa-token-demo-webflux // [示例] Sa-Token 整合 WebFlux
├── sa-token-demo-jwt // [示例] Sa-Token 集成 jwt
├── sa-token-demo-solon // [示例] Sa-Token 集成 Solon

2
sa-token-doc/doc/up/global-listener.md
View File

@@ -22,7 +22,7 @@ public class MySaTokenListener implements SaTokenListener {
/** 每次登录时触发 */
@Override
public void doLogin(String loginType, Object loginId, SaLoginModel loginModel) {
public void doLogin(String loginType, Object loginId, String tokenValue, SaLoginModel loginModel) {
// ...
}