From a698b1bc0d9727b9af0208f12c312787046bf617 Mon Sep 17 00:00:00 2001 From: rstoyanchev Date: Wed, 5 Nov 2025 11:26:40 +0000 Subject: [PATCH] Refine validation section for controllers Closes gh-35759 --- .../webflux/controller/ann-validation.adoc | 26 +++++++++------- .../webmvc/mvc-controller/ann-validation.adoc | 30 +++++++++++-------- 2 files changed, 32 insertions(+), 24 deletions(-) diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-validation.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-validation.adoc index 553b9d9dac2..67fb1256a88 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-validation.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-validation.adoc @@ -7,19 +7,23 @@ Spring WebFlux has built-in xref:core/validation/validator.adoc[Validation] for `@RequestMapping` methods, including xref:core/validation/beanvalidation.adoc[Java Bean Validation]. Validation may be applied at one of two levels: -1. xref:web/webflux/controller/ann-methods/modelattrib-method-args.adoc[@ModelAttribute], +1. Java Bean Validation is applied individually to an +xref:web/webflux/controller/ann-methods/modelattrib-method-args.adoc[@ModelAttribute], xref:web/webflux/controller/ann-methods/requestbody.adoc[@RequestBody], and -xref:web/webflux/controller/ann-methods/multipart-forms.adoc[@RequestPart] argument -resolvers validate a method argument individually if the method parameter is annotated -with Jakarta `@Valid` or Spring's `@Validated`, _AND_ there is no `Errors` or -`BindingResult` parameter immediately after, _AND_ method validation is not needed (to be -discussed next). The exception raised in this case is `WebExchangeBindException`. +xref:web/webflux/controller/ann-methods/multipart-forms.adoc[@RequestPart] method parameter +annotated with `@jakarta.validation.Valid` or Spring's `@Validated` so long as +it is a command object rather than a container such as `Map` or `Collection`, it does not +have `Errors` or `BindingResult` immediately after in the method signature, and does not +otherwise require method validation (see next). `WebExchangeBindException` is the +exception raised when validating a method parameter individually. -2. When `@Constraint` annotations such as `@Min`, `@NotBlank` and others are declared -directly on method parameters, or on the method (for the return value), then method -validation must be applied, and that supersedes validation at the method argument level -because method validation covers both method parameter constraints and nested constraints -via `@Valid`. The exception raised in this case is `HandlerMethodValidationException`. +2. Java Bean Validation is applied to the method when `@Constraint` annotations such as +`@Min`, `@NotBlank` and others are declared directly on method parameters, or on the +method for the return value, and it supersedes any validation that would be applied +otherwise to a method parameter individually because method validation covers both +method parameter constraints and nested constraints via `@Valid`. +`HandlerMethodValidationException` is the exception raised validation is applied +to the method. Applications must handle both `WebExchangeBindException` and `HandlerMethodValidationException` as either may be raised depending on the controller diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-validation.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-validation.adoc index 99ddf8635eb..45e5c632f4b 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-validation.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-validation.adoc @@ -7,22 +7,26 @@ Spring MVC has built-in xref:core/validation/validator.adoc[validation] for `@RequestMapping` methods, including xref:core/validation/beanvalidation.adoc[Java Bean Validation]. Validation may be applied at one of two levels: -1. xref:web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc[@ModelAttribute], +1. Java Bean Validation is applied individually to an +xref:web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc[@ModelAttribute], xref:web/webmvc/mvc-controller/ann-methods/requestbody.adoc[@RequestBody], and -xref:web/webmvc/mvc-controller/ann-methods/multipart-forms.adoc[@RequestPart] argument -resolvers validate a method argument individually if the method parameter is annotated -with Jakarta `@Valid` or Spring's `@Validated`, _AND_ there is no `Errors` or -`BindingResult` parameter immediately after, _AND_ method validation is not needed (to be -discussed next). The exception raised in this case is `MethodArgumentNotValidException`. +xref:web/webmvc/mvc-controller/ann-methods/multipart-forms.adoc[@RequestPart] method parameter +annotated with `@jakarta.validation.Valid` or Spring's `@Validated` so long as +it is a command object rather than a container such as `Map` or `Collection`, it does not +have `Errors` or `BindingResult` immediately after in the method signature, and does not +otherwise require method validation (see next). `MethodArgumentNotValidException` is the +exception raised when validating a method parameter individually. -2. When `@Constraint` annotations such as `@Min`, `@NotBlank` and others are declared -directly on method parameters, or on the method (for the return value), then method -validation must be applied, and that supersedes validation at the method argument level -because method validation covers both method parameter constraints and nested constraints -via `@Valid`. The exception raised in this case is `HandlerMethodValidationException`. +2. Java Bean Validation is applied to the method when `@Constraint` annotations such as +`@Min`, `@NotBlank` and others are declared directly on method parameters, or on the +method for the return value, and it supersedes any validation that would be applied +otherwise to a method parameter individually because method validation covers both +method parameter constraints and nested constraints via `@Valid`. +`HandlerMethodValidationException` is the exception raised validation is applied +to the method. -Applications must handle both `MethodArgumentNotValidException` and -`HandlerMethodValidationException` as either may be raised depending on the controller +Applications should handle both `MethodArgumentNotValidException` and +`HandlerMethodValidationException` since either may be raised depending on the controller method signature. The two exceptions, however are designed to be very similar, and can be handled with almost identical code. The main difference is that the former is for a single object while the latter is for a list of method parameters.