完善 SaInterceptor 相关文档

sa-token-doc/doc/use/at-check.md

@@ -10,6 +10,7 @@
 - `@SaCheckPermission("user:add")`: 权限认证 —— 必须具有指定权限才能进入该方法。 
 - `@SaCheckSafe`: 二级认证校验 —— 必须二级认证之后才能进入该方法。 
 - `@SaCheckBasic`: HttpBasic认证 —— 只有通过 Basic 认证后才能进入该方法。 
+- `@SaIgnore`：忽略认证 —— 表示被修饰的方法或类无需进行注解认证和路由拦截认证。
 
 Sa-Token 使用全局拦截器完成注解鉴权功能，为了不为项目带来不必要的性能负担，拦截器默认处于关闭状态<br>
 因此，为了使用注解鉴权，**你必须手动将 Sa-Token 的全局拦截器注册到你项目中**
@@ -24,11 +25,11 @@ Sa-Token 使用全局拦截器完成注解鉴权功能，为了不为项目带
 ``` java
 @Configuration
 public class SaTokenConfigure implements WebMvcConfigurer {
-	// 注册Sa-Token的注解拦截器，打开注解式鉴权功能 
+	// 注册 Sa-Token 拦截器，打开注解式鉴权功能 
 	@Override
 	public void addInterceptors(InterceptorRegistry registry) {
-		// 注册注解拦截器，并排除不需要注解鉴权的接口地址 (与登录拦截器无关)
-		registry.addInterceptor(new SaAnnotationInterceptor()).addPathPatterns("/**");	
+		// 注册 Sa-Token 拦截器，打开注解式鉴权功能 
+		registry.addInterceptor(new SaInterceptor()).addPathPatterns("/**");	
 	}
 }
 ```
@@ -114,7 +115,36 @@ orRole 字段代表权限认证未通过时的次要选择，两者只要其一
 - 写法三：`orRole = {"admin, manager, staff"}`，代表必须同时具有三个角色。
 
 
-### 5、在业务逻辑层使用注解鉴权
+### 5、忽略认证 
+
+使用 `@SaIgnore` 可表示一个接口忽略认证：
+
+``` java
+@SaCheckLogin
+@RestController
+public class TestController {
+	
+	// ... 其它方法 
+	
+	// 此接口加上了 @SaIgnore 可以游客访问 
+	@SaIgnore
+	@RequestMapping("getList")
+	public SaResult getList() {
+		// ... 
+		return SaResult.ok(); 
+	}
+}
+```
+
+如上代码表示：`TestController` 中的所有方法都需要登录后才可以访问，但是 `getList` 接口可以匿名游客访问。
+
+- @SaIgnore 修饰方法时代表这个方法可以被游客访问，修饰类时代表这个类中的所有接口都可以游客访问。
+- @SaIgnore 具有最高优先级，当 @SaIgnore 和其它鉴权注解一起出现时，其它鉴权注解都将被忽略。
+- @SaIgnore 同样可以忽略掉 Sa-Token 拦截器中的路由鉴权，在下面的 [路由拦截鉴权] 章节中我们会讲到。
+
+
+
+### 6、在业务逻辑层使用注解鉴权
 疑问：我能否将注解写在其它架构层呢，比如业务逻辑层？
 
 使用拦截器模式，只能在`Controller层`进行注解鉴权，如需在任意层级使用注解鉴权，请参考：[AOP注解鉴权](/plugin/aop-at)

sa-token-doc/doc/use/route-check.md

