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

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

@@ -22,9 +22,13 @@ import cn.dev33.satoken.router.SaRouter;
 import cn.dev33.satoken.util.SaTokenConsts;
 
 /**
- * Servlet全局过滤器 
- * @author click33
+ * Servlet 全局鉴权过滤器
+ * <p>
+ *     默认优先级为 -100，尽量保证在其它过滤器之前执行
+ * </p>
  *
+ * @author click33
+ * @since <= 1.34.0
  */
 @Order(SaTokenConsts.ASSEMBLY_ORDER)
 public class SaServletFilter implements SaFilter, Filter {

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

@@ -23,7 +23,7 @@ import cn.dev33.satoken.strategy.SaStrategy;
 public class SaInterceptor implements HandlerInterceptor {
 
 	/**
-	 * 是否打开注解鉴权 
+	 * 是否打开注解鉴权，配置为 true 时注解鉴权才会生效，配置为 false 时，即使写了注解也不会进行鉴权
 	 */
 	public boolean isAnnotation = true;
 	
@@ -48,9 +48,9 @@ public class SaInterceptor implements HandlerInterceptor {
 	}
 
 	/**
-	 * 设置是否打开注解鉴权 
+	 * 设置是否打开注解鉴权：配置为 true 时注解鉴权才会生效，配置为 false 时，即使写了注解也不会进行鉴权
 	 * @param isAnnotation /
-	 * @return 对象自身 
+	 * @return 对象自身
 	 */
 	public SaInterceptor isAnnotation(boolean isAnnotation) {
 		this.isAnnotation = isAnnotation;
@@ -58,7 +58,7 @@ public class SaInterceptor implements HandlerInterceptor {
 	}
 	
 	/**
-	 * 写入[认证函数]: 每次请求执行 
+	 * 写入 [ 认证函数 ]: 每次请求执行
 	 * @param auth / 
 	 * @return 对象自身 
 	 */
@@ -79,27 +79,32 @@ public class SaInterceptor implements HandlerInterceptor {
 		
 		try {
 
+			// 这里必须确保 handler 是 HandlerMethod 类型时，才能进行注解鉴权
 			if(isAnnotation && handler instanceof HandlerMethod) {
 				
 				// 获取此请求对应的 Method 处理函数 
 				Method method = ((HandlerMethod) handler).getMethod();
 
-				// 如果此 Method 或其所属 Class 标注了 @SaIgnore，则忽略掉鉴权 
+				// 如果此 Method 或其所属 Class 标注了 @SaIgnore，则忽略掉鉴权
 				if(SaStrategy.me.isAnnotationPresent.apply(method, SaIgnore.class)) {
+					// 注意这里直接就退出整个鉴权了，最底部的 auth.run() 路由拦截鉴权也被跳出了
 					return true;
 				}
 
-				// 注解校验 
+				// 执行注解鉴权
 				SaStrategy.me.checkMethodAnnotation.accept(method);
 			}
 			
-			// Auth 校验  
+			// Auth 路由拦截鉴权校验
 			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-boot-starter/src/main/java/cn/dev33/satoken/spring/SaTokenContextForSpring.java

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

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

@@ -5,17 +5,17 @@ import org.springframework.context.annotation.Bean;
 import cn.dev33.satoken.context.SaTokenContext;
 
 /**
- * 注册Sa-Token所需要的Bean 
- * <p> Bean 的注册与注入应该分开在两个文件中，否则在某些场景下会造成循环依赖 
- * @author click33
+ * 注册 Sa-Token 框架所需要的 Bean
  *
+ * @author click33
+ * @since <= 1.34.0
  */
 public class SaTokenContextRegister {
 
 	/**
-	 * 获取上下文Bean (Spring版)
+	 * 获取上下文处理器组件 (Spring版)
 	 * 
-	 * @return 容器交互Bean (Spring版)
+	 * @return /
 	 */
 	@Bean
 	public SaTokenContext getSaTokenContextForSpring() {

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

@@ -10,9 +10,10 @@ import cn.dev33.satoken.error.SaSpringBootErrorCode;
 import cn.dev33.satoken.exception.NotWebContextException;
 
 /**
- * SpringMVC相关操作  
- * @author click33
+ * SpringMVC 相关操作工具类，快速获取当前会话的 HttpServletRequest、HttpServletResponse 对象
  *
+ * @author click33
+ * @since <= 1.34.0
  */
 public class SpringMVCUtil {
 	
@@ -20,32 +21,32 @@ public class SpringMVCUtil {
 	}
 	
 	/**
-	 * 获取当前会话的 request 
+	 * 获取当前会话的 request 对象
 	 * @return request
 	 */
 	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();
 	}
 	
 	/**
-	 * 获取当前会话的 response
+	 * 获取当前会话的 response 对象
 	 * @return response
 	 */
 	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 上下文无法获取 HttpServletResponse").setCode(SaSpringBootErrorCode.CODE_20101);
 		}
 		return servletRequestAttributes.getResponse();
 	}
 
 	/**
 	 * 判断当前是否处于 Web 上下文中  
-	 * @return request
+	 * @return /
 	 */
 	public static boolean isWeb() {
 		return RequestContextHolder.getRequestAttributes() != null;