优化注释和文档

2025-09-19 01:58:05 +08:00 · 2021-09-29 23:43:01 +08:00
parent 713e11482c
commit b7dba13cab
9 changed files with 154 additions and 160 deletions
--- a/sa-token-core/src/main/java/cn/dev33/satoken/action/SaTokenAction.java
+++ b/sa-token-core/src/main/java/cn/dev33/satoken/action/SaTokenAction.java
@@ -7,9 +7,9 @@ import java.util.List;
 import cn.dev33.satoken.session.SaSession;

 /**
- * Sa-Token 逻辑代理接口 
+ * <h1> v1.27+ 此接口已废弃，目前版本暂时向下兼容，请及时更换为 SaStrategy </h1>
+ * <p>Sa-Token 逻辑代理接口 </p> 
 * <p>此接口将会代理框架内部的一些关键性逻辑，方便开发者进行按需重写</p> 
- * <p> v1.27+ 此接口已废弃，目前版本暂时向下兼容，请更换为 SaStrategy 
 * @author kong
 *
 */
--- a/sa-token-core/src/main/java/cn/dev33/satoken/action/SaTokenActionDefaultImpl.java
+++ b/sa-token-core/src/main/java/cn/dev33/satoken/action/SaTokenActionDefaultImpl.java
@@ -17,8 +17,8 @@ import cn.dev33.satoken.util.SaFoxUtil;
 import cn.dev33.satoken.util.SaTokenConsts;

 /**
- * Sa-Token 逻辑代理接口 [默认实现类] 
- * <p> v1.27+ 此接口已废弃，目前版本暂时向下兼容，请更换为 SaStrategy 
+ * <h1> v1.27+ 此接口已废弃，目前版本暂时向下兼容，请及时更换为 SaStrategy </h1>
+ * <p> Sa-Token 逻辑代理接口 [默认实现类]  </p> 
 * @author kong
 *
 */