@@ -18,28 +18,29 @@ public class SaTokenConfigure implements WebMvcConfigurer {
 	// 注册拦截器
 	@Override
 	public void addInterceptors(InterceptorRegistry registry) {
-		// 注册 Sa-Token 的路由拦截器
-		registry.addInterceptor(new SaRouteInterceptor())
-			.addPathPatterns("/**")
-			.excludePathPatterns("/user/doLogin"); 
+		// 注册 Sa-Token 拦截器，校验规则为 StpUtil.checkLogin() 登录校验。
+		registry.addInterceptor(new SaInterceptor(handle -> StpUtil.checkLogin()))
+				.addPathPatterns("/**")
+				.excludePathPatterns("/user/doLogin"); 
 	}
 }
 ```
-以上代码，我们注册了一个登录认证拦截器，并且排除了`/user/doLogin`接口用来开放登录（除了`/user/doLogin`以外的所有接口都需要登录才能访问）。
+以上代码，我们注册了一个基于 `StpUtil.checkLogin()` 的登录校验拦截器，并且排除了`/user/doLogin`接口用来开放登录（除了`/user/doLogin`以外的所有接口都需要登录才能访问）。
 
+!> `SaInterceptor` 是新版本提供的拦截器，点此 [查看旧版本代码迁移示例](https://blog.csdn.net/shengzhang_/article/details/126458949)。
 
 ### 2、校验函数详解  
-自定义认证规则：`new SaRouteInterceptor()` 是最简单的无参构造写法，代表只进行默认的登录校验功能。
+自定义认证规则：`new SaInterceptor(handle -> StpUtil.checkLogin())` 是最简单的写法，代表只进行登录校验功能。
 
-我们可以往构造函数塞一个 lambda 表达式，来自定义认证规则，例如：
+我们可以往构造函数塞一个完整的 lambda 表达式，来定义详细的校验规则，例如：
 
 ``` java 
 @Configuration
 public class SaTokenConfigure implements WebMvcConfigurer {
 	@Override
 	public void addInterceptors(InterceptorRegistry registry) {
-		// 注册 Sa-Token 的路由拦截器，自定义认证规则 
-		registry.addInterceptor(new SaRouteInterceptor((req, res, handler)->{
+		// 注册 Sa-Token 拦截器，定义详细认证规则 
+		registry.addInterceptor(new SaInterceptor(handler -> {
 			// 根据路由划分模块，不同模块不同鉴权 
 			SaRouter.match("/user/**", r -> StpUtil.checkPermission("user"));
 			SaRouter.match("/admin/**", r -> StpUtil.checkPermission("admin"));
@@ -61,11 +62,11 @@ SaRouter.match() 匹配函数有两个参数：
 ``` java 
 @Configuration
 public class SaTokenConfigure implements WebMvcConfigurer {
-	// 注册Sa-Token的拦截器
+	// 注册 Sa-Token 的拦截器
 	@Override
 	public void addInterceptors(InterceptorRegistry registry) {
 		// 注册路由拦截器，自定义认证规则 
-		registry.addInterceptor(new SaRouteInterceptor((req, res, handler) -> {
+		registry.addInterceptor(new SaInterceptor((req, res, handler) -> {
 			
 			// 登录认证 -- 拦截所有路由，并排除/user/doLogin 用于开放登录 
 			SaRouter.match("/**", "/user/doLogin", r -> StpUtil.checkLogin());
@@ -140,7 +141,7 @@ SaRouter
 使用 `SaRouter.stop()` 可以提前退出匹配链，例：
 
 ``` java
-registry.addInterceptor(new SaRouteInterceptor((req, res, handler) -> {
+registry.addInterceptor(new SaInterceptor((req, res, handler) -> {
 	SaRouter.match("/**").check(r -> System.out.println("进入1"));
 	SaRouter.match("/**").check(r -> System.out.println("进入2")).stop();
 	SaRouter.match("/**").check(r -> System.out.println("进入3"));
@@ -176,3 +177,36 @@ SaRouter.match("/**").check(/* --- */);
 
 free() 的作用是：打开一个独立的作用域，使内部的 stop() 不再一次性跳出整个 Auth 函数，而是仅仅跳出当前 free 作用域。
 
+
+### 6、使用注解忽略掉路由拦截校验
+
+我们可以使用 `@SaIgnore` 注解，忽略掉路由拦截认证：
+
+1、先配置好了拦截规则：
+``` java
+@Override
+public void addInterceptors(InterceptorRegistry registry) {
+	registry.addInterceptor(new SaInterceptor(handler -> {
+		// 根据路由划分模块，不同模块不同鉴权 
+		SaRouter.match("/user/**", r -> StpUtil.checkPermission("user"));
+		SaRouter.match("/admin/**", r -> StpUtil.checkPermission("admin"));
+		SaRouter.match("/goods/**", r -> StpUtil.checkPermission("goods"));
+		// ... 
+	})).addPathPatterns("/**");
+}
+```
+
+2、然后在 `Controller` 里又添加了忽略校验的注解
+``` java
+@SaIgnore
+@RequestMapping("/user/getList")
+public SaResult getList() {
+	System.out.println("------------ 访问进来方法"); 
+	return SaResult.ok(); 
+}
+```
+
+请求将会跳过拦截器的校验，直接进入 Controller 的方法中。
+
+**注意点：此注解的忽略效果只针对 SaInterceptor拦截器 和 APO注解鉴权 生效，对自定义拦截器与过滤器不生效。**
+