Sa-Token Thymeleaf 标签方言在页面中优雅实现登录、角色与权限控制【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架让鉴权变得简单、优雅—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token本篇文章讲解 Sa-Token 官方插件sa-token-thymeleaf的完整用法如何把它引入 Thymeleaf 模板引擎、如何注册标签方言 Bean、如何使用sa:前缀下的登录判断 / 角色判断 / 权限判断标签以及如何通过注入全局变量stp在页面中直接调用 Sa-Token 的底层 API。读完本文你将能够在 Thymeleaf 页面中零 Java 代码地完成大部分鉴权显隐控制并理解每个标签背后的实现原理。1、标签方言是什么Sa-Token 的核心能力登录认证、角色认证、权限认证默认是在 Java 层通过StpUtil调用的。但在 Web 开发中很多鉴权需求发生在视图层例如登录用户才能看到这段内容只有 admin 角色才能看到管理按钮没有 user-add 权限就不渲染新增按钮。sa-token-thymeleaf插件为 Thymeleaf 提供了一套自定义标签方言Dialect让你可以直接在 HTML 标签属性上写sa:login、sa:hasRoleadmin这类指令。模板渲染时Thymeleaf 引擎会根据当前登录状态动态决定保留或移除对应元素从而实现页面级的权限控制无需编写任何 Java 判断逻辑。从源码看该方言由三个文件构成SaTokenDialect.java方言主体继承 Thymeleaf 的AbstractProcessorDialect注册全部标签处理器SaTokenTagProcessor.java属性标签处理器负责执行判断表达式并按结果保留/移除元素Sa-Token-Dialect.xml方言描述文件声明命名空间与各属性的说明文档。2、引入依赖首先确保项目已经引入 Thymeleaf 依赖Spring Boot 项目通常使用spring-boot-starter-thymeleaf然后在此基础上继续添加sa-token-thymeleaf插件。Maven 方式!-- 在 thymeleaf 标签中使用 Sa-Token -- dependency groupIdcn.dev33/groupId artifactIdsa-token-thymeleaf/artifactId version${sa.top.version}/version /dependencyGradle 方式// 在 thymeleaf 标签中使用 Sa-Token implementation cn.dev33:sa-token-thymeleaf:${sa.top.version}说明${sa.top.version}是 Sa-Token 版本号占位符请替换为你实际使用的版本。仓库中的演示工程 sa-token-demo-thymeleaf/pom.xml 使用的是1.46.0可作参考。从插件自身的 pom.xml 可以看到它仅依赖sa-token-coreSa-Token 核心与thymeleaf且标记为optional不会引入多余的传递依赖非常轻量。3、注册标签方言对象依赖引入后需要在 Spring 配置类中把SaTokenDialect注册为 BeanThymeleaf 才能识别并启用这套方言。在SaTokenConfigure配置类中注册 BeanConfiguration public class SaTokenConfigure { // Sa-Token 标签方言 (Thymeleaf版) Bean public SaTokenDialect getSaTokenDialect() { return new SaTokenDialect(); } }仓库演示工程中的 SaTokenConfigure.java 就是完全一致的写法。关于底层 StpLogic源码细节SaTokenDialect有两个构造方法。无参构造内部实际调用的是this(sa, 1000, StpUtil.stpLogic)即默认方言名称为sa、处理器优先级为1000、底层复用StpUtil的全局StpLogic你也可以通过new SaTokenDialect(name, precedence, stpLogic)自定义方言名称、优先级和所绑定的StpLogic适用于多账号体系让不同页面绑定不同登录体系。这一点在 SaTokenDialectTest.java 的defaultConstructor_usesSaPrefixAndGlobalStpLogic与customConstructor_keepsNameAndPrecedence两个测试用例中得到了直接验证。4、使用标签方言注册完成后就可以在 Thymeleaf 页面中直接使用sa:前缀的标签了。所有标签都会在渲染时执行一次判断条件满足则保留元素并把sa:属性从标签上移除条件不满足则整个元素连同其子内容被删除这是 Thymeleaf 自定义属性处理器SaTokenTagProcessor.doProcess中structureHandler.removeElement()的行为详见 SaTokenTagProcessor.java。4.1、登录判断h2标签方言测试页面/h2 p 登录之后才能显示 span sa:loginvalue/span /p p 不登录才能显示 span sa:notLoginvalue/span /psa:login当前账号已登录时显示该元素sa:notLogin当前账号未登录时显示该元素。这两个标签底层调用的是stpLogic.isLogin()见 SaTokenDialect.javalogin取真值显示、notLogin取反后显示。4.2、角色判断p 具有角色 admin 才能显示 span sa:hasRoleadminvalue/span /p p 同时具备多个角色才能显示 span sa:hasRoleAndadmin, ceo, ctovalue/span /p p 只要具有其中一个角色就能显示 span sa:hasRoleOradmin, ceo, ctovalue/span /p p 不具有角色 admin 才能显示 span sa:notRoleadminvalue/span /psa:hasRoleadmin具有指定角色才显示sa:hasRoleAndadmin, ceo, cto同时具备多个角色才显示多个值用逗号分隔sa:hasRoleOradmin, ceo, cto只要具备其中任一角色就显示sa:notRoleadmin不具有指定角色才显示。从源码看多角色/多权限值会先经过SaTokenDialect.toArray(value)转换成字符串数组内部使用SaFoxUtil.convertStringToList按逗号切分并自动去除空格因此admin, ceo, cto与admin,ceo,cto等价对应测试toArray_splitsAndTrims也验证了 admin , user 会被正确解析为[admin, user]。另外方言 XML 描述文件 Sa-Token-Dialect.xml 中还声明了一个sa:lackRole属性语义与notRole相同不具有指定角色才能显示元素但文档标注为未来版本可能废弃建议更换为 notRole。同理还有sa:lackPermission对应notPermission。新项目建议直接使用notRole/notPermission。4.3、权限判断p 具有权限 user-add 才能显示 span sa:hasPermissionuser-addvalue/span /p p 同时具备多个权限才能显示 span sa:hasPermissionAnduser-add, user-delete, user-getvalue/span /p p 只要具有其中一个权限就能显示 span sa:hasPermissionOruser-add, user-delete, user-getvalue/span /p p 不具有权限 user-add 才能显示 span sa:notPermissionuser-addvalue/span /psa:hasPermissionuser-add具有指定权限才显示sa:hasPermissionAnduser-add, user-delete, user-get同时具备全部权限才显示sa:hasPermissionOruser-add, user-delete, user-get具备其中任一权限就显示sa:notPermissionuser-add不具有指定权限才显示。权限数据的来源由项目中的StpInterface实现类提供。仓库演示工程 StpInterfaceImpl.java 模拟返回了user-add、user-delete等权限码集合以及admin、super-admin角色集合可对照理解标签判断的数据从何而来。4.4、渲染行为验证测试用例仓库在 SaTokenDialectTest.java 中对全部标签的显隐行为做了完整测试例如hasRoleTag_rendersOrRemoves拥有admin角色时div保留只有user角色时整个元素被移除hasRoleAndTag_requiresAllRolessa:hasRoleAndadmin,ops要求两个角色齐全才显示hasRoleOrTag_requiresAnyRolesa:hasRoleOradmin,ops只要具备其一即可hasRoleTag_hiddenWhenNotLogin未登录时hasRole等标签一律隐藏内部通过捕获NotLoginException返回 false这个行为非常实用避免未登录页面暴露敏感区域getProcessors_registers13Processors方言共注册 13 个处理器12 个鉴权标签 1 个用于移除html命名空间声明的处理器。5、在页面中调用 Sa-Token 相关 API标签方言可以满足大多数场景下的权限判断。但有时候我们依然需要更加灵活地在页面中调用 Sa-Token 框架 API例如读取SaSession中存放的业务数据、获取当前登录账号 ID 等。此时可以借助 Thymeleaf 的全局静态变量机制把StpLogic暴露给页面。首先在SaTokenConfigure配置类中为 Thymeleaf 配置全局对象Configuration public class SaTokenConfigure{ // ... 其它代码 // 为 Thymeleaf 注入全局变量以便在页面中调用 Sa-Token 的方法 Autowired private void configureThymeleafStaticVars(ThymeleafViewResolver viewResolver) { viewResolver.addStaticVariable(stp, StpUtil.stpLogic); } }[!WARNING| label:注意] 如果SaTokenConfigure继承了WebMvcConfigurer等类可能会造成循环依赖如果遇到请新建一个其他配置类完成此项配置。然后就可以在页面上调用StpLogic的 API 了例如p调用 StpLogic 方法调用测试/p p th:if${stp.isLogin()} 从SaSession中取值 span th:text${stp.getSession().get(name)}/span /p这里stp即StpUtil.stpLogic因此在页面中stp.isLogin()、stp.getSession().get(name)、stp.getLoginId()等StpLogic的公开方法都可以直接调用与 Java 层的StpUtil完全同源。StpLogic是整个 Sa-Token 登录逻辑门面的实现类多账号体系下每个 loginType 对应一个独立的StpLogic实例这也是方言构造方法接受StpLogic参数的意义所在。6、代码提示如果想在写标签属性时获得 IDE 的代码提示补全sa:login、sa:hasRole等属性只需在 HTML 头部声明增加上对应的命名空间即可!DOCTYPE html html langzh xmlns:sahttp://www.thymeleaf.org/extras/sa-token head !-- 代码 -- /head body !-- 代码 -- /body /html命名空间http://www.thymeleaf.org/extras/sa-token与方言描述文件 Sa-Token-Dialect.xml 中声明的namespace-uri保持一致。声明命名空间属于纯提示性质即使不写标签在运行时也能正常工作。7、常用标签速查表标签属性底层调用基于StpLogic显示条件sa:loginisLogin()已登录sa:notLogin!isLogin()未登录sa:hasRoleadminhasRole(admin)具有指定角色sa:hasRoleAnda, bhasRoleAnd([a, b])同时具备全部角色sa:hasRoleOra, bhasRoleOr([a, b])具备任一角色sa:notRoleadmin!hasRole(admin)不具有指定角色sa:lackRoleadmin!hasRole(admin)同notRole建议使用notRolesa:hasPermissionuser-addhasPermission(user-add)具有指定权限sa:hasPermissionAnda, bhasPermissionAnd([a, b])同时具备全部权限sa:hasPermissionOra, bhasPermissionOr([a, b])具备任一权限sa:notPermissionuser-add!hasPermission(user-add)不具有指定权限sa:lackPermissionuser-add!hasPermission(user-add)同notPermission建议使用notPermission8、小结sa-token-thymeleaf插件以 Thymeleaf 自定义方言的形式把 Sa-Token 的登录、角色、权限三大鉴权能力无缝下沉到视图层让你在 HTML 中即可完成精细的显隐控制同时通过stp全局变量保留了调用StpLogic全量 API 的灵活性。其实现路径清晰SaTokenDialect负责注册处理器SaTokenTagProcessor负责按判断结果渲染或移除元素方言测试 与 演示工程 提供了可直接运行的参考。如果你是 Spring Boot Thymeleaf 技术栈这套标签方言能显著简化页面级权限控制的代码量。【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架让鉴权变得简单、优雅—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考