`@ModelAttribute`

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

Java

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@ModelAttribute Pet pet) { } [id="CO1-1"][id="CO1-1"][id="CO1-1"](1)

<1>  绑定到 `Pet` 的实例。

Kotlin

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
fun processSubmit(@ModelAttribute pet: Pet): String { } [id="CO2-1"][id="CO1-2"][id="CO2-1"](1)

<1>  绑定到 `Pet` 的实例。

表单数据和查询参数优先于 URI 变量和请求头，URI 变量和请求头仅在它们不覆盖同名请求参数时才包含在内。请求头名称中的破折号会被去除。

Pet 实例可能：

从模型中获取，它可能已被 Model 添加。
如果模型属性在类级别的 @SessionAttributes 中列出，则从 HTTP 会话中获取。
通过默认构造函数实例化。
通过带有与 Servlet 请求参数匹配的参数的“主构造函数”实例化。参数名称通过字节码中运行时保留的参数名称确定。

默认情况下，构造函数和属性数据绑定都适用。然而，模型对象设计需要仔细考虑，出于安全原因，建议要么使用专门为 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）。

WebFlux 与 Spring MVC 不同，支持模型中的响应式类型，例如 Mono<Account>。您可以声明带有或不带有响应式类型包装器的 @ModelAttribute 参数，它将根据实际值进行解析。

如果数据绑定导致错误，默认情况下会抛出 WebExchangeBindException，但您也可以在 @ModelAttribute 旁边紧接着添加 BindingResult 参数，以便在控制器方法中处理此类错误。例如：

Java

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

<1>  添加 `BindingResult`。

Kotlin

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
fun processSubmit(@ModelAttribute("pet") pet: Pet, result: BindingResult): String { [id="CO4-1"][id="CO1-3"][id="CO4-1"](1)
	if (result.hasErrors()) {
		return "petForm"
	}
	// ...
}

<1>  添加 `BindingResult`。

要使用 BindingResult 参数，您必须在它之前声明 @ModelAttribute 参数，且不带响应式类型包装器。如果您想使用响应式类型，可以直接通过它处理错误。例如：

Java
Kotlin

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public Mono<String> processSubmit(@Valid @ModelAttribute("pet") Mono<Pet> petMono) {
	return petMono
		.flatMap(pet -> {
			// ...
		})
		.onErrorResume(ex -> {
			// ...
		});
}

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
fun processSubmit(@Valid @ModelAttribute("pet") petMono: Mono<Pet>): Mono<String> {
	return petMono
			.flatMap { pet ->
				// ...
			}
			.onErrorResume{ ex ->
				// ...
			}
}

您可以通过添加 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) { [id="CO5-1"][id="CO1-4"][id="CO5-1"](1)
	if (result.hasErrors()) {
		return "petForm";
	}
	// ...
}

<1>  在模型属性参数上使用 `@Valid`。

Kotlin

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
fun processSubmit(@Valid @ModelAttribute("pet") pet: Pet, result: BindingResult): String { [id="CO6-1"][id="CO1-5"][id="CO6-1"](1)
	if (result.hasErrors()) {
		return "petForm"
	}
	// ...
}

<1>  在模型属性参数上使用 `@Valid`。

如果由于其他参数具有 @Constraint 注解而应用了方法验证，则会抛出 HandlerMethodValidationException。请参阅控制器方法验证部分。

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

当使用 GraalVM 编译成本机镜像时，上述描述的隐式 @ModelAttribute 支持不允许对相关数据绑定反射提示进行适当的提前推断。因此，建议在使用 GraalVM 本机镜像时，明确使用 @ModelAttribute 注解方法参数。