对于最新稳定版本，请使用 Spring Framework 7.0.6！spring-doc.cadn.net.cn

@ModelAttribute

参见响应式栈中的等效内容spring-doc.cadn.net.cn

@ModelAttribute 方法参数注解可将请求参数、URI 路径变量和请求头绑定到模型对象上。例如：spring-doc.cadn.net.cn

@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 的一个实例。

请求参数是 Servlet API 中的一个概念，包括来自请求体的表单数据和查询参数。URI 变量和请求头也会被包含在内，但前提是它们不会覆盖同名的请求参数。请求头名称中的短横线（-）会被移除。spring-doc.cadn.net.cn

上面的 Pet 实例可能是：spring-doc.cadn.net.cn

如上所述，如果模型属性名称与某个请求值（例如路径变量或请求参数）的名称相匹配，并且存在一个兼容的 Converter<String, T>，那么就可以使用该 Converter<String, T> 来获取模型对象。在下面的示例中，模型属性名称 account 与 URI 路径变量 account 相匹配，并且已注册了一个 Converter<String, Account>，该转换器可能会从持久化存储中检索该对象：spring-doc.cadn.net.cn

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

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

使用构造函数绑定时，可以通过 @BindParam 注解自定义请求参数的名称。例如：spring-doc.cadn.net.cn

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.NameResolver 上设置一个 DataBinder 来使用其他注解。

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

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

@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 异常， 但你也可以在 BindingResult 参数旁边立即添加一个 @ModelAttribute 参数， 以便在控制器方法中处理此类错误。例如：spring-doc.cadn.net.cn

@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。

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

@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 实例。

如果在 BindingResult 之后没有 @ModelAttribute 参数，则会抛出包含验证错误的 MethodArgumentNotValidException 异常。然而，如果由于其他参数带有 @jakarta.validation.Constraint 注解而应用了方法级验证，则会抛出 HandlerMethodValidationException 异常。更多详情，请参见验证一节。spring-doc.cadn.net.cn

使用 @ModelAttribute 是可选的。默认情况下，任何未被判定为简单值类型的参数（由 BeanUtils#isSimpleProperty 确定）并且未被其他任何参数解析器解析的参数，都会被隐式视为 @ModelAttribute。
在使用 GraalVM 编译为原生镜像时，上述描述的隐式 @ModelAttribute 支持无法正确进行相关数据绑定反射提示的提前推断。因此，建议在 GraalVM 原生镜像中显式地为方法参数添加 @ModelAttribute 注解。