@ModelAttribute

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

Java
@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@ModelAttribute Pet pet) { (1)
	// method logic...
}
1 绑定到 `Pet`的一个实例。
Kotlin
@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
fun processSubmit(@ModelAttribute pet: Pet): String { (1)
	// method logic...
}
2 绑定到 `Pet`的一个实例。

请求参数是 Servlet API 概念，包括来自请求正文的表单数据和查询参数。也包括 URI 变量和头，但仅当它们不以相同名称覆盖请求参数时。连字符从头名称中除去。

上面的 Pet 实例可能为：

  • 从模型访问，可以在模型中通过@ModelAttribute method添加此模型。

  • 如果模型属性在类级别的@SessionAttributes注释中列出，则从 HTTP 会话访问。

  • 如果模型属性名称与请求值（例如路径变量或请求参数）的名称匹配，则通过 `Converter`获取（如下例所示）。

  • 通过默认构造函数实例化。

  • 通过与 Servlet 请求参数匹配的参数实例化"`primary constructor`"。参数名称通过字节码中运行时保留的参数名称确定。

如上所述，Converter<String, T> 可用于在模型属性名称与路径变量或请求参数等请求值名称匹配并且存在兼容的 Converter<String, T> 时获取模型对象。在以下示例中，模型属性名称 account 与 URI 路径变量 account 匹配，并且有一个已注册的 Converter<String, 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)
	// ...
}

默认情况下，将应用构造函数和属性 data binding。不过，模型对象设计需要仔细考虑，并且出于安全原因，建议使用专门为 Web 绑定设计的对象，或者只应用构造函数绑定。如果仍然必须使用属性绑定，那么应当设置 allowedFields 模式以限制可设置的属性。有关此示例配置的更多详细信息，请参阅 model design。

在使用构造函数绑定时，你可以通过 @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) { (1)
	// ...
}
1 Setting @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 { (1)
	// ...
}
2 Setting @ModelAt\tribute(binding=false).

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

Java
@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@ModelAttribute("pet") Pet pet, BindingResult result) { (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 { (1)
	if (result.hasErrors()) {
		return "petForm"
	}
	// ...
}
2 在`@ModelAttribute`旁边添加一个`BindingResult`。

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

Java
@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@Valid @ModelAttribute("pet") Pet pet, BindingResult result) { (1)
	if (result.hasErrors()) {
		return "petForm";
	}
	// ...
}
1 Validate the Pet instance.
Kotlin
@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
fun processSubmit(@Valid @ModelAttribute("pet") pet: Pet, result: BindingResult): String { (1)
	if (result.hasErrors()) {
		return "petForm"
	}
	// ...
}
2 Validate the Pet instance.

如果没有 @ModelAttribute 后面的 BindingResult 参数，那么会针对验证错误引发 MethodArgumentNotValueException。但是，如果方法验证正在应用，因为其他参数具有 @jakarta.validation.Constraint 注释，那么会改为引发 HandlerMethodValidationException。有关更多详细信息，请参见第 Validation 段。

使用 @ModelAttribute 是可选的。默认情况下，如果某个参数不是使用 https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-AND 确定的简单值类型，并且未通过任何其他参数解析器解析，则该参数将视为隐式的 @ModelAttribute。

使用 GraalVM 编译为本机映像时，上面描述的隐式 @ModelAttribute 支持不允许提前正确推断相关的 data binding 反射提示。因此，建议明确使用 @ModelAttribute 为方法参数添加注释，以便在 GraalVM 本机映像中使用。