可遍历的值类型

在 Thymeleaf 中，java.util.List 并非唯一可用于 th:each 遍历的类型。th:each 支持一整套丰富的可遍历对象，具体包括以下几类：

1. 核心可遍历类型列表

可遍历对象类型	说明
实现 java.util.Iterable 的对象	最基础的可遍历类型（List、Set、Collection 等都实现了该接口），是最常用的遍历场景
实现 java.util.Enumeration 的对象	枚举类型（如 Vector.elements() 返回的枚举），遍历逻辑与 Iterable 一致
实现 java.util.Iterator 的对象	迭代器类型，遍历过程中直接读取迭代器返回的值，无需将所有值缓存到内存（适合大数据量遍历）
实现 java.util.Map 的对象	遍历 Map 时，迭代变量的类型为 java.util.Map.Entry（包含 key 和 value 属性）
实现 java.util.stream.Stream 的对象	流类型，遍历方式与 Iterable 一致（注意 Stream 只能遍历一次）
任意数组	包括基本类型数组（如 int[]）和对象数组（如 String[]）
其他任意对象	若对象不属于上述类型，会被当作仅包含自身的单元素列表处理（即只会遍历一次）

2. 典型用法示例

（1）遍历 Map（核心高频场景）

<!-- 假设上下文有 ${userInfo}（Map<String, String> 类型） -->
<div th:each="entry : ${userInfo}">
  <span th:text="${entry.key}">键</span>: 
  <span th:text="${entry.value}">值</span>
</div>

• 迭代变量 entry 是 Map.Entry 类型，可通过 entry.key 获取键，entry.value 获取值。

（2）遍历数组

<!-- 假设上下文有 ${tags}（String[] 类型） -->
<ul>
  <li th:each="tag : ${tags}" th:text="${tag}">标签占位符</li>
</ul>

（3）遍历单个非集合对象（特殊场景）

<!-- 假设上下文有 ${singleProduct}（单个 Product 对象，非集合） -->
<div th:each="prod : ${singleProduct}">
  <p th:text="${prod.name}">产品名称</p>
</div>

• 此时 th:each 会把 singleProduct 当作只有一个元素的列表，最终只会渲染一次 <div>。

（4）遍历 Stream（注意一次性特性）

<!-- 假设上下文有 ${productStream}（Stream<Product> 类型） -->
<table>
  <tr th:each="prod : ${productStream}">
    <td th:text="${prod.name}">产品名</td>
  </tr>
</table>

• 注意：Stream 只能遍历一次，遍历后会被关闭，再次使用会抛出异常。

3. 关键注意事项

• Iterator/Stream 的一次性：Iterator 和 Stream 都是“一次性”的，遍历完成后无法再次遍历；
• Map 遍历的顺序：默认按 Map 的自然遍历顺序（如 HashMap 无序，LinkedHashMap 按插入顺序）；
• 单对象遍历的意义：将单个对象当作列表遍历，可统一模板写法（比如无论返回单个/多个数据，都用 th:each 渲染）。

总结

1. Thymeleaf 的 th:each 支持 Iterable、Enumeration、Iterator、Map、Stream、数组等多种可遍历类型，覆盖绝大多数开发场景；
2. 遍历 Map 时迭代变量为 Map.Entry，可通过 key/value 获取键值对；
3. 非可遍历对象会被当作单元素列表处理，Iterator/Stream 遍历后无法复用，需注意使用场景。