`@ModelAttribute`

@ModelAttribute方法参数注解将请求参数绑定到模型对象。例如：

Java
Kotlin

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@ModelAttribute Pet pet) { (1)
	// 方法逻辑...
}

1	绑定到一个`Pet`实例。

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
fun processSubmit(@ModelAttribute pet: Pet): String { (1)
	// 方法逻辑...
}

1	绑定到一个`Pet`实例。

Pet实例可能是：

从模型中访问，可能是通过@ModelAttribute方法添加的。
如果模型属性在类级别的@SessionAttributes注解中列出，则可以从HTTP会话中访问。
如果模型属性名称与请求值（例如路径变量或请求参数）的名称匹配，则可以通过Converter获得（示例如下）。
通过默认构造函数实例化。
通过与Servlet请求参数匹配的“主构造函数”实例化。参数名称是通过字节码中保留的运行时参数名称确定的。

如上所述，如果模型属性名称与请求值（例如路径变量或请求参数）的名称匹配，并且存在兼容的Converter<String, T>，则可以使用Converter<String, T>来获取模型对象。在下面的示例中，模型属性名称account与URI路径变量account匹配，并且注册了Converter<String, Account>，可能从持久性存储中检索它：

Java
Kotlin

@PutMapping("/accounts/{account}")
public String save(@ModelAttribute("account") Account account) { (1)
	// ...
}

@PutMapping("/accounts/{account}")
fun save(@ModelAttribute("account") account: Account): String { (1)
	// ...
}

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

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

Java
Kotlin

class Account {

    private final String firstName;

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

class Account(@BindParam("first-name") val firstName: String)

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

在某些情况下，您可能希望在没有数据绑定的情况下访问模型属性。对于这种情况，您可以将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(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(form: AccountForm, result: BindingResult,
		   @ModelAttribute(binding = false) account: Account): String { (1)
	// ...
}

1	设置`@ModelAt\tribute(binding=false)`。

如果数据绑定导致错误，默认情况下会引发MethodArgumentNotValidException，但您还可以在控制器方法中紧挨着@ModelAttribute添加一个BindingResult参数来处理这些错误。例如：

Java
Kotlin

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

1	在`@ModelAttribute`旁边添加一个`BindingResult`。

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

1	在`@ModelAttribute`旁边添加一个`BindingResult`。

您可以通过添加jakarta.validation.Valid注解或Spring的@Validated注解，在数据绑定后自动应用验证。请参阅Bean验证和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之后没有BindingResult参数，则会引发MethodArgumentNotValueException，其中包含验证错误。但是，如果方法验证适用于其他参数具有@jakarta.validation.Constraint注解，则会引发HandlerMethodValidationException。有关更多详细信息，请参阅验证部分。

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

在使用GraalVM编译为本机映像时，上述描述的隐式@ModelAttribute支持不允许正确推断相关数据绑定反射提示。因此，建议在GraalVM本机映像中使用时，显式地为方法参数添加@ModelAttribute注解。