|
对于最新稳定版本，请使用 Spring Framework 7.0.6！ |
@ModelAttribute
你可以使用 @ModelAttribute 注解标注方法参数，以访问模型中的属性；如果该属性不存在，则会自动实例化。模型属性还会被 HTTP Servlet 请求参数中与字段名称相匹配的值覆盖。这一过程称为数据绑定（data binding），它可以避免你手动解析和转换各个查询参数及表单字段。以下示例展示了如何实现这一点：
-
Java
-
Kotlin
@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@ModelAttribute Pet pet) { (1)
// method logic...
}| 1 | 绑定一个 Pet 的实例。 |
@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
fun processSubmit(@ModelAttribute pet: Pet): String { (1)
// method logic...
}| 1 | 绑定一个 Pet 的实例。 |
上面的 Pet 实例通过以下方式之一获取：
-
从模型中检索，该模型可能已由@ModelAttribute 方法添加。
-
如果模型属性在类级别的
@SessionAttributes注解中列出，则从 HTTP 会话中检索。 -
通过一个
Converter获取，其中模型属性名称与请求值（例如路径变量或请求参数）的名称相匹配（参见下一个示例）。 -
使用其默认构造函数进行实例化。
-
通过一个“主构造函数”进行实例化，该构造函数的参数与 Servlet 请求参数相匹配。参数名称通过 JavaBeans 的
@ConstructorProperties注解或字节码中保留的运行时参数名称来确定。
使用 @ModelAttribute 方法 来提供模型属性，或依赖框架自动创建模型属性的另一种替代方案是，让一个 Converter<String, T> 来提供该实例。当模型属性的名称与请求值（例如路径变量或请求参数）的名称匹配，并且存在从 String 到模型属性类型的 Converter 时，此方案将被应用。在以下示例中，模型属性的名称为 account，它与 URI 路径变量 account 相匹配，并且已注册了一个 Converter<String, Account>，可用于从数据存储中加载 Account：
-
Java
-
Kotlin
@PutMapping("/accounts/{account}")
public String save(@ModelAttribute("account") Account account) { (1)
// ...
}| 1 | 使用显式的属性名称绑定一个 Account 实例。 |
@PutMapping("/accounts/{account}")
fun save(@ModelAttribute("account") account: Account): String { (1)
// ...
}| 1 | 使用显式的属性名称绑定一个 Account 实例。 |
获取模型属性实例后，将应用数据绑定。WebDataBinder 类会将 Servlet 请求参数名称（查询参数和表单字段）匹配到目标 Object 上的字段名称。在必要时应用类型转换后，匹配的字段将被填充。有关数据绑定（及验证）的更多信息，请参阅 验证。有关自定义数据绑定的更多信息，请参阅 DataBinder。
数据绑定可能会导致错误。默认情况下，会抛出一个 BindException 异常。然而，若要在控制器方法中检查此类错误，可以在 BindingResult 参数之后立即添加一个 @ModelAttribute 参数，如下例所示：
-
Java
-
Kotlin
@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@ModelAttribute("pet") Pet pet, BindingResult result) { (1)
if (result.hasErrors()) {
return "petForm";
}
// ...
}| 1 | 在 BindingResult 旁边添加一个 @ModelAttribute。 |
@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
fun processSubmit(@ModelAttribute("pet") pet: Pet, result: BindingResult): String { (1)
if (result.hasErrors()) {
return "petForm"
}
// ...
}| 1 | 在 BindingResult 旁边添加一个 @ModelAttribute。 |
在某些情况下，你可能希望访问模型属性而不进行数据绑定。对于这种情况，你可以将 Model 注入到控制器中并直接访问它，或者也可以设置 @ModelAttribute(binding=false)，如下例所示：
-
Java
-
Kotlin
@ModelAttribute
public AccountForm setUpForm() {
return new AccountForm();
}
@ModelAttribute
public Account findAccount(@PathVariable String accountId) {
return accountRepository.findOne(accountId);
}
@PostMapping("update")
public String update(@Valid AccountForm form, BindingResult result,
@ModelAttribute(binding=false) Account account) { (1)
// ...
}| 1 | 设置 @ModelAttribute(binding=false)。 |
@ModelAttribute
fun setUpForm(): AccountForm {
return AccountForm()
}
@ModelAttribute
fun findAccount(@PathVariable accountId: String): Account {
return accountRepository.findOne(accountId)
}
@PostMapping("update")
fun update(@Valid form: AccountForm, result: BindingResult,
@ModelAttribute(binding = false) account: Account): String { (1)
// ...
}| 1 | 设置 @ModelAttribute(binding=false)。 |
您可以通过添加 jakarta.validation.Valid 注解或 Spring 的 @Validated 注解（Bean Validation 和 Spring 验证），在数据绑定后自动应用验证。以下示例展示了如何实现这一点：
-
Java
-
Kotlin
@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@Valid @ModelAttribute("pet") Pet pet, BindingResult result) { (1)
if (result.hasErrors()) {
return "petForm";
}
// ...
}| 1 | 验证 Pet 实例。 |
@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
fun processSubmit(@Valid @ModelAttribute("pet") pet: Pet, result: BindingResult): String { (1)
if (result.hasErrors()) {
return "petForm"
}
// ...
}| 1 | 验证 Pet 实例。 |
请注意，使用 @ModelAttribute 是可选的（例如，用于设置其属性）。
默认情况下，任何不是简单值类型（由
BeanUtils#isSimpleProperty
判定）
且未被其他任何参数解析器解析的参数，都会被当作已使用 @ModelAttribute 注解处理。
在使用 GraalVM 编译为原生镜像时，上述描述的隐式 @ModelAttribute 支持无法正确进行相关数据绑定反射提示的提前推断。因此，建议在 GraalVM 原生镜像中显式地为方法参数添加 @ModelAttribute 注解。 |