提交Thymeleaf表单后Controller处理方法未被调用问题排查

代码与场景说明 #

表单实体类 #

@NoArgsConstructor
@AllArgsConstructor
@Data
public class FormDto {
    private UUID id;
    private Set<UUID> items;
}

Thymeleaf表单（checkbox_form.html） #

<form action="#" th:action="@{/roles/checkboxForm}" th:object="${dto}" method="post">

    <fieldset>
        <input type="hidden" th:field="*{roleId}" th:value="*{roleId}" />

        <div class="row" th:each="user : ${users}">
            <div class="col">
                <input type="checkbox" th:field="*{items}" th:value="${user.id}" th:id="${user.id}"/>
                <label th:for="${user.id}" th:text="${user.lastName}"></label>
            </div>
        </div>

        <hr/>

        <button type="submit" name="action" value="save">add</button>
        <button type="submit" name="action" value="cancel">cancel</button>

    </fieldset>
</form>

Controller代码 #

@GetMapping(value = "/list")
public String getCheckboxForm(Model model) {

    var users = userService.getAllUsers();

    model.addAttribute("dto", new RoleAddUsersDto());
    model.addAttribute("users", users);

    return "checkbox_form";
}

@PostMapping(value = "/checkboxForm")
public String handleCheckboxFormSubmit(@ModelAttribute("dto") RoleAddUsersDto dto,
                                       BindingResult bindingResult,
                                       Model model) {
    return "home";
}

提交的原始表单数据 #

id=0186d463-8661-4c25-bd5b-4fd75d3297ff&_items=on&_items=on&items=01d71d78-6697-41c1-a2ab-2c04d4dad576&_items=on&items=08d71d78-6697-41c1-a2ab-2c04d4dad576&_items=on&_items=on&_items=on&_items=on&_items=on&_items=on&_items=on&_items=on&_items=on&_items=on&_items=on&_items=on&_items=on&_items=on&_items=on&_items=on&_items=on&action=submit

提交表单后，handleCheckboxFormSubmit方法始终未被调用，以下是排查方向：

排查要点 #

1. 请求路径匹配问题 #

检查Controller类上的@RequestMapping注解：表单提交的路径是/roles/checkboxForm，如果Controller类上没有添加@RequestMapping("/roles")，那么POST方法的实际映射路径是/checkboxForm，和表单提交路径不匹配，会导致404，方法自然不会执行。

2. 实体类与Controller参数类不一致 #

代码中实体类定义的是FormDto，但Controller的GET方法实例化的是RoleAddUsersDto，POST方法接收的也是RoleAddUsersDto。确认这两个类是否为同一类（比如FormDto是RoleAddUsersDto的别名），如果是不同类且字段不匹配，会导致数据绑定失败，甚至请求无法正确映射。

3. 表单字段与实体类字段不匹配 #

表单中有隐藏字段th:field="*{roleId}"，但FormDto（或RoleAddUsersDto）中没有roleId字段，这会触发Spring的数据绑定错误，BindingResult会存在错误，若未处理可能导致请求无法进入方法。检查实体类是否遗漏了roleId字段，或者表单中是否写错了字段名。

4. UUID类型的参数转换问题 #

实体类中items是Set<UUID>类型，Spring默认可能无法直接将表单提交的字符串类型UUID转换为UUID对象。可以添加自定义的Converter<String, UUID>，或者确认Spring Boot自动配置是否支持UUID转换（Spring Boot 2.x及以上通常默认支持，但需检查依赖完整性）。

5. 表单提交的参数异常 #

观察提交的表单数据中action=submit，但表单按钮的value是save和cancel，这可能是前端JS修改了提交参数，或者按钮的name/value被错误修改。虽然这一般不会导致方法不被调用，但如果Controller方法中添加了@RequestParam("action")限制参数值，会导致请求不匹配，可检查方法是否有相关限制。

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