优化 sa-token-spring-boot3-starter 模块注释

sa-token-starter/sa-token-spring-boot-starter/src/main/java/cn/dev33/satoken/filter/SaServletFilter.java

@@ -127,7 +127,9 @@ public class SaServletFilter implements SaFilter, Filter {
 			// 1. 获取异常处理策略结果 
 			String result = (e instanceof BackResultException) ? e.getMessage() : String.valueOf(error.run(e));
 			
-			// 2. 写入输出流 
+			// 2. 写入输出流
+			// 		请注意此处默认 Content-Type 为 text/plain，如果需要返回 JSON 信息，需要在 return 前自行设置 Content-Type 为 application/json
+			// 		例如：SaHolder.getResponse().setHeader("Content-Type", "application/json;charset=UTF-8");
 			if(response.getContentType() == null) {
 				response.setContentType("text/plain; charset=utf-8"); 
 			}

sa-token-starter/sa-token-spring-boot3-starter/src/main/java/cn/dev33/satoken/filter/SaServletFilter.java

@@ -21,9 +21,13 @@ import jakarta.servlet.ServletRequest;
 import jakarta.servlet.ServletResponse;
 
 /**
- * Servlet全局过滤器 
- * @author click33
+ * Servlet 全局鉴权过滤器
+ * <p>
+ *     默认优先级为 -100，尽量保证在其它过滤器之前执行
+ * </p>
  *
+ * @author click33
+ * @since <= 1.34.0
  */
 @Order(SaTokenConsts.ASSEMBLY_ORDER)
 public class SaServletFilter implements SaFilter, Filter {
@@ -122,7 +126,9 @@ public class SaServletFilter implements SaFilter, Filter {
 			// 1. 获取异常处理策略结果 
 			String result = (e instanceof BackResultException) ? e.getMessage() : String.valueOf(error.run(e));
 			
-			// 2. 写入输出流 
+			// 2. 写入输出流
+			// 		请注意此处默认 Content-Type 为 text/plain，如果需要返回 JSON 信息，需要在 return 前自行设置 Content-Type 为 application/json
+			// 		例如：SaHolder.getResponse().setHeader("Content-Type", "application/json;charset=UTF-8");
 			if(response.getContentType() == null) {
 				response.setContentType("text/plain; charset=utf-8"); 
 			}

sa-token-starter/sa-token-spring-boot3-starter/src/main/java/cn/dev33/satoken/interceptor/SaInterceptor.java

@@ -78,6 +78,7 @@ public class SaInterceptor implements HandlerInterceptor {
 		
 		try {
 
+			// 这里必须确保 handler 是 HandlerMethod 类型时，才能进行注解鉴权
 			if(isAnnotation && handler instanceof HandlerMethod) {
 				
 				// 获取此请求对应的 Method 处理函数 
@@ -85,6 +86,7 @@ public class SaInterceptor implements HandlerInterceptor {
 
 				// 如果此 Method 或其所属 Class 标注了 @SaIgnore，则忽略掉鉴权 
 				if(SaStrategy.me.isAnnotationPresent.apply(method, SaIgnore.class)) {
+					// 注意这里直接就退出整个鉴权了，最底部的 auth.run() 路由拦截鉴权也被跳出了
 					return true;
 				}
 
@@ -96,9 +98,12 @@ public class SaInterceptor implements HandlerInterceptor {
 			auth.run(handler);
 			
 		} catch (StopMatchException e) {
-			// 停止匹配，进入Controller 
+			// StopMatchException 异常代表：停止匹配，进入Controller
+
 		} catch (BackResultException e) {
-			// 停止匹配，向前端输出结果 
+			// BackResultException 异常代表：停止匹配，向前端输出结果
+			// 		请注意此处默认 Content-Type 为 text/plain，如果需要返回 JSON 信息，需要在 back 前自行设置 Content-Type 为 application/json
+			// 		例如：SaHolder.getResponse().setHeader("Content-Type", "application/json;charset=UTF-8");
 			if(response.getContentType() == null) {
 				response.setContentType("text/plain; charset=utf-8"); 
 			}

sa-token-starter/sa-token-spring-boot3-starter/src/main/java/cn/dev33/satoken/spring/SaTokenContextForSpringInJakartaServlet.java

@@ -9,15 +9,15 @@ import cn.dev33.satoken.servlet.model.SaResponseForServlet;
 import cn.dev33.satoken.servlet.model.SaStorageForServlet;
 
 /**
- * Sa-Token 上下文处理器 [ SpringBoot3 Jakarta Servlet 版 ] 
+ * Sa-Token 上下文处理器 [ SpringBoot3 Jakarta Servlet 版 ]，在 SpringBoot3 中使用 Sa-Token 时，必须注入此实现类，否则会出现上下文无效异常
  * 
  * @author click33
- *
+ * @since <= 1.34.0
  */
 public class SaTokenContextForSpringInJakartaServlet implements SaTokenContext {
 
 	/**
-	 * 获取当前请求的Request对象
+	 * 获取当前请求的 Request 包装对象
 	 */
 	@Override
 	public SaRequest getRequest() {
@@ -25,7 +25,7 @@ public class SaTokenContextForSpringInJakartaServlet implements SaTokenContext {
 	}
 
 	/**
-	 * 获取当前请求的Response对象
+	 * 获取当前请求的 Response 包装对象
 	 */
 	@Override
 	public SaResponse getResponse() {
@@ -33,7 +33,7 @@ public class SaTokenContextForSpringInJakartaServlet implements SaTokenContext {
 	}
 
 	/**
-	 * 获取当前请求的 [存储器] 对象 
+	 * 获取当前请求的 Storage 包装对象
 	 */
 	@Override
 	public SaStorage getStorage() {
@@ -41,7 +41,7 @@ public class SaTokenContextForSpringInJakartaServlet implements SaTokenContext {
 	}
 	
 	/**
-	 * 校验指定路由匹配符是否可以匹配成功指定路径 
+	 * 判断：指定路由匹配符是否可以匹配成功指定路径
 	 */
 	@Override
 	public boolean matchPath(String pattern, String path) {
@@ -49,7 +49,7 @@ public class SaTokenContextForSpringInJakartaServlet implements SaTokenContext {
 	}
 
 	/**
-	 * 此上下文是否有效 
+	 * 判断：在本次请求中，此上下文是否可用。
 	 */
 	@Override
 	public boolean isValid() {

sa-token-starter/sa-token-spring-boot3-starter/src/main/java/cn/dev33/satoken/spring/SaTokenContextRegister.java

@@ -5,16 +5,15 @@ import org.springframework.context.annotation.Bean;
 import cn.dev33.satoken.context.SaTokenContext;
 
 /**
- * SaTokenContext 上下文注册 
+ * 注册 Sa-Token 框架所需要的 Bean
  * 
  * @author click33
  * @since 2023年1月1日
- *
  */
 public class SaTokenContextRegister {
 
 	/**
-	 * 获取上下文Bean [ SpringBoot3 Jakarta Servlet 版 ] 
+	 * 获取上下文处理器组件 (SpringBoot3 Jakarta Servlet 版)
 	 * 
 	 * @return / 
 	 */

sa-token-starter/sa-token-spring-boot3-starter/src/main/java/cn/dev33/satoken/spring/SpringMVCUtil.java

@@ -9,9 +9,10 @@ import jakarta.servlet.http.HttpServletRequest;
 import jakarta.servlet.http.HttpServletResponse;
 
 /**
- * SpringMVC相关操作  
- * @author click33
+ * SpringMVC 相关操作工具类，快速获取当前会话的 HttpServletRequest、HttpServletResponse 对象
  *
+ * @author click33
+ * @since <= 1.34.0
  */
 public class SpringMVCUtil {
 	
@@ -25,7 +26,7 @@ public class SpringMVCUtil {
 	public static HttpServletRequest getRequest() {
 		ServletRequestAttributes servletRequestAttributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
 		if(servletRequestAttributes == null) {
-			throw new NotWebContextException("非Web上下文无法获取Request").setCode(SaSpringBootErrorCode.CODE_20101);
+			throw new NotWebContextException("非 web 上下文无法获取 HttpServletRequest").setCode(SaSpringBootErrorCode.CODE_20101);
 		}
 		return servletRequestAttributes.getRequest();
 	}
@@ -37,7 +38,7 @@ public class SpringMVCUtil {
 	public static HttpServletResponse getResponse() {
 		ServletRequestAttributes servletRequestAttributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
 		if(servletRequestAttributes == null) {
-			throw new NotWebContextException("非Web上下文无法获取Response").setCode(SaSpringBootErrorCode.CODE_20101);
+			throw new NotWebContextException("非 web 上下文无法获取 HttpServletRequest").setCode(SaSpringBootErrorCode.CODE_20101);
 		}
 		return servletRequestAttributes.getResponse();
 	}