`@ModelAttribute`

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

Java

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@ModelAttribute Pet pet) { [id="CO1-1"][id="CO1-1"][id="CO1-1"](1)
	// method logic...
}

<1>  绑定到 `Pet` 实例。

Kotlin

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
fun processSubmit(@ModelAttribute pet: Pet): String { [id="CO2-1"][id="CO1-2"][id="CO2-1"](1)
	// method logic...
}

<1>  绑定到 `Pet` 实例。

请求参数是 Servlet API 的一个概念，它包括来自请求体的表单数据和查询参数。URI 变量和请求头也包含在内，但前提是它们不会覆盖同名的请求参数。请求头名称中的破折号会被去除。

上面的 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) { [id="CO3-1"][id="CO1-3"][id="CO3-1"](1)
	// ...
}

@PutMapping("/accounts/{account}")
fun save(@ModelAttribute("account") account: Account): String { [id="CO3-2"][id="CO1-4"][id="CO3-2"](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 来使用不同的注解。

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

在某些情况下，你可能希望访问模型属性而无需数据绑定。对于这种情况，你可以将 Model 注入到控制器中并直接访问它，或者，如以下示例所示，设置 @ModelAttribute(binding=false)：

Java

@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) { [id="CO3-3"][id="CO1-5"][id="CO3-3"](1)
	// ...
}

<1>  设置 `@ModelAttribute(binding=false)`。

Kotlin

@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 { [id="CO4-1"][id="CO1-6"][id="CO4-1"](1)
	// ...
}

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

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

Java

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@ModelAttribute("pet") Pet pet, BindingResult result) { [id="CO5-1"][id="CO1-7"][id="CO5-1"](1)
	if (result.hasErrors()) {
		return "petForm";
	}
	// ...
}

<1>  在 `@ModelAttribute` 旁边添加 `BindingResult`。

Kotlin

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
fun processSubmit(@ModelAttribute("pet") pet: Pet, result: BindingResult): String { [id="CO6-1"][id="CO1-8"][id="CO6-1"](1)
	if (result.hasErrors()) {
		return "petForm"
	}
	// ...
}

<1>  在 `@ModelAttribute` 旁边添加 `BindingResult`。

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

Java

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@Valid @ModelAttribute("pet") Pet pet, BindingResult result) { [id="CO7-1"][id="CO1-9"][id="CO7-1"](1)
	if (result.hasErrors()) {
		return "petForm";
	}
	// ...
}

<1>  验证 `Pet` 实例。

Kotlin

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
fun processSubmit(@Valid @ModelAttribute("pet") pet: Pet, result: BindingResult): String { [id="CO8-1"][id="CO1-10"][id="CO8-1"](1)
	if (result.hasErrors()) {
		return "petForm"
	}
	// ...
}

<1>  验证 `Pet` 实例。

如果在 @ModelAttribute 之后没有 BindingResult 参数，则会抛出带有验证错误的 MethodArgumentNotValidException。但是，如果由于其他参数具有 @jakarta.validation.Constraint 注解而适用方法验证，则会抛出 HandlerMethodValidationException。有关更多详细信息，请参阅验证部分。

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

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