Thymeleaf中文网

深色模式

th:assert：模板内断言校验 ​

th:assert 属性用于在模板中定义断言表达式列表（多个表达式用逗号分隔），Thymeleaf 会执行这些表达式并要求每一个的结果都为 true；如果任意一个表达式结果为 false，会直接抛出异常，从而实现模板内的参数/变量校验。

html
<!-- 断言：onevar 非空，且 twovar 不等于 43 -->
<div th:assert="${onevar},(${twovar} != 43)">
  内容区域
</div>

th:assert 尤其适合在带参数的片段中校验入参的合法性，避免片段因参数异常导致渲染错误：

html
<!-- 定义头部片段，要求 title 参数非空 -->
<header th:fragment="contentheader(title)" th:assert="${!#strings.isEmpty(title)}">
  <h1 th:text="${title}">页面标题</h1>
</header>

<!-- 调用片段时，若传递空 title 会触发断言异常 -->
<div th:replace="::contentheader(title='')"></div> <!-- 抛出异常 -->
<div th:replace="::contentheader(title=${null})"></div> <!-- 抛出异常 -->
<div th:replace="::contentheader(title='产品列表')"></div> <!-- 正常渲染 -->

进阶用法：多条件联合校验 ​

可同时校验多个参数/变量，覆盖更复杂的规则：

html
<!-- 片段接收 price 参数，断言：price 非空、大于0、且为数字 -->
<div th:fragment="price-card(price)" 
     th:assert="${price}, ${price > 0}, ${#numbers.isNumber(price)}">
  <p th:text="'价格：' + ${price}">价格：0.00</p>
</div>

关键说明 ​

  • 异常类型：断言失败时抛出 TemplateProcessingException，可在后端捕获并处理（如返回错误页面）；
  • 作用域：th:assert 作用于当前标签及其子元素，仅在模板渲染到该标签时执行；
  • 调试价值：断言能快速定位模板中变量/参数的异常（比如空值、非法值），避免因数据异常导致模板渲染出错误内容；
  • 生产环境：建议保留核心断言（如必填参数校验），帮助快速排查线上问题；非核心断言可根据需求关闭（通过模板引擎配置）。

实用示例：用户信息片段校验 ​

html
<!-- 片段要求 user 参数非空，且 user.id 为数字、user.name 非空 -->
<div th:fragment="user-info(user)"
     th:assert="${user}, ${#numbers.isNumber(user.id)}, ${!#strings.isEmpty(user.name)}">
  <p>ID：<span th:text="${user.id}">1</span></p>
  <p>姓名：<span th:text="${user.name}">张三</span></p>
</div>

总结 ​

  1. th:assert 用于模板内断言校验，多个表达式用逗号分隔，需全部为 true 否则抛异常；
  2. 核心用途是校验片段参数的合法性（如非空、格式正确），避免因异常数据导致模板渲染错误；
  3. 断言能提升模板的健壮性，帮助快速定位变量/参数异常，是模板调试和生产环境问题排查的实用工具。