@ModelAttribute

参见响应式栈中的等效项

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

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

请求参数是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) { (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来使用不同的注解。

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

在某些情况下，您可能希望在没有数据绑定的情况下访问模型属性。对于这种情况，您可以将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注解方法参数。