--- a/sa-token-core/src/main/java/cn/dev33/satoken/annotation/SaCheckBasic.java
+++ b/sa-token-core/src/main/java/cn/dev33/satoken/annotation/SaCheckBasic.java
@@ -24,7 +24,7 @@ public @interface SaCheckBasic {
    String realm() default SaBasicTemplate.DEFAULT_REALM;

    /**
-     * 需要校验的账号密码 
+     * 需要校验的账号密码，格式形如 sa:123456 
     * @return see note 
     */
    String account() default "";
--- a/sa-token-core/src/main/java/cn/dev33/satoken/config/SaSsoConfig.java
+++ b/sa-token-core/src/main/java/cn/dev33/satoken/config/SaSsoConfig.java
@@ -10,7 +10,7 @@ import cn.dev33.satoken.util.SaFoxUtil;
 import cn.dev33.satoken.util.SaResult;

 /**
- * Sa-Token-SSO 单点登录模块 配置Model
+ * Sa-Token SSO 单点登录模块 配置类 Model 
 * @author kong
 *
 */
@@ -18,8 +18,11 @@ public class SaSsoConfig implements Serializable {

 	private static final long serialVersionUID = -6541180061782004705L;

+	
+	// ----------------- Server端相关配置 
+	
 	/**
-	 * Ticket有效期 (单位: 秒)
+	 * Ticket有效期 (单位: 秒) 
 	 */
 	public long ticketTimeout = 60 * 5;
 	
@@ -27,48 +30,77 @@ public class SaSsoConfig implements Serializable {
 	 * 所有允许的授权回调地址，多个用逗号隔开 (不在此列表中的URL将禁止下放ticket) 
 	 */
 	public String allowUrl = "*";
+
+	/**
+	 * 是否打开单点注销功能 
+	 */
+	public Boolean isSlo = true; 
 	
 	/**
-	 * 接口调用秘钥 (用于SSO模式三单点注销的接口通信身份校验)
+	 * 是否打开模式三（此值为 true 时将使用 http 请求：校验ticket值、单点注销、获取userinfo） 
+	 */
+	public Boolean isHttp = false; 
+
+	/**
+	 * 接口调用秘钥 (用于SSO模式三单点注销的接口通信身份校验) 
 	 */
 	public String secretkey;
+
 	
+	// ----------------- Client端相关配置 
+
 	/**
-	 * SSO-Server端 单点登录地址
+	 * 配置 Server 端单点登录授权地址 
 	 */
 	public String authUrl;

 	/**
-	 * SSO-Server端 Ticket校验地址
+	 * 是否打开单点注销功能 
+	 */
+	// public Boolean isSlo = true;  // 同上 
+
+	/**
+	 * 是否打开模式三（此值为 true 时将使用 http 请求：校验ticket值、单点注销、获取userinfo） 
+	 */
+	// public Boolean isHttp = false;  // 同上 
+
+	/**
+	 * 接口调用秘钥 (用于SSO模式三单点注销的接口通信身份校验) 
+	 */
+	// public String secretkey;  // 同上 
+
+	/**
+	 * 配置 Server 端的 ticket 校验地址 
 	 */
 	public String checkTicketUrl;

 	/**
-	 * SSO-Server端 单点注销地址 
+	 * 配置 Server 端查询 userinfo 地址 
+	 */
+	public String userinfoUrl;
+	
+	/**
+	 * 配置 Server 端单点注销地址 
 	 */
 	public String sloUrl;

 	/**
-	 * SSO-Client端 当前Client端的单点注销回调URL （为空时自动获取） 
+	 * 配置当前 Client 端的单点注销回调URL （为空时自动获取） 
 	 */
 	public String ssoLogoutCall;

-	/**
-	 * SSO-Server端 账号资料查询地址 
-	 */
-	public String userinfoUrl;



 	/**
-	 * @return Ticket有效期 (单位: 秒) 
+	 * @return Ticket有效期 (单位: 秒)  
 	 */
 	public long getTicketTimeout() {
 		return ticketTimeout;
 	}

 	/**
-	 * @param ticketTimeout Ticket有效期 (单位: 秒) 
+	 * @param ticketTimeout Ticket有效期 (单位: 秒)   
 	 * @return 对象自身
 	 */
 	public SaSsoConfig setTicketTimeout(long ticketTimeout) {
@@ -93,14 +125,46 @@ public class SaSsoConfig implements Serializable {
 	}

 	/**
-	 * @return 调用秘钥 (用于SSO模式三单点注销的接口通信身份校验)
+	 * @return 是否打开单点注销功能 
+	 */
+	public Boolean getIsSlo() {
+		return isSlo;
+	}
+
+	/**
+	 * @param isSlo 是否打开单点注销功能 
+	 * @return 对象自身 
+	 */
+	public SaSsoConfig setIsSlo(Boolean isSlo) {
+		this.isSlo = isSlo;
+		return this;
+	}
+
+	/**
+	 * @return isHttp 是否打开模式三（此值为 true 时将使用 http 请求：校验ticket值、单点注销、获取userinfo） 
+	 */
+	public Boolean getIsHttp() {
+		return isHttp;
+	}
+
+	/**
+	 * @param isHttp 是否打开模式三（此值为 true 时将使用 http 请求：校验ticket值、单点注销、获取userinfo） 
+	 * @return 对象自身 
+	 */
+	public SaSsoConfig setIsHttp(Boolean isHttp) {
+		this.isHttp = isHttp;
+		return this;
+	}
+
+	/**
+	 * @return 接口调用秘钥 (用于SSO模式三单点注销的接口通信身份校验)  
 	 */
 	public String getSecretkey() {
 		return secretkey;
 	}

 	/**
-	 * @param secretkey 调用秘钥 (用于SSO模式三单点注销的接口通信身份校验) 
+	 * @param secretkey 接口调用秘钥 (用于SSO模式三单点注销的接口通信身份校验)  
 	 * @return 对象自身
 	 */
 	public SaSsoConfig setSecretkey(String secretkey) {
@@ -109,14 +173,14 @@ public class SaSsoConfig implements Serializable {
 	}

 	/**
-	 * @return SSO-Server端 单点登录地址
+	 * @return 配置的 Server 端单点登录授权地址 
 	 */
 	public String getAuthUrl() {
 		return authUrl;
 	}

 	/**
-	 * @param authUrl SSO-Server端 单点登录地址
+	 * @param authUrl 配置 Server 端单点登录授权地址  
 	 * @return 对象自身
 	 */
 	public SaSsoConfig setAuthUrl(String authUrl) {
@@ -125,14 +189,14 @@ public class SaSsoConfig implements Serializable {
 	}

 	/**
-	 * @return SSO-Server端Ticket校验地址 
+	 * @return 配置的 Server 端的 ticket 校验地址  
 	 */
 	public String getCheckTicketUrl() {
 		return checkTicketUrl;
 	}

 	/**
-	 * @param checkTicketUrl SSO-Server端Ticket校验地址
+	 * @param checkTicketUrl 配置 Server 端的 ticket 校验地址  
 	 * @return 对象自身
 	 */
 	public SaSsoConfig setCheckTicketUrl(String checkTicketUrl) {
@@ -141,14 +205,30 @@ public class SaSsoConfig implements Serializable {
 	}

 	/**
-	 * @return SSO-Server端单点注销地址
+	 * @return 配置的 Server 端查询 userinfo 地址 
+	 */
+	public String getUserinfoUrl() {
+		return userinfoUrl;
+	}
+
+	/**
+	 * @param userinfoUrl 配置 Server 端查询 userinfo 地址 
+	 * @return 对象自身 
+	 */
+	public SaSsoConfig setUserinfoUrl(String userinfoUrl) {
+		this.userinfoUrl = userinfoUrl;
+		return this;
+	}
+
+	/**
+	 * @return 配置 Server 端单点注销地址  
 	 */
 	public String getSloUrl() {
 		return sloUrl;
 	}

 	/**
-	 * @param sloUrl SSO-Server端单点注销地址
+	 * @param sloUrl 配置 Server 端单点注销地址  
 	 * @return 对象自身
 	 */
 	public SaSsoConfig setSloUrl(String sloUrl) {
@@ -157,14 +237,14 @@ public class SaSsoConfig implements Serializable {
 	}

 	/**
-	 * @return SSO-Client端 当前Client端的单点注销回调URL （为空时自动获取） 
+	 * @return 配置当前 Client 端的单点注销回调URL （为空时自动获取） 
 	 */
 	public String getSsoLogoutCall() {
 		return ssoLogoutCall;
 	}

 	/**
-	 * @param ssoLogoutCall SSO-Client端 当前Client端的单点注销回调URL （为空时自动获取） 
+	 * @param ssoLogoutCall 配置当前 Client 端的单点注销回调URL （为空时自动获取）  
 	 * @return 对象自身
 	 */
 	public SaSsoConfig setSsoLogoutCall(String ssoLogoutCall) {
@@ -172,30 +252,14 @@ public class SaSsoConfig implements Serializable {
 		return this;
 	}

-	/**
-	 * @return SSO-Server端 账号资料查询地址 
-	 */
-	public String getUserinfoUrl() {
-		return userinfoUrl;
-	}
-
-	/**
-	 * @param userinfoUrl SSO-Server端 账号资料查询地址 
-	 * @return 对象自身 
-	 */
-	public SaSsoConfig setUserinfoUrl(String userinfoUrl) {
-		this.userinfoUrl = userinfoUrl;
-		return this;
-	}
-	
 	@Override
 	public String toString() {
-		return "SaSsoConfig [ticketTimeout=" + ticketTimeout + ", allowUrl=" + allowUrl + ", secretkey=" + secretkey
-				+ ", authUrl=" + authUrl + ", checkTicketUrl=" + checkTicketUrl + ", sloUrl=" + sloUrl
-				+ ", ssoLogoutCall=" + ssoLogoutCall + ", userinfoUrl=" + userinfoUrl + ", isHttp=" + isHttp + ", isSlo=" + isSlo + "]";
+		return "SaSsoConfig [ticketTimeout=" + ticketTimeout + ", allowUrl=" + allowUrl + ", isSlo=" + isSlo
+				+ ", isHttp=" + isHttp + ", secretkey=" + secretkey + ", authUrl=" + authUrl + ", checkTicketUrl="
+				+ checkTicketUrl + ", userinfoUrl=" + userinfoUrl + ", sloUrl=" + sloUrl + ", ssoLogoutCall="
+				+ ssoLogoutCall + "]";
 	}
 	
-
 	/**
 	 * 以数组形式写入允许的授权回调地址 
 	 * @param url 所有集合 
@@ -206,50 +270,6 @@ public class SaSsoConfig implements Serializable {
 		return this;
 	}

-	// -------------------- SaSsoHandle 相关配置 -------------------- 
-	
-	/**
-	 * 是否使用http请求校验ticket值 
-	 */
-	public Boolean isHttp = false; 
-
-	/**
-	 * 是否打开单点注销 
-	 */
-	public Boolean isSlo = false; 
-	
-
-	/**
-	 * @return isHttp 是否使用http请求校验ticket值 
-	 */
-	public Boolean getIsHttp() {
-		return isHttp;
-	}
-
-	/**
-	 * @param isHttp 是否使用http请求校验ticket值 
-	 * @return 对象自身 
-	 */
-	public SaSsoConfig setIsHttp(Boolean isHttp) {
-		this.isHttp = isHttp;
-		return this;
-	}
-
-	/**
-	 * @return 是否打开单点注销 
-	 */
-	public Boolean getIsSlo() {
-		return isSlo;
-	}
-
-	/**
-	 * @param isSlo 是否打开单点注销 
-	 * @return 对象自身 
-	 */
-	public SaSsoConfig setIsSlo(Boolean isSlo) {
-		this.isSlo = isSlo;
-		return this;
-	}
 	
 	
 	// -------------------- SaSsoHandle 所有回调函数 -------------------- 
@@ -312,4 +332,7 @@ public class SaSsoConfig implements Serializable {
 		return this;
 	}

+	
+
+	
 }
--- a/sa-token-demo/sa-token-demo-springboot/src/main/java/com/pj/SaTokenDemoApplication.java
+++ b/sa-token-demo/sa-token-demo-springboot/src/main/java/com/pj/SaTokenDemoApplication.java
@@ -1,5 +1,7 @@
 package com.pj;

+import cn.dev33.satoken.annotation.SaCheckBasic;
+import cn.dev33.satoken.annotation.SaCheckPermission;
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;

@@ -13,6 +15,8 @@ import cn.dev33.satoken.SaManager;
@SpringBootApplication
 public class SaTokenDemoApplication {

+	@SaCheckPermission
+	@SaCheckBasic
 	public static void main(String[] args) {
 		SpringApplication.run(SaTokenDemoApplication.class, args);
 		System.out.println("\n启动成功：Sa-Token配置如下：" + SaManager.getConfig());
--- a/sa-token-demo/sa-token-demo-springboot/src/main/java/com/pj/test/GlobalException.java
+++ b/sa-token-demo/sa-token-demo-springboot/src/main/java/com/pj/test/GlobalException.java
@@ -1,13 +1,10 @@
 package com.pj.test;

-import java.io.IOException;
-
 import javax.servlet.http.HttpServletRequest;
 import javax.servlet.http.HttpServletResponse;

 import org.springframework.web.bind.annotation.ControllerAdvice;
 import org.springframework.web.bind.annotation.ExceptionHandler;
-import org.springframework.web.bind.annotation.ModelAttribute;
 import org.springframework.web.bind.annotation.ResponseBody;

 import com.pj.util.AjaxJson;
@@ -20,16 +17,9 @@ import cn.dev33.satoken.exception.NotRoleException;
 /**
 * 全局异常处理 
 */
-@ControllerAdvice // 可指定包前缀，比如：(basePackages = "com.pj.admin")
+@ControllerAdvice
 public class GlobalException {

-	// 在当前类每个方法进入之前触发的操作
-	@ModelAttribute
-	public void get(HttpServletRequest request) throws IOException {
-		
-	}
-
-	
 	// 全局异常拦截（拦截项目中的所有异常）
 	@ResponseBody
 	@ExceptionHandler
@@ -45,61 +35,25 @@ public class GlobalException {
 		if (e instanceof NotLoginException) {	// 如果是未登录异常
 			NotLoginException ee = (NotLoginException) e;
 			aj = AjaxJson.getNotLogin().setMsg(ee.getMessage());
-		} else if(e instanceof NotRoleException) {		// 如果是角色异常
+		} 
+		else if(e instanceof NotRoleException) {		// 如果是角色异常
 			NotRoleException ee = (NotRoleException) e;
 			aj = AjaxJson.getNotJur("无此角色：" + ee.getRole());
-		} else if(e instanceof NotPermissionException) {	// 如果是权限异常
+		} 
+		else if(e instanceof NotPermissionException) {	// 如果是权限异常
 			NotPermissionException ee = (NotPermissionException) e;
 			aj = AjaxJson.getNotJur("无此权限：" + ee.getCode());
-		} else if(e instanceof DisableLoginException) {	// 如果是被封禁异常
+		} 
+		else if(e instanceof DisableLoginException) {	// 如果是被封禁异常
 			DisableLoginException ee = (DisableLoginException) e;
 			aj = AjaxJson.getNotJur("账号被封禁：" + ee.getDisableTime() + "秒后解封");
-		} else {	// 普通异常, 输出：500 + 异常信息
+		} 
+		else {	// 普通异常, 输出：500 + 异常信息 
 			aj = AjaxJson.getError(e.getMessage());
 		}
 		
 		// 返回给前端
 		return aj;
-
-		// 输出到客户端 
-//		response.setContentType("application/json; charset=utf-8"); // http说明，我要返回JSON对象
-//		response.getWriter().print(new ObjectMapper().writeValueAsString(aj));
 	}
 	
-	
-
-	// 全局异常拦截（拦截项目中的NotLoginException异常）
-//	@ExceptionHandler(NotLoginException.class)
-//	public AjaxJson handlerNotLoginException(NotLoginException nle, HttpServletRequest request, HttpServletResponse response)
-//			throws Exception {
-//
-//		// 打印堆栈，以供调试
-//		nle.printStackTrace(); 
-//		
-//		// 判断场景值，定制化异常信息 
-//		String message = "";
-//		if(nle.getType().equals(NotLoginException.NOT_TOKEN)) {
-//			message = "未提供token";
-//		}
-//		else if(nle.getType().equals(NotLoginException.INVALID_TOKEN)) {
-//			message = "token无效";
-//		}
-//		else if(nle.getType().equals(NotLoginException.TOKEN_TIMEOUT)) {
-//			message = "token已过期";
-//		}
-//		else if(nle.getType().equals(NotLoginException.BE_REPLACED)) {
-//			message = "token已被顶下线";
-//		}
-//		else if(nle.getType().equals(NotLoginException.KICK_OUT)) {
-//			message = "token已被踢下线";
-//		}
-//		else {
-//			message = "当前会话未登录";
-//		}
-//		
-//		// 返回给前端
-//		return AjaxJson.getError(message);
-//	}
-	
-
 }
--- a/sa-token-doc/doc/index.html
+++ b/sa-token-doc/doc/index.html
@@ -79,6 +79,7 @@
 					errorText: '错误',
 					successText: '复制成功'
 				},
+				topMargin: 90, // 锚点距离顶部的距离 
 				// sidebarDisplayLevel : 1 ,  // 设置侧边栏显示级别
 				// search: 'auto', // 搜索功能 
 				alias: {
--- a/sa-token-doc/doc/sso/sso-check-domain.md
+++ b/sa-token-doc/doc/sso/sso-check-domain.md
@@ -39,5 +39,5 @@
 ### 4、疑问：为什么不直接回传 Token，而是先回传 Ticket，再用 Ticket 去查询对应的账号id？
 Token 作为长时间有效的会话凭证，在任何时候都不应该直接暴露在 URL 之中（虽然 Token 直接的暴露本身不会造成安全漏洞，但会为很多漏洞提供可乘之机）

-因此 Sa-Token-SSO 选择先回传 Ticket，再由 Ticket 获取账号id，且 Ticket 一次性用完即废，提高安全性
+为了不让系统安全处于亚健康状态，Sa-Token-SSO 选择先回传 Ticket，再由 Ticket 获取账号id，且 Ticket 一次性用完即废，提高安全性。

--- a/sa-token-doc/doc/use/config.md
+++ b/sa-token-doc/doc/use/config.md
@@ -99,18 +99,30 @@ PS：两者的区别在于：**`方式1会覆盖yml中的配置，方式2会与y


 ### 单点登录相关配置 
-| 参数名称		| 类型		| 默认值		| 所属端					| 说明																			|
-| :--------		| :--------	| :--------	| :--------				| :--------																		|
-| ticketTimeout	| long		| 300		| Server端				| Ticket有效期 (单位: 秒)														|
-| allowUrl		| String	| *			| Server端				| 所有允许的授权回调地址，多个用逗号隔开 (不在此列表中的URL将禁止下放ticket)，参考：[SSO整合：配置域名校验](/sso/sso-check-domain)	|
-| secretkey		| String	| null		| Server端 & Client端	| 调用秘钥 (用于SSO模式三单点注销的接口通信身份校验)								|
-| authUrl		| String	| null		| Client端				| SSO-Server端 单点登录地址														|
-| isHttp		| Boolean	| false		| Server端 & Client端	| 是否使用http请求校验ticket值													|
-| checkTicketUrl| String	| null		| Client端				| SSO-Server端 Ticket校验地址													|
-| isSlo			| Boolean	| false		| Client端				| 是否打开单点注销功能															|
-| sloUrl		| String	| null		| Client端				| SSO-Server端 单点注销地址														|
-| ssoLogoutCall	| String	| null		| Client端				| SSO-Client端 当前Client端的单点注销回调URL （为空时自动获取）					|
-| userinfoUrl	| String	| null		| Client端				| SSO-Server端 查询userinfo地址													|
+
+Server 端：
+
+| 参数名称		| 类型		| 默认值		| 说明																			|
+| :--------		| :--------	| :--------	| :--------																		|
+| ticketTimeout	| long		| 300		| ticket 有效期 （单位: 秒）														|
+| allowUrl		| String	| *			| 所有允许的授权回调地址，多个用逗号隔开（不在此列表中的URL将禁止下放ticket），参考：[SSO整合：配置域名校验](/sso/sso-check-domain)	|
+| isSlo			| Boolean	| false		| 是否打开单点注销功能															|
+| isHttp		| Boolean	| false		| 是否打开模式三（此值为 true 时将使用 http 请求：校验ticket值、单点注销、获取userinfo）		|
+| secretkey		| String	| null		| 调用秘钥 （用于SSO模式三单点注销的接口通信身份校验）								|
+
+
+Client 端：
+
+| 参数名称		| 类型		| 默认值		| 说明											|
+| :--------		| :--------	| :--------	| :--------										|
+| authUrl		| String	| null		| 配置 Server 端单点登录授权地址					|
+| isSlo			| Boolean	| false		| 是否打开单点注销功能							|
+| isHttp		| Boolean	| false		| 是否打开模式三（此值为 true 时将使用 http 请求：校验ticket值、单点注销、获取userinfo）				|
+| checkTicketUrl| String	| null		| 配置 Server 端的 ticket 校验地址							|
+| userinfoUrl	| String	| null		| 配置 Server 端查询 userinfo 地址									|
+| sloUrl		| String	| null		| 配置 Server 端单点注销地址										|
+| ssoLogoutCall	| String	| null		| 配置当前 Client 端的单点注销回调URL （为空时自动获取）	|
+| secretkey		| String	| null		| 接口调用秘钥 （用于SSO模式三单点注销的接口通信身份校验）		|

 配置示例：
 ``` yml