跳到主要内容

@ModelAttribute

ChatGPT-4o-mini 中英对照 @ModelAttribute @ModelAttribute

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

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

  • 绑定到 Pet 的一个实例。

请求参数是 Servlet API 的一个概念，包括来自请求体的表单数据和查询参数。URI 变量和头部也包括在内，但仅在它们不覆盖具有相同名称的请求参数时才算。头部名称中的破折号会被去掉。

上面的 Pet 实例可能是：

  • 从模型中访问，如果它可以通过 @ModelAttribute 方法 添加。

  • 如果模型属性在类级别的 @SessionAttributes 注解中列出，则从 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
    // ...
}
java

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

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

class Account {

    private final String firstName;

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

@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
    // ...
}
java

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

  • 在 @ModelAttribute 旁边添加一个 BindingResult。

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

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

  • 验证 Pet 实例。

如果在 @ModelAttribute 之后没有 BindingResult 参数，则会因验证错误而引发 MethodArgumentNotValueException。然而，如果由于其他参数具有 @jakarta.validation.Constraint 注解而应用方法验证，则会引发 HandlerMethodValidationException。有关更多详细信息，请参见 Validation 部分。

提示

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

注意

在使用 GraalVM 编译为本地镜像时，上述隐式的 @ModelAttribute 支持不允许正确的提前推断相关的数据绑定反射提示。因此，建议显式地使用 @ModelAttribute 注解方法参数，以便在 GraalVM 本地镜像中使用。