本文详解 Thymeleaf 中绑定动态列表（List）失败的常见原因及解决方案，重点解决因使用 record 类型、错误混用 Thymeleaf 指令与原生 HTML 属性导致的 null 绑定问题。
本文详解 thymeleaf 中绑定动态列表（list
在 Spring Boot + Thymeleaf 应用中，动态添加表单项并批量绑定到 List<T> 是高频需求，但实践中常因类型设计与模板语法不匹配导致后端接收为 null。你遇到的 optionRequests 为空，根本原因在于以下两点：
✅ 核心问题解析
-
Record 类型不支持运行时反射绑定
Thymeleaf 的 @ModelAttribute 和 th:field 依赖 JavaBean 规范（即 public 无参构造器 + getter/setter）。而 record 是不可变类型，虽自动生成 getXXX() 方法，但缺少符合 Spring DataBinder 要求的 setter 方法，且其字段默认为 final，导致 Spring 无法通过反射注入值。
✅ 正确做法：将 FormRequest 和 OptionRequest 改为普通 class，显式声明私有字段，并提供完整 getter/setter（Lombok @Data 可大幅简化）：
// 替换 record 为 class
@Data // Lombok 注解（需引入 lombok）
public class FormRequest {
private String title;
private List<OptionRequest> optionRequests = new ArrayList<>();
private MultipartFile imgFile;
}
@Data
public class OptionRequest {
private String optionName;
private Integer addValue;
private String method;
private String material;
}-
JavaScript 动态生成的 input 混用了 Thymeleaf 指令与原生属性
你在 JS 中拼接了 th:field、th:name 等服务端指令：$("<input type='hidden' th:field='${example.optionRequests[" + idx + "].optionName}' ...>")⚠️ 这是严重错误：*Thymeleaf 指令仅在服务端渲染阶段生效，JS 在浏览器运行时无法解析 `th:` 属性**，最终生成的 HTML 中这些属性被忽略或残留为无效字符串，导致 Spring 无法识别绑定路径。
✅ 正确做法：完全使用标准 HTML name 属性，严格遵循 Spring 的 Indexed Collection Binding 规则：
- 列表索引必须从 0 开始连续；
- name 值格式为 property[index].field（如 optionRequests[0].optionName）；
- 所有字段（包括空项）均需存在，否则 Spring 截断后续索引。
修改 JS 中的拼接逻辑（移除所有 th:*，仅保留 name 和 value）：
function addOptionRow() {
const table = document.getElementById('optionTable');
const newRow = table.insertRow();
const idx = $('#optionTable tbody tr').length; // 注意：只统计 tbody 内行，避免表头干扰
// 渲染显示单元格（同原逻辑）
const cells = ['optionName', 'addValue', 'method', 'material'].map(id =>
newRow.insertCell().innerText = $(`#${id}`).val()
);
newRow.insertCell().innerHTML = "<button class='btn btn-danger btn-sm' onclick='removeRow(this)'>X</button>";
// ✅ 关键：动态添加隐藏域，使用标准 name 属性（非 th:field！）
$("#example-form").append($(`<input type='hidden' name='optionRequests[${idx}].optionName' value='${$('#optionName').val()}'>`));
$("#example-form").append($(`<input type='hidden' name='optionRequests[${idx}].addValue' value='${$('#addValue').val()}'>`));
$("#example-form").append($(`<input type='hidden' name='optionRequests[${idx}].method' value='${$('#method').val()}'>`));
$("#example-form").append($(`<input type='hidden' name='optionRequests[${idx}].material' value='${$('#material').val()}'>`));
// 清空模态框输入
$('#optionName, #addValue, #method, #material').val('');
$('#optionModal').modal('hide');
}? 补充关键注意事项
- 初始化列表必须非 null：Controller 中 model.addAttribute("example", new FormRequest(...)) 必须确保 optionRequests 字段已初始化为 new ArrayList<>()，否则 Spring 遇到 null 列表会直接跳过绑定。
- 表单 enctype 兼容性：当前使用 enctype="multipart/form-data"，需确认 MultipartFile 字段能正常接收；若仅文本字段，可移除此属性以简化调试。
- Thymeleaf 模板无需动态生成字段：th:field 仅适用于服务端预渲染的静态表单。动态行必须由 JS 控制，且严格遵守 name 命名规范。
- 调试技巧：提交前在浏览器开发者工具中检查 <form> 内实际生成的 hidden input，确认 name 属性是否形如 optionRequests[0].optionName，且索引连续无跳变。
遵循以上改造后，Spring 将能正确解析并绑定 List<OptionRequest>，@ModelAttribute 参数中的 optionRequests 不再为 null。记住：Thymeleaf 是服务端模板引擎，JS 是客户端行为——二者职责分离，切勿在 JS 中试图“模拟” Thymeleaf 指令。
