跳到主要内容
版本：7.0.3

@ModelAttribute

Hunyuan 7b 中英对照 @ModelAttribute @ModelAttribute

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

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@ModelAttribute Pet pet) { 1
	// 方法逻辑...
}

  • 绑定到 Pet 的实例。

请求参数（Request Parameters）是Servlet API中的一个概念，它包括来自请求体（request body）的表单数据以及查询参数（query parameters）。URI变量（URI Variables）和请求头（Header）也属于请求参数的范畴，但只有当它们不会覆盖同名请求参数时才会被包含在内。请求头名称中的连字符（-）会被删除。

上面的Pet实例可能是：

  • 可通过〔@ModelAttribute方法〕(../ann-modelattrib-methods.md)在模型中访问该属性。

  • 如果模型属性被列在类级别的〔@SessionAttributes〕(sessionattributes.md)注解中，则可以通过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
	// ...
}

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

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

class Account {

	private final String firstName;

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

@BindParam 也可以放在对应于构造函数参数的字段上。虽然 @BindParam 是默认支持的，但你也可以通过在 DataBinder 上设置 DataBinder.NameResolver 来使用其他注解。

构造函数绑定支持List、Map和数组参数，这些参数可以由单个字符串转换而来（例如，逗号分隔的列表），也可以基于索引键来获取，如accounts[2].name或account[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
	// ...
}

  • 设置 @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";
	}
	// ...
}

  • 在 @ModelAttribute 旁边添加了 BindingResult。

你可以通过添加 jakartavalidation_valid 注解或 Spring 的 @Validated 注解，在数据绑定后自动应用验证。请参阅 Bean 验证 和 Spring 验证。例如：

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

  • 验证 Pet 实例。

如果在@ModelAttribute之后没有BindingResult参数，那么将会抛出MethodArgumentNotValidException并附带验证错误信息。然而，如果由于其他参数带有@jakarta.validation.Constraint注解而需要应用方法验证，则会抛出HandlerMethodValidationException代替。有关更多详细信息，请参阅验证部分。

提示

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

注意

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