跳到主要内容

@ModelAttribute

ChatGPT-4o-mini 中英对照 @ModelAttribute @ModelAttribute

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

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@ModelAttribute Pet pet) { 1
// 方法逻辑...
}
java
  • 绑定到 Pet 的一个实例。

请求参数是 Servlet API 的一个概念,包括来自请求体的表单数据和查询参数。URI 变量和头部也包括在内,但仅在它们不覆盖具有相同名称的请求参数时才算。头部名称中的破折号会被去掉。

上面的 Pet 实例可能是:

  • 从模型中访问,如果它可以通过 @ModelAttribute 方法 添加。

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

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

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

  • 通过与 Servlet 请求参数匹配的参数的“主构造函数”实例化。参数名称通过字节码中的运行时保留参数名称确定。

如上所述,如果模型属性名称与请求值的名称(例如路径变量或请求参数)匹配,并且存在一个兼容的 Converter<String, T>,则可以使用 Converter<String, T> 来获取模型对象。在下面的示例中,模型属性名称 account 与 URI 路径变量 account 匹配,并且注册了一个 Converter<String, Account>,该转换器可能从持久性存储中检索它:

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

默认情况下,构造函数和属性 数据绑定 都会被应用。然而,模型对象设计需要仔细考虑,出于安全原因,建议要么使用专门为网页绑定量身定制的对象,要么仅应用构造函数绑定。如果仍然必须使用属性绑定,则应设置 allowedFields 模式以限制可以设置哪些属性。有关此内容的更多详细信息和示例配置,请参见 模型设计

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

class Account {

private final String firstName;

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

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

构造函数绑定支持 ListMap 和数组参数,这些参数可以从单个字符串转换而来,例如以逗号分隔的列表,或者基于索引键,例如 accounts[2].nameaccount[KEY].name

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

@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
// ...
}
java
  • 设置 @ModelAttribute(binding=false)

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

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@ModelAttribute("pet") Pet pet, BindingResult result) { 1
if (result.hasErrors()) {
return "petForm";
}
// ...
}
java
  • @ModelAttribute 旁边添加一个 BindingResult

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

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@Valid @ModelAttribute("pet") Pet pet, BindingResult result) { 1
if (result.hasErrors()) {
return "petForm";
}
// ...
}
java
  • 验证 Pet 实例。

如果在 @ModelAttribute 之后没有 BindingResult 参数,则会因验证错误而引发 MethodArgumentNotValueException。然而,如果由于其他参数具有 @jakarta.validation.Constraint 注解而应用方法验证,则会引发 HandlerMethodValidationException。有关更多详细信息,请参见 Validation 部分。

提示

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

注意

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