Sa-Token 集成 Thymeleaf 标签方言在页面模板中实现登录态与权限判断【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架让鉴权变得简单、优雅—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-TokenSa-Token 的 Thymeleaf 插件sa-token-thymeleaf以「标签方言Tag Dialect」的形式让开发者直接在 Thymeleaf 模板中用sa:login、sa:hasRole、sa:hasPermission等属性标签控制页面元素的显隐并通过全局变量注入在页面中调用StpLogic的任意 API。读完本文你将完整掌握该插件的依赖引入、方言 Bean 注册、全部标签用法、页面调用 Sa-Token API 的配置方式与 IDE 代码提示技巧并理解标签显隐背后的源码实现与测试验证逻辑。一、插件定位标签方言是什么本插件的作用是让我们可以在 Thymeleaf 页面中使用 Sa-Token 相关 API俗称——标签方言。传统做法是在 Controller 中判断权限后把布尔值传入页面再用th:if控制显隐引入标签方言后权限逻辑直接下推到模板层模板自身即携带权限语义页面代码更内聚。插件源码位于 sa-token-plugin/sa-token-thymeleaf 模块核心只有三个文件SaTokenDialect.java方言主体继承 Thymeleaf 的AbstractProcessorDialect负责注册全部标签处理器SaTokenTagProcessor.java统一的属性标签处理器封装「判断不通过则移除元素」的行为Sa-Token-Dialect.xml方言元数据描述文件用于 IDE 代码提示。从 pom.xml 的依赖结构看该模块仅依赖sa-token-core与thymeleafthymeleaf为optional依赖即最终项目需自行保证已引入 Thymeleaf不绑定具体 Spring Boot 版本。二、引入依赖首先我们确保项目已经引入 Thymeleaf 依赖然后在此基础上继续添加sa-token-thymeleafMaven 方式!-- 在 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}版本统一取自 BOM 中的sa.top.version属性与sa-token-core保持同版本即可。三、注册标签方言对象在配置类中注册SaTokenDialectBeanThymeleaf 自动装配时会自动收集容器中所有IDialect类型 Bean 并挂到TemplateEngine上Configuration public class SaTokenConfigure { // Sa-Token 标签方言 (Thymeleaf版) Bean public SaTokenDialect getSaTokenDialect() { return new SaTokenDialect(); } }仓库中的完整示例见 SaTokenConfigure.java位于sa-token-demo-thymeleaf演示工程其注册方式与上文一致。结合源码 SaTokenDialect.java#L48-L63这里有两个值得了解的实现细节默认构造使用方言名sa、优先级1000并绑定StpUtil.stpLogic——即全局默认账号系统的StpLogic。这就是页面标签默认判断的是「默认账号登录态」的原因自定义构造SaTokenDialect(String name, int precedence, StpLogic stpLogic)允许传入自定义前缀、优先级与StpLogic实例。在多账号系统如StpUserUtil、StpAdminUtil场景下可以推断出通过注册多个不同名称的方言即可让不同页面方言前缀分别绑定不同账号体系。四、使用标签方言注册方言后即可在 Thymeleaf 页面中直接使用标签。标签作用于任意 HTML 元素属性值为需要匹配的角色或权限标识。4.1 登录判断h2标签方言测试页面/h2 p 登录之后才能显示 span sa:loginvalue/span /p p 不登录才能显示 span sa:notLoginvalue/span /p4.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 /p4.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 /p4.4 标签与底层 StpLogic 方法对照源码 SaTokenDialect.java#L69-L93 的getProcessors方法共注册了 13 个处理器12 个鉴权标签 1 个命名空间清理处理器。其中除文档列出的 10 个标签外源码还额外提供了lackRole、lackPermission两个别名标签Sa-Token-Dialect.xml 中标注为「未来版本可能废弃建议更换为 notRole / notPermission」。完整对照如下标签作用底层 StpLogic 调用sa:login登录后才显示stpLogic.isLogin()sa:notLogin未登录才显示! stpLogic.isLogin()sa:hasRole具有指定角色才显示stpLogic.hasRole(value)sa:hasRoleAnd同时具备多个角色才显示stpLogic.hasRoleAnd(toArray(value))sa:hasRoleOr具备其中一个角色即显示stpLogic.hasRoleOr(toArray(value))sa:notRole不具有指定角色才显示! stpLogic.hasRole(value)sa:lackRole同notRole别名建议弃用! stpLogic.hasRole(value)sa:hasPermission具有指定权限才显示stpLogic.hasPermission(value)sa:hasPermissionAnd同时具备多个权限才显示stpLogic.hasPermissionAnd(toArray(value))sa:hasPermissionOr具备其中一个权限即显示stpLogic.hasPermissionOr(toArray(value))sa:notPermission不具有指定权限才显示! stpLogic.hasPermission(value)sa:lackPermission同notPermission别名建议弃用! stpLogic.hasPermission(value)注意多值标签hasRoleAnd等的属性值以逗号分隔源码中的toArray方法SaTokenDialect.java#L100-L103基于SaFoxUtil.convertStringToList完成字符串到数组的转换可容忍前后空格且对null或空串返回空数组。五、调用 Sa-Token 相关 API以上标签方言可以满足大多数场景下的权限判断但有时我们仍需要在页面中更灵活地调用 Sa-Token 框架 API。做法是为 Thymeleaf 配置全局变量Configuration public class SaTokenConfigure{ // ... 其它代码 // 为 Thymeleaf 注入全局变量以便在页面中调用 Sa-Token 的方法 Autowired private void configureThymeleafStaticVars(ThymeleafViewResolver viewResolver) { viewResolver.addStaticVariable(stp, StpUtil.stpLogic); } }注意如果SaTokenConfigure继承了WebMvcConfigurer等类可能会造成循环依赖如果遇到请新建一个其他配置类完成此项配置。注册静态变量后即可在页面上直接调用StpLogic的 APIp调用 StpLogic 方法调用测试/p p th:if${stp.isLogin()} 从SaSession中取值 span th:text${stp.getSession().get(name)}/span /p由于addStaticVariable注入的是StpUtil.stpLogic对象引用页面中不仅可以调用stp.isLogin()还可以访问会话数据stp.getSession()、执行stp.getLoginId()等操作模板侧的可用能力等同于 Java 侧的StpLogic全集。演示工程 SaTokenConfigure.java 同时完成了方言注册与静态变量注入两项配置可整体参考。六、IDE 代码提示如果想在写标签属性时增加 IDE 代码提示只需在页面头部声明中加上对应的命名空间即可!DOCTYPE html html langzh xmlns:sahttp://www.thymeleaf.org/extras/sa-token head !-- 代码 -- /head body !-- 代码 -- /body /html该提示能力的依据来自插件内置的 Sa-Token-Dialect.xml它按 Thymeleaf 方言描述规范声明了prefixsa与namespace-urihttp://www.thymeleaf.org/extras/sa-token并为每个attribute-processor编写了中文文档说明如「登录之后才能显示元素」「同时具备多个角色才能显示元素」等IDE 正是解析这份元数据来提供标签补全与悬浮提示。同时SaTokenDialect在处理器集合中注册了StandardXmlNsTagProcessorSaTokenDialect.java#L89-L90作用是在渲染阶段把html标签上的xmlns:sa命名空间声明移除保证输出的 HTML 干净不会把仅用于 IDE 提示的命名空间泄漏到浏览器端。七、源码原理标签如何决定元素显隐所有标签共用同一个处理器 SaTokenTagProcessor.java其行为由两部分构成构造参数SaTokenTagProcessor.java#L37-L48仅在 HTML 模板模式下生效、匹配任意标签名不限定span/div、对属性名应用方言前缀、处理器内部优先级10000且处理完成后移除该属性本身removeMatchedAttributeAfterProcesstrue处理逻辑SaTokenTagProcessor.java#L50-L59Override protected void doProcess( final ITemplateContext context, final IProcessableElementTag tag, final AttributeName attributeName, final String attributeValue, final IElementTagStructureHandler structureHandler) { // 执行表达式返回值为false则删除这个标签 if( ! this.fun.apply(attributeValue)) { structureHandler.removeElement(); } }这里的关键点判断不通过时调用的是structureHandler.removeElement()——即整个元素含内容从渲染结果中被移除而不是用 CSS 隐藏。这意味着没有权限的用户在页面源码中根本看不到受保护的元素内容模板层判断因此仅用于 UI 收敛真正的安全边界仍应由路由拦截或接口鉴权承担。另一个边界行为是未登录场景hasRole、hasPermission等标签在未登录时整体隐藏。StpLogic的hasRole等方法在内部捕获未登录异常并返回false测试用例hasRoleTag_hiddenWhenNotLogin对此有明确断言见下文。八、测试用例如何用真实引擎验证标签行为插件的测试类 SaTokenDialectTest.java 给出了可复用的验证思路通过SaTokenContextMockUtil.setMockContext构造模拟请求上下文用匿名StpInterface注入角色与权限数据源按需调用stpLogic.login(10001)设置登录态最后用真实TemplateEngineStringTemplateResolver渲染模板字符串并断言输出。几个代表性用例hasRoleTag_rendersOrRemovesdiv sa:hasRoleadmin在持有admin角色时渲染为divADMIN-AREA/div无角色时输出为空串——直接印证了「不通过则整元素移除」的行为hasRoleAndTag_requiresAllRoles/hasRoleOrTag_requiresAnyRole分别验证 And 语义要求全部满足、Or 语义满足其一即可toArray_splitsAndTrims验证 admin , user 被正确切分为[admin,user]null与空串返回空数组getProcessors_registers13Processors锁定处理器数量为 1312 个鉴权标签 1 个命名空间处理器可作为插件能力面的回归基线。SaTokenTagProcessorTest.java 则在更细粒度上验证了处理器契约断言回调函数收到的正是模板中写的属性值funReceivesAttributeValue以及返回true保留元素、返回false移除元素funTrue_keepsElement/funFalse_removesElement。九、小结sa-token-thymeleaf插件通过一个SaTokenDialectBean 即可让 Thymeleaf 模板获得 12 种登录态/角色/权限判断标签并可用静态变量方式在页面中直接调用StpLogic全量 API。使用时注意三点多值标签用逗号分隔且容忍空格配置类若同时继承WebMvcConfigurer需注意静态变量注入的循环依赖问题lackRole/lackPermission属别名标签新代码建议直接使用notRole/notPermission。模板层显隐判断不产生源码级保密效果生产系统仍应以路由拦截和接口鉴权作为权限控制的最终防线。【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架让鉴权变得简单、优雅—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Sa-Token 集成 Thymeleaf 标签方言：在页面模板中实现登录态与权限判断
Sa-Token 集成 Thymeleaf 标签方言在页面模板中实现登录态与权限判断【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架让鉴权变得简单、优雅—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-TokenSa-Token 的 Thymeleaf 插件sa-token-thymeleaf以「标签方言Tag Dialect」的形式让开发者直接在 Thymeleaf 模板中用sa:login、sa:hasRole、sa:hasPermission等属性标签控制页面元素的显隐并通过全局变量注入在页面中调用StpLogic的任意 API。读完本文你将完整掌握该插件的依赖引入、方言 Bean 注册、全部标签用法、页面调用 Sa-Token API 的配置方式与 IDE 代码提示技巧并理解标签显隐背后的源码实现与测试验证逻辑。一、插件定位标签方言是什么本插件的作用是让我们可以在 Thymeleaf 页面中使用 Sa-Token 相关 API俗称——标签方言。传统做法是在 Controller 中判断权限后把布尔值传入页面再用th:if控制显隐引入标签方言后权限逻辑直接下推到模板层模板自身即携带权限语义页面代码更内聚。插件源码位于 sa-token-plugin/sa-token-thymeleaf 模块核心只有三个文件SaTokenDialect.java方言主体继承 Thymeleaf 的AbstractProcessorDialect负责注册全部标签处理器SaTokenTagProcessor.java统一的属性标签处理器封装「判断不通过则移除元素」的行为Sa-Token-Dialect.xml方言元数据描述文件用于 IDE 代码提示。从 pom.xml 的依赖结构看该模块仅依赖sa-token-core与thymeleafthymeleaf为optional依赖即最终项目需自行保证已引入 Thymeleaf不绑定具体 Spring Boot 版本。二、引入依赖首先我们确保项目已经引入 Thymeleaf 依赖然后在此基础上继续添加sa-token-thymeleafMaven 方式!-- 在 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}版本统一取自 BOM 中的sa.top.version属性与sa-token-core保持同版本即可。三、注册标签方言对象在配置类中注册SaTokenDialectBeanThymeleaf 自动装配时会自动收集容器中所有IDialect类型 Bean 并挂到TemplateEngine上Configuration public class SaTokenConfigure { // Sa-Token 标签方言 (Thymeleaf版) Bean public SaTokenDialect getSaTokenDialect() { return new SaTokenDialect(); } }仓库中的完整示例见 SaTokenConfigure.java位于sa-token-demo-thymeleaf演示工程其注册方式与上文一致。结合源码 SaTokenDialect.java#L48-L63这里有两个值得了解的实现细节默认构造使用方言名sa、优先级1000并绑定StpUtil.stpLogic——即全局默认账号系统的StpLogic。这就是页面标签默认判断的是「默认账号登录态」的原因自定义构造SaTokenDialect(String name, int precedence, StpLogic stpLogic)允许传入自定义前缀、优先级与StpLogic实例。在多账号系统如StpUserUtil、StpAdminUtil场景下可以推断出通过注册多个不同名称的方言即可让不同页面方言前缀分别绑定不同账号体系。四、使用标签方言注册方言后即可在 Thymeleaf 页面中直接使用标签。标签作用于任意 HTML 元素属性值为需要匹配的角色或权限标识。4.1 登录判断h2标签方言测试页面/h2 p 登录之后才能显示 span sa:loginvalue/span /p p 不登录才能显示 span sa:notLoginvalue/span /p4.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 /p4.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 /p4.4 标签与底层 StpLogic 方法对照源码 SaTokenDialect.java#L69-L93 的getProcessors方法共注册了 13 个处理器12 个鉴权标签 1 个命名空间清理处理器。其中除文档列出的 10 个标签外源码还额外提供了lackRole、lackPermission两个别名标签Sa-Token-Dialect.xml 中标注为「未来版本可能废弃建议更换为 notRole / notPermission」。完整对照如下标签作用底层 StpLogic 调用sa:login登录后才显示stpLogic.isLogin()sa:notLogin未登录才显示! stpLogic.isLogin()sa:hasRole具有指定角色才显示stpLogic.hasRole(value)sa:hasRoleAnd同时具备多个角色才显示stpLogic.hasRoleAnd(toArray(value))sa:hasRoleOr具备其中一个角色即显示stpLogic.hasRoleOr(toArray(value))sa:notRole不具有指定角色才显示! stpLogic.hasRole(value)sa:lackRole同notRole别名建议弃用! stpLogic.hasRole(value)sa:hasPermission具有指定权限才显示stpLogic.hasPermission(value)sa:hasPermissionAnd同时具备多个权限才显示stpLogic.hasPermissionAnd(toArray(value))sa:hasPermissionOr具备其中一个权限即显示stpLogic.hasPermissionOr(toArray(value))sa:notPermission不具有指定权限才显示! stpLogic.hasPermission(value)sa:lackPermission同notPermission别名建议弃用! stpLogic.hasPermission(value)注意多值标签hasRoleAnd等的属性值以逗号分隔源码中的toArray方法SaTokenDialect.java#L100-L103基于SaFoxUtil.convertStringToList完成字符串到数组的转换可容忍前后空格且对null或空串返回空数组。五、调用 Sa-Token 相关 API以上标签方言可以满足大多数场景下的权限判断但有时我们仍需要在页面中更灵活地调用 Sa-Token 框架 API。做法是为 Thymeleaf 配置全局变量Configuration public class SaTokenConfigure{ // ... 其它代码 // 为 Thymeleaf 注入全局变量以便在页面中调用 Sa-Token 的方法 Autowired private void configureThymeleafStaticVars(ThymeleafViewResolver viewResolver) { viewResolver.addStaticVariable(stp, StpUtil.stpLogic); } }注意如果SaTokenConfigure继承了WebMvcConfigurer等类可能会造成循环依赖如果遇到请新建一个其他配置类完成此项配置。注册静态变量后即可在页面上直接调用StpLogic的 APIp调用 StpLogic 方法调用测试/p p th:if${stp.isLogin()} 从SaSession中取值 span th:text${stp.getSession().get(name)}/span /p由于addStaticVariable注入的是StpUtil.stpLogic对象引用页面中不仅可以调用stp.isLogin()还可以访问会话数据stp.getSession()、执行stp.getLoginId()等操作模板侧的可用能力等同于 Java 侧的StpLogic全集。演示工程 SaTokenConfigure.java 同时完成了方言注册与静态变量注入两项配置可整体参考。六、IDE 代码提示如果想在写标签属性时增加 IDE 代码提示只需在页面头部声明中加上对应的命名空间即可!DOCTYPE html html langzh xmlns:sahttp://www.thymeleaf.org/extras/sa-token head !-- 代码 -- /head body !-- 代码 -- /body /html该提示能力的依据来自插件内置的 Sa-Token-Dialect.xml它按 Thymeleaf 方言描述规范声明了prefixsa与namespace-urihttp://www.thymeleaf.org/extras/sa-token并为每个attribute-processor编写了中文文档说明如「登录之后才能显示元素」「同时具备多个角色才能显示元素」等IDE 正是解析这份元数据来提供标签补全与悬浮提示。同时SaTokenDialect在处理器集合中注册了StandardXmlNsTagProcessorSaTokenDialect.java#L89-L90作用是在渲染阶段把html标签上的xmlns:sa命名空间声明移除保证输出的 HTML 干净不会把仅用于 IDE 提示的命名空间泄漏到浏览器端。七、源码原理标签如何决定元素显隐所有标签共用同一个处理器 SaTokenTagProcessor.java其行为由两部分构成构造参数SaTokenTagProcessor.java#L37-L48仅在 HTML 模板模式下生效、匹配任意标签名不限定span/div、对属性名应用方言前缀、处理器内部优先级10000且处理完成后移除该属性本身removeMatchedAttributeAfterProcesstrue处理逻辑SaTokenTagProcessor.java#L50-L59Override protected void doProcess( final ITemplateContext context, final IProcessableElementTag tag, final AttributeName attributeName, final String attributeValue, final IElementTagStructureHandler structureHandler) { // 执行表达式返回值为false则删除这个标签 if( ! this.fun.apply(attributeValue)) { structureHandler.removeElement(); } }这里的关键点判断不通过时调用的是structureHandler.removeElement()——即整个元素含内容从渲染结果中被移除而不是用 CSS 隐藏。这意味着没有权限的用户在页面源码中根本看不到受保护的元素内容模板层判断因此仅用于 UI 收敛真正的安全边界仍应由路由拦截或接口鉴权承担。另一个边界行为是未登录场景hasRole、hasPermission等标签在未登录时整体隐藏。StpLogic的hasRole等方法在内部捕获未登录异常并返回false测试用例hasRoleTag_hiddenWhenNotLogin对此有明确断言见下文。八、测试用例如何用真实引擎验证标签行为插件的测试类 SaTokenDialectTest.java 给出了可复用的验证思路通过SaTokenContextMockUtil.setMockContext构造模拟请求上下文用匿名StpInterface注入角色与权限数据源按需调用stpLogic.login(10001)设置登录态最后用真实TemplateEngineStringTemplateResolver渲染模板字符串并断言输出。几个代表性用例hasRoleTag_rendersOrRemovesdiv sa:hasRoleadmin在持有admin角色时渲染为divADMIN-AREA/div无角色时输出为空串——直接印证了「不通过则整元素移除」的行为hasRoleAndTag_requiresAllRoles/hasRoleOrTag_requiresAnyRole分别验证 And 语义要求全部满足、Or 语义满足其一即可toArray_splitsAndTrims验证 admin , user 被正确切分为[admin,user]null与空串返回空数组getProcessors_registers13Processors锁定处理器数量为 1312 个鉴权标签 1 个命名空间处理器可作为插件能力面的回归基线。SaTokenTagProcessorTest.java 则在更细粒度上验证了处理器契约断言回调函数收到的正是模板中写的属性值funReceivesAttributeValue以及返回true保留元素、返回false移除元素funTrue_keepsElement/funFalse_removesElement。九、小结sa-token-thymeleaf插件通过一个SaTokenDialectBean 即可让 Thymeleaf 模板获得 12 种登录态/角色/权限判断标签并可用静态变量方式在页面中直接调用StpLogic全量 API。使用时注意三点多值标签用逗号分隔且容忍空格配置类若同时继承WebMvcConfigurer需注意静态变量注入的循环依赖问题lackRole/lackPermission属别名标签新代码建议直接使用notRole/notPermission。模板层显隐判断不产生源码级保密效果生产系统仍应以路由拦截和接口鉴权作为权限控制的最终防线。【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架让鉴权变得简单、优雅—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
