跳到主要内容

@ModelAttribute

DeepSeek V3 中英对照 @ModelAttribute

@ModelAttribute 方法参数注解将表单数据、查询参数、URI 路径变量和请求头绑定到模型对象上。例如：

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@ModelAttribute Pet pet) { } 1
java

  • 绑定到 Pet 的实例。

表单数据和查询参数优先于 URI 变量和头部信息，只有在它们不覆盖同名请求参数的情况下才会包含 URI 变量和头部信息。头部名称中的短横线会被移除。

Pet 实例可能是：

  • 从模型中访问，该模型可能已通过Model添加。

  • 如果模型属性在类级别的@SessionAttributes中列出，则从 HTTP 会话中访问。

  • 通过默认构造函数实例化。

  • 通过“主构造函数”实例化，参数与 Servlet 请求参数匹配。参数名称通过字节码中运行时保留的参数名称确定。

默认情况下，构造函数和属性数据绑定都会被应用。然而，模型对象的设计需要仔细考虑，出于安全原因，建议使用专门为 Web 绑定定制的对象，或者仅应用构造函数绑定。如果必须使用属性绑定，则应设置 allowedFields 模式以限制可以设置的属性。有关此内容的更多细节和示例配置，请参阅模型设计。

在使用构造器绑定时，你可以通过 @BindParam 注解来自定义请求参数的名称。例如：

class Account {

    private final String firstName;

    public Account(@BindParam("first-name") String firstName) {
        this.firstName = firstName;
    }
}
java
备注

@BindParam 也可以放在与构造函数参数对应的字段上。虽然 @BindParam 是开箱即用的，但你也可以通过为 DataBinder 设置 DataBinder.NameResolver 来使用其他注解。

构造函数绑定支持将 List、Map 和数组参数从单个字符串转换而来，例如逗号分隔的列表，或者基于索引键，如 accounts[2].name 或 account[KEY].name。

与 Spring MVC 不同，WebFlux 支持模型中的响应式类型，例如 Mono<Account>。你可以声明带有或不带响应式类型包装器的 @ModelAttribute 参数，它将根据实际值进行解析。

如果数据绑定导致错误，默认情况下会抛出 WebExchangeBindException，但你也可以在 @ModelAttribute 旁边紧挨着添加一个 BindingResult 参数，以便在控制器方法中处理这些错误。例如：

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@ModelAttribute("pet") Pet pet, BindingResult result) { 1
    if (result.hasErrors()) {
        return "petForm";
    }
    // ...
}
java

  • 添加一个 BindingResult。

要使用 BindingResult 参数，你必须在它之前声明 @ModelAttribute 参数，并且不能使用响应式类型包装器。如果你想使用响应式类型，可以直接通过它来处理错误。例如：

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public Mono<String> processSubmit(@Valid @ModelAttribute("pet") Mono<Pet> petMono) {
    return petMono
        .flatMap(pet -> {
            // ...
        })
        .onErrorResume(ex -> {
            // ...
        });
}
java

你可以通过在数据绑定后添加 jakarta.validation.Valid 注解或 Spring 的 @Validated 注解来自动应用验证（参见 Bean Validation 和 Spring validation）。例如：

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@Valid @ModelAttribute("pet") Pet pet, BindingResult result) { 1
    if (result.hasErrors()) {
        return "petForm";
    }
    // ...
}
java

  • 在模型属性参数上使用 @Valid。

如果方法验证适用，因为其他参数带有 @Constraint 注解，那么将会抛出 HandlerMethodValidationException 异常。请参阅控制器方法部分的验证。

提示

使用 @ModelAttribute 是可选的。默认情况下，任何不是简单值类型的参数（由 BeanUtils#isSimpleProperty 确定）并且 未被任何其他参数解析器解析的参数，都将被视为隐式的 @ModelAttribute。

注意

在使用 GraalVM 编译为原生镜像时，上述隐式的 @ModelAttribute 支持无法正确推断相关数据绑定的反射提示。因此，建议在使用 GraalVM 原生镜像时，显式地使用 @ModelAttribute 注解方法参数。