diff --git a/sa-token-doc/doc/use/at-check.md b/sa-token-doc/doc/use/at-check.md index af26b14e..82ae9e0b 100644 --- a/sa-token-doc/doc/use/at-check.md +++ b/sa-token-doc/doc/use/at-check.md @@ -10,6 +10,7 @@ - `@SaCheckPermission("user:add")`: 权限认证 —— 必须具有指定权限才能进入该方法。 - `@SaCheckSafe`: 二级认证校验 —— 必须二级认证之后才能进入该方法。 - `@SaCheckBasic`: HttpBasic认证 —— 只有通过 Basic 认证后才能进入该方法。 +- `@SaIgnore`:忽略认证 —— 表示被修饰的方法或类无需进行注解认证和路由拦截认证。 Sa-Token 使用全局拦截器完成注解鉴权功能,为了不为项目带来不必要的性能负担,拦截器默认处于关闭状态
因此,为了使用注解鉴权,**你必须手动将 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) diff --git a/sa-token-doc/doc/use/route-check.md b/sa-token-doc/doc/use/route-check.md index a1ab0996..5928ea15 100644 --- a/sa-token-doc/doc/use/route-check.md +++ b/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注解鉴权 生效,对自定义拦截器与过滤器不生效。** +