跳到主要内容

@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 来使用其他注解。

构造函数绑定支持将 ListMap 和数组参数从单个字符串转换而来,例如逗号分隔的列表,或者基于索引键,如 accounts[2].nameaccount[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 ValidationSpring 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 注解方法参数。