@ModelAttribute

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

Java
@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@ModelAttribute Pet pet) { } (1)
1 绑定到 `Pet`的一个实例。
Kotlin
@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
fun processSubmit(@ModelAttribute pet: Pet): String { } (1)
2 绑定到 `Pet`的一个实例。

表单数据和查询参数优先于 URI 变量和标头，仅包括那些未用同名请求参数覆盖它们的变量和标头，连字符会从标头名称中删掉。

Pet 实例可能是：

  • 从可能是已经通过Model添加的模型访问。

  • 从可能在类级别 @SessionAttributes中列出模型属性的 HTTP 会话访问。

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

  • 通过与 Servlet 请求参数匹配的参数实例化"`primary constructor`"。参数名称通过字节码中运行时保留的参数名称确定。

默认情况下，构造函数和属性 data binding 都已应用。但是，模型对象设计需要仔细考虑，出于安全原因，建议要么使用专门为 Web 绑定定制的对象，要么只应用构造函数绑定。如果仍必须使用属性绑定，则应设置 allowedFields 模式以限制可以设置哪些属性。有关这方面和示例配置的更多详细信息，请参见 model design。

在使用构造函数绑定时，你可以通过 @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）。

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

如果数据绑定导致错误，则默认情况下会引发 WebExchangeBindException，但是您还可以在 @ModelAttribute 紧挨着添加一个 BindingResult 参数，以便在控制器方法中处理此类错误。例如：

Java
@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@ModelAttribute("pet") Pet pet, BindingResult result) { 1
	if (result.hasErrors()) {
		return "petForm";
	}
	// ...
}
1 Adding a BindingResult.
Kotlin
@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
fun processSubmit(@ModelAttribute("pet") pet: Pet, result: BindingResult): String { (1)
	if (result.hasErrors()) {
		return "petForm"
	}
	// ...
}
2 Adding a 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 ->
				// ...
			}
}

通过添加 @5 批注或 Spring 的 @6 批注，您可以在数据绑定后自动应用验证（请参阅 @7 和 @8）。例如：

Java
@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@Valid @ModelAttribute("pet") Pet pet, BindingResult result) { (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 { (1)
	if (result.hasErrors()) {
		return "petForm"
	}
	// ...
}
2 对模型属性参数使用 @Valid。

如果方法验证适用，因为其他参数带有 @9 批注，那么 @10 将会代之以提出。请参阅控制器方法 @11 的章节。

使用 @ModelAttribute 是可选的。默认情况下，如果某个参数不是使用 https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-AND 确定的简单值类型，并且未通过任何其他参数解析器解析，则该参数将视为隐式的 @ModelAttribute。

使用 GraalVM 编译为本机映像时，上面描述的隐式 @ModelAttribute 支持不允许提前正确推断相关的 data binding 反射提示。因此，建议明确使用 @ModelAttribute 为方法参数添加注释，以便在 GraalVM 本机映像中使用。