对于最新的稳定版本，请使用 Spring Framework 7.0.6!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 上设置一个 DataBinder.NameResolver 来使用其他注解

构造函数绑定支持从单个字符串（例如逗号分隔列表）转换而来的 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，但你也可以在 @ModelAttribute 旁边立即添加一个 BindingResult 参数，以在控制器方法中处理此类错误。例如：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 Validation 和 Spring validation）。例如：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 是可选的。默认情况下，任何不是由 BeanUtils#isSimpleProperty 确定的简单值类型的参数， 并且 未被其他任何参数解析器解析的参数，将被视为隐式的 @ModelAttribute。
在使用GraalVM编译为原生镜像时，上文描述的隐式@ModelAttribute支持无法正确实现相关数据绑定的反射提示的提前推断。因此，建议在GraalVM原生镜像使用场景中，显式标注方法参数为@ModelAttribute。