Sa-Token 注解鉴权实战指南从 SaCheckLogin 到 SaCheckOr 的完整用法与底层原理【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架让鉴权变得简单、优雅—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token注解鉴权是 Sa-Token 提供的将鉴权逻辑与业务代码解耦的声明式方案开发者只需在 Controller 方法上标注SaCheckLogin、SaCheckRole(admin)、SaCheckPermission(user:add)等注解即可由框架统一完成登录、角色、权限、二级认证、Http Basic/Digest、账号封禁、API 签名等各类校验。本文将以 sa-token-doc/use/at-check.md 为骨架结合核心注解源码与官方示例完整讲解拦截器注册、全部注解的用法、校验模式、角色权限双重校验、忽略认证与批量注解鉴权并补充源码级实现原理帮助你在一套代码风格统一的工程里优雅落地声明式鉴权。一、注解鉴权是什么把鉴权逻辑从业务代码中剥离许多开发者习惯了代码鉴权——在方法内部通过StpUtil.checkLogin()、StpUtil.checkPermission(...)等方法手动编写校验语句。这种方式虽然灵活但会把鉴权逻辑与业务逻辑混在一起当校验规则复杂时方法体容易变得臃肿。Sa-Token 提供注解鉴权正是为了解决这一问题将鉴权逻辑以注解的形式声明在方法或类上由框架统一拦截执行业务方法内部只保留纯粹的业务代码。Sa-Token 核心包 sa-token-core 中内置了以下鉴权注解源码位于 sa-token-core/src/main/java/cn/dev33/satoken/annotation注解功能说明SaCheckLogin登录校验 —— 只有登录之后才能进入该方法SaCheckRole(admin)角色校验 —— 必须具有指定角色标识才能进入该方法SaCheckPermission(user:add)权限校验 —— 必须具有指定权限才能进入该方法SaCheckSafe二级认证校验 —— 必须二级认证之后才能进入该方法SaCheckHttpBasicHttpBasic 校验 —— 只有通过 HttpBasic 认证后才能进入该方法SaCheckHttpDigestHttpDigest 校验 —— 只有通过 HttpDigest 认证后才能进入该方法SaCheckDisable(comment)账号服务封禁校验 —— 校验当前账号指定服务是否被封禁SaCheckSignAPI 签名校验 —— 用于跨系统的 API 签名参数校验位于扩展插件 sa-token-sign 中SaIgnore忽略校验 —— 表示被修饰的方法或类无需进行注解鉴权和路由拦截器鉴权SaCheckOr批量注解鉴权 —— 满足其中一个注解即可通过校验关键前提Sa-Token 使用全局拦截器完成注解鉴权功能为了不为项目带来不必要的性能负担拦截器默认处于关闭状态。因此想要使用注解鉴权你必须手动将 Sa-Token 的全局拦截器注册到项目中。二、第一步注册 SaInterceptor 全局拦截器以 SpringBoot 2 项目为例新建配置类SaTokenConfigure.javaConfiguration public class SaTokenConfigure implements WebMvcConfigurer { // 注册 Sa-Token 拦截器打开注解式鉴权功能 Override public void addInterceptors(InterceptorRegistry registry) { // 注册 Sa-Token 拦截器打开注解式鉴权功能 registry.addInterceptor(new SaInterceptor()).addPathPatterns(/**); } }保证此类被 SpringBoot 启动类扫描到即可。官方示例工程中sa-token-demo-case项目正是这样做的见 SaTokenConfigure 所在配置类其 Controller 示例 AtCheckController.java 注释中明确要求项目在配置类中注册拦截器 SaInterceptor此拦截器将打开注解鉴权功能。拦截器的底层工作方式源码视角从源码看SaInterceptor是 Spring MVC 的HandlerInterceptor实现sa-token-spring-boot-starter 中的实现。其preHandle方法按以下顺序执行执行beforeAuth前置函数在注解鉴权之前执行确保handler是HandlerMethod类型时才调用SaAnnotationStrategy.instance.checkMethodAnnotation.accept(method)进行注解鉴权对应源码第 113-117 行if(isAnnotation handler instanceof HandlerMethod)执行auth路由拦截鉴权校验函数。其中isAnnotation字段默认为true表示拦截器默认携带注解鉴权能力也可通过new SaInterceptor().isAnnotation(false)显式关闭注解鉴权仅保留路由拦截功能。此外SaInterceptor还提供了setBeforeAuth(...)与setAuth(...)两个链式方法分别用于注入认证前置函数与每次请求都执行的认证函数这部分能力与路由拦截鉴权章节配合使用详见文档 global-filter.md。三、第二步使用注解鉴权注册好拦截器后即可在接口上直接使用注解// 登录校验只有登录之后才能进入该方法 SaCheckLogin RequestMapping(info) public String info() { return 查询用户信息; } // 角色校验必须具有指定角色才能进入该方法 SaCheckRole(super-admin) RequestMapping(add) public String add() { return 用户增加; } // 权限校验必须具有指定权限才能进入该方法 SaCheckPermission(user-add) RequestMapping(add) public String add() { return 用户增加; } // 二级认证校验必须二级认证之后才能进入该方法 SaCheckSafe() RequestMapping(add) public String add() { return 用户增加; } // Http Basic 校验只有通过 Http Basic 认证后才能进入该方法 SaCheckHttpBasic(account sa:123456) RequestMapping(add) public String add() { return 用户增加; } // Http Digest 校验只有通过 Http Digest 认证后才能进入该方法 SaCheckHttpDigest(value sa:123456) RequestMapping(add) public String add() { return 用户增加; } // 校验当前账号是否被封禁 comment 服务如果已被封禁会抛出异常无法进入方法 SaCheckDisable(comment) RequestMapping(send) public String send() { return 查询用户信息; }注以上注解都可以加在类上代表为这个类所有方法进行鉴权源码中每个注解的Target均包含ElementType.METHOD与ElementType.TYPE如 SaCheckLogin.java。几个注解的源码细节SaCheckLogin只有一个type()属性默认为空字符串用于多账号体系下指定所属账号体系标识非多账号体系无需关注见 SaCheckLogin.javaSaCheckPermission除type()外还有value()需要校验的权限码数组与mode()验证模式默认SaMode.AND以及orRole()权限校验不通过时的次要选择见 SaCheckPermission.javaSaCheckRole拥有value()与mode()两个核心属性见 SaCheckRole.javaSaCheckSafe的value()指定要校验的服务默认值为SaTokenConsts.DEFAULT_SAFE_AUTH_SERVICE见 SaCheckSafe.java。在官方示例 AtCheckController.java 中可以看到这些注解的完整可运行示例前提是先调用登录接口http://localhost:8081/acc/doLogin?namezhangpwd123456完成登录。四、设定校验模式SaMode.AND 与 SaMode.ORSaCheckRole与SaCheckPermission注解可设置校验模式例如// 注解式鉴权只要具有其中一个权限即可通过校验 RequestMapping(atJurOr) SaCheckPermission(value {user-add, user-all, user-delete}, mode SaMode.OR) public SaResult atJurOr() { return SaResult.data(用户信息); }mode有两种取值SaMode.AND标注一组权限会话必须全部具有才可通过校验这也是注解的默认模式源码中SaMode mode() default SaMode.AND;SaMode.OR标注一组权限会话只要具有其一即可通过校验。SaMode枚举定义于 SaMode.java。在官方示例 AtCheckController.java 中可以看到两种模式的对照用法checkPermission2接口要求user.add、user.delete、user.update三个权限全部拥有SaMode.AND而checkPermission3接口只需要拥有其中一个SaMode.OR。五、角色权限双重or 校验orRole 字段假设有以下业务场景一个接口在具有权限user.add或角色admin时可以调通。写法如下// 角色权限双重 or校验具备指定权限或者指定角色即可通过校验 RequestMapping(userAdd) SaCheckPermission(value user.add, orRole admin) public SaResult userAdd() { return SaResult.data(用户信息); }orRole字段代表权限校验未通过时的次要选择两者只要其一校验成功即可进入请求方法其有三种写法写法一orRole admin代表需要拥有角色admin写法二orRole {admin, manager, staff}代表具有三个角色其一即可写法三orRole {admin, manager, staff}代表必须同时具有三个角色注意逗号写在字符串内部。从源码注释可以印证这一点见 SaCheckPermission.javaorRole默认值为空数组{}示例 1 表示只要具有 user-add 权限或 admin 角色其一即可通过校验示例 2/3 分别对应其一与同时具备两种语义。SaCheckPermission的value与orRole同时校验时逻辑为权限命中或角色命中即可放行这也是该接口名为角色权限双重 or 校验的原因。六、忽略认证SaIgnore 的优先级规则使用SaIgnore可表示一个接口忽略认证SaCheckLogin RestController public class TestController { // ... 其它方法 // 此接口加上了 SaIgnore 可以游客访问 SaIgnore RequestMapping(getList) public SaResult getList() { // ... return SaResult.ok(); } }如上代码表示TestController中的所有方法都需要登录后才可以访问但是getList接口可以匿名游客访问。SaIgnore的使用规则SaIgnore修饰方法时代表这个方法可以被游客访问修饰类时代表这个类中的所有接口都可以游客访问SaIgnore具有最高优先级当SaIgnore和其它鉴权注解一起出现时其它鉴权注解都将被忽略SaIgnore同样可以忽略掉 Sa-Token 拦截器中的路由鉴权即SaInterceptor的auth认证函数在路由拦截鉴权章节中会讲到。官方示例 AtCheckController.java 中ignore接口同时标注了SaIgnore与SaCheckLogin验证了最高优先级规则该接口无需登录即可访问。从源码看SaIgnore定义于 SaIgnore.java其 javadoc 特别强调此注解的忽略效果只针对 SaInterceptor 拦截器和 AOP 注解鉴权生效对自定义拦截器与过滤器不生效。这意味着如果你自己编写了独立的 Filter/Interceptor 做鉴权SaIgnore并不会跳过它们——在设计开放接口的白名单时需要注意这一点。七、批量注解鉴权SaCheckOr 的多条件或语义使用SaCheckOr表示批量注解鉴权// 在 SaCheckOr 中可以指定多个注解只要当前会话满足其中一个注解即可通过验证进入方法。 SaCheckOr( login SaCheckLogin, role SaCheckRole(admin), permission SaCheckPermission(user.add), safe SaCheckSafe(update-password), httpBasic SaCheckHttpBasic(account sa:123456), disable SaCheckDisable(submit-orders) ) RequestMapping(test) public SaResult test() { // ... return SaResult.ok(); }每一项属性都可以写成数组形式例如// 当前客户端只要有 [ login 账号登录] 或者 [user 账号登录] 其一就可以通过验证进入方法。 // 注意type login 和 type user 是多账号模式章节的扩展属性此处你可以先略过这个知识点。 SaCheckOr( login { SaCheckLogin(type login), SaCheckLogin(type user) } ) RequestMapping(test) public SaResult test() { // ... return SaResult.ok(); }从源码看SaCheckOr定义于 SaCheckOr.java自 1.35.0 版本引入其内置属性均为数组类型login、role、permission、safe、httpBasic、httpDigest、disable另有append属性用于追加抓取扩展包里的注解只能填写 Sa-Token 相关注解类型源码注释为Class? extends Annotation[] append()。为什么没有 SaCheckAnd疑问既然有了SaCheckOr为什么没有与之对应的SaCheckAnd呢因为当你写多个注解时其天然就是and校验关系例如// 当你在一个方法上写多个注解鉴权时其默认就是要满足所有注解规则后才可以进入方法只要有一个不满足就会抛出异常 SaCheckLogin SaCheckRole(admin) SaCheckPermission(user.add) RequestMapping(test) public SaResult test() { // ... return SaResult.ok(); }即多个注解并列 全部满足AND 语义SaCheckOr内部嵌套 满足其一OR 语义两者组合即可表达任意复杂的鉴权表达式。使用 append 字段追加扩展注解append字段用于抓取扩展包里的注解例如// 测试只有通过登录校验或者提供了正确的 ApiKey才可以进入方法 RequestMapping(/test) SaCheckOr(login SaCheckLogin, append { SaCheckApiKey.class }) SaCheckApiKey public SaResult test() { // ... return SaResult.ok(); }这里的SaCheckApiKey来自sa-token-apikey插件对应源码 sa-token-apikey它通过append机制被纳入SaCheckOr的或校验集合中实现登录通过或ApiKey 通过即可进入方法的效果。八、扩展阅读与官方示例在业务逻辑层Service 层使用鉴权注解AOP 注解鉴权注拦截器模式只能在 Controller 层进行注解鉴权如需在任意层级使用注解鉴权请参考该文档制作自定义鉴权注解注入到框架自定义注解完整的可运行代码示例见 AtCheckController.java其中包含登录鉴权、权限校验AND/OR 两种模式、角色校验、角色权限双重 or 校验、忽略校验的完整接口与访问地址可直接在本地启动sa-token-demo-case工程后逐一体验。结语注解鉴权让 Sa-Token 的鉴权能力以最简洁的方式融入工程一次拦截器注册new SaInterceptor()换来全部注解的生效SaCheckLogin/SaCheckRole/SaCheckPermission覆盖最主流的登录、角色、权限校验SaMode.AND/OR与orRole解决组合校验SaIgnore提供最高优先级的放行出口SaCheckOr则把任意多种条件收敛为满足其一的统一表达。配合 AOP 注解鉴权 的能力你可以将这套声明式鉴权从 Controller 层一路延伸到 Service 层真正实现鉴权逻辑与业务逻辑的彻底分离。【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架让鉴权变得简单、优雅—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
