此版本仍在开发中，尚不被认为是稳定的。对于最新的稳定版本，请使用 Spring Framework 6.2.10！spring-doc.cadn.net.cn

@ModelAttribute

在 Servlet 堆栈中查看等效项spring-doc.cadn.net.cn

这@ModelAttribute方法参数标注绑定表单数据、查询参数、 URI 路径变量，并将请求标头添加到模型对象上。例如：spring-doc.cadn.net.cn

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@ModelAttribute Pet pet) { } (1)
1 绑定到Pet. 
@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
fun processSubmit(@ModelAttribute pet: Pet): String { } (1)
1 绑定到Pet.

表单数据和查询参数优先于 URI 变量和标头，后者是 仅当它们不覆盖具有相同名称的请求参数时才包含。破折号是 从标题名称中剥离。spring-doc.cadn.net.cn

这Pet实例可能是：spring-doc.cadn.net.cn

默认情况下，同时应用构造函数和属性数据绑定。然而 模型对象设计需要仔细考虑，出于安全原因，它是 建议使用专门为 Web 绑定定制的对象，或将 仅构造函数绑定。如果仍必须使用属性绑定，则应设置 allowedFields 模式以限制可以设置的属性。有关此内容的更多详细信息 和示例配置，请参阅模型设计。spring-doc.cadn.net.cn

使用构造函数绑定时，可以通过@BindParam注解。例如：spring-doc.cadn.net.cn

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.NameResolver上DataBinder

构造函数绑定支持List,Map，数组参数从 单个字符串，例如逗号分隔的列表，或基于索引键（例如accounts[2].name或account[KEY].name.spring-doc.cadn.net.cn

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

如果数据绑定导致错误，则默认情况下WebExchangeBindException被抬起， 但您也可以添加BindingResult参数紧邻@ModelAttribute以处理控制器方法中的此类错误。例如：spring-doc.cadn.net.cn

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

要使用BindingResult参数，则必须声明@ModelAttribute参数之前它没有响应式类型包装器。如果你想使用响应式，你可以处理错误直接通过它。 例如：spring-doc.cadn.net.cn

@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 验证和 Spring 验证）。 例如：spring-doc.cadn.net.cn

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@Valid @ModelAttribute("pet") Pet pet, BindingResult result) { (1)
	if (result.hasErrors()) {
		return "petForm";
	}
	// ...
}
1 用@Valid在模型属性参数上。 
@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
fun processSubmit(@Valid @ModelAttribute("pet") pet: Pet, result: BindingResult): String { (1)
	if (result.hasErrors()) {
		return "petForm"
	}
	// ...
}
1 用@Valid在模型属性参数上。

如果方法验证适用，因为其他参数具有@Constraint附注 然后HandlerMethodValidationException将被引发。请参阅有关控制器方法验证的部分。spring-doc.cadn.net.cn

用@ModelAttribute是可选的。默认情况下，任何不是简单的value 类型（由 BeanUtils#isSimpleProperty 确定且未被任何其他参数解析器解析）都被视为隐式@ModelAttribute.
使用 GraalVM 编译为本机映像时，隐式@ModelAttribute上述支持不允许对相关数据进行适当的提前推断绑定反射提示。因此，建议显式注释方法 参数@ModelAttribute用于 GraalVM 本机映像。