Spring Boot+Thymeleaf POST提交含对象列表实体时列表为null问题

这种带嵌套列表的表单绑定问题我之前也踩过好几次坑，核心原因基本都是Spring MVC无法正确识别列表参数的绑定规则，或者Thymeleaf渲染时没生成正确的表单字段名。咱们一步步排查解决：

1. 先确保实体类的列表字段已正确初始化 #

• 你的主实体类中，List<RelacionMaquinaModeloGastoIndirecto>字段必须提前初始化，不能让它处于null状态，否则Spring没办法往空列表里添加元素。示例代码：

  public class TuEntidadPrincipal {
      // 其他普通字段
      private String descripcion;
      
      // 必须初始化列表，Spring才能自动填充元素
      private List<RelacionMaquinaModeloGastoIndirecto> relaciones = new ArrayList<>();
      
      // 注意：必须提供标准的getter/setter方法，命名要规范（比如getRelaciones()、setRelaciones()）
      public List<RelacionMaquinaModeloGastoIndirecto> getRelaciones() {
          return relaciones;
      }
  
      public void setRelaciones(List<RelacionMaquinaModeloGastoIndirecto> relaciones) {
          this.relaciones = relaciones;
      }
  }
  

• 另外，RelacionMaquinaModeloGastoIndirecto类必须包含无参构造函数，Spring需要通过它来实例化列表中的每个对象。

2. 修正Thymeleaf表单的列表绑定语法 #

这是最容易出错的环节，Thymeleaf绑定列表元素必须使用索引下标，而且要注意表达式的写法：

• 在表单循环列表时，用th:each遍历列表的同时，借助stat.index获取元素索引，并且在th:field中用__${stat.index}__来动态生成绑定路径。示例代码：

  <form th:object="${tuEntidadPrincipal}" method="post">
      <!-- 普通字段绑定 -->
      <div>
          <label>描述：</label>
          <input type="text" th:field="*{descripcion}" />
      </div>
  
      <!-- 列表元素的循环绑定 -->
      <div th:each="relacion, stat : *{relaciones}">
          <div>
              <label>机型ID：</label>
              <input type="text" th:field="*{relaciones[__${stat.index}__].maquinaModelo.id}" />
          </div>
          <div>
              <label>间接费用ID：</label>
              <input type="text" th:field="*{relaciones[__${stat.index}__].gastoIndirecto.id}" />
          </div>
          <!-- 其他列表字段的绑定 -->
      </div>
  
      <button type="submit">提交表单</button>
  </form>
  

• 重点提醒：__${stat.index}__的双下划线不能省略，这是Thymeleaf的特殊语法，用来在OGNL表达式中插入变量值，最终生成类似relaciones[0].maquinaModelo.id的表单name属性，Spring MVC才能正确识别列表元素。

3. 检查控制器的参数接收方式 #

• 确保控制器方法中使用正确的注解绑定实体，表单提交应该用@ModelAttribute（或者直接省略，Spring会自动绑定），不要误用@RequestBody（那是用来接收JSON格式请求的）：

  @PostMapping("/guardar")
  public String guardarEntidad(@ModelAttribute TuEntidadPrincipal tuEntidad) {
      // 这里tuEntidad的relaciones列表应该就能正常获取到值了
      tuServicio.guardar(tuEntidad);
      return "redirect:/lista";
  }
  

4. 额外排查点 #

• 检查表单的enctype属性：如果没有文件上传需求，不要设置enctype="multipart/form-data"，默认的application/x-www-form-urlencoded即可，否则Spring MVC无法正确解析表单参数。
• 查看浏览器请求：提交表单时，打开开发者工具的网络面板，查看Form Data中是否有类似relaciones[0].maquinaModelo.id=123的参数，如果没有，说明Thymeleaf渲染时没生成正确的name属性，右键检查页面元素确认input的name值是否符合预期。

内容的提问来源于stack exchange，提问作者Legna