`@ModelAttribute`

@ModelAttribute 注解使用在方法参数上，会将请求参数绑定到模型对象上。例如：

Java

@POST("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@ModelAttribute Pet pet) { (1)
  // 业务逻辑。。。
}

1	绑定到 `Pet` 类的一个对象。

Pet 对象可能是：

从模型中访问，它可能已经被一个 @ModelAttribute 方法添加。
如果模型字段名称与请求值的名称（如路径变量或请求参数）匹配，可以通过 Converter 获取（示例如下）。
通过默认构造函数实例化。
通过与请求参数匹配的参数的“主构造函数”实例化。参数名称是通过字节码中的运行时保留参数名称确定的。

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

Java

@PUT("/accounts/{account}")
public String create(@ModelAttribute("account") Account account) { (1)
  // ...
}

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

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

Java

class Account {

  private final String firstName;

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

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

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

Java

@ModelAttribute
public AccountForm setUpForm() {
  return new AccountForm();
}

@ModelAttribute
public Account findAccount(@PathVariable String accountId) {
  return accountRepository.findOne(accountId);
}

@POST("update")
public String update(AccountForm form, BindingResult result,
    @ModelAttribute(binding=false) Account account) { (1)
  // ...
}

1	设置 `@ModelAttribute(binding=false)`.

如果数据绑定错误，默认情况下会抛出一个 MethodArgumentNotValidException，但您也可以在控制器方法中将 BindingResult 参数紧接在 @ModelAttribute 之后添加，以便处理这些错误。例如：

Java

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

1	添加一个 `BindingResult` 参数紧接着 `@ModelAttribute`.

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

Java

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

1	验证 `Pet` 对象.

如果没有在 @ModelAttribute 之后添加 BindingResult 参数，则会抛出带有验证错误的 MethodArgumentNotValidException。更多详细信息，请参阅验证部分。

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

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