Spring/spring-framework
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve RestControllerAdvice documentation

Browse Source 
Closes gh-34866
This commit is contained in:
rstoyanchev
2025-06-06 14:40:54 +01:00
parent de52090959
commit 4782c697b8
2 changed files with 17 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-advice.adoc
View File

@@ -10,18 +10,20 @@ to any controller. Moreover, as of 5.3, `@ExceptionHandler` methods in `@Control
can be used to handle exceptions from any `@Controller` or any other handler.
`@ControllerAdvice` is meta-annotated with `@Component` and therefore can be registered as
a Spring bean through xref:core/beans/java/instantiating-container.adoc#beans-java-instantiating-container-scan[component scanning]
. `@RestControllerAdvice` is meta-annotated with `@ControllerAdvice`
and `@ResponseBody`, and that means `@ExceptionHandler` methods will have their return
value rendered via response body message conversion, rather than via HTML views.
a Spring bean through xref:core/beans/java/instantiating-container.adoc#beans-java-instantiating-container-scan[component scanning].
`@RestControllerAdvice` is a shortcut annotation that combines `@ControllerAdvice`
with `@ResponseBody`, in effect simply an `@ControllerAdvice` whose exception handler
methods render to the response body.
On startup, `RequestMappingHandlerMapping` and `ExceptionHandlerExceptionResolver` detect
controller advice beans and apply them at runtime. Global `@ExceptionHandler` methods,
from an `@ControllerAdvice`, are applied _after_ local ones, from the `@Controller`.
By contrast, global `@ModelAttribute` and `@InitBinder` methods are applied _before_ local ones.
The `@ControllerAdvice` annotation has attributes that let you narrow the set of controllers
and handlers that they apply to. For example:
By default, both `@ControllerAdvice` and `@RestControllerAdvice` apply to any controller,
including `@Controller` and `@RestController`. Use attributes of the annotation to narrow
the set of controllers and handlers that they apply to. For example:
[tabs]
======

20
spring-web/src/main/java/org/springframework/web/bind/annotation/RestControllerAdvice.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright 2002-2023 the original author or authors.
* Copyright 2002-2025 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -26,18 +26,16 @@ import java.lang.annotation.Target;
import org.springframework.core.annotation.AliasFor;
/**
* A convenience annotation that is itself annotated with
* {@link ControllerAdvice @ControllerAdvice}
* and {@link ResponseBody @ResponseBody}.
* A shortcut annotation that combines {@link ControllerAdvice @ControllerAdvice}
* with {@link ResponseBody @ResponseBody}, in effect simply an
* {@code @ControllerAdvice} whose exception handler methods render to the
* response body.
*
* <p>Types that carry this annotation are treated as controller advice where
* {@link ExceptionHandler @ExceptionHandler} methods assume
* {@link ResponseBody @ResponseBody} semantics by default.
* <p>By default, {@code @RestControllerAdvice} applies to any controller,
* including {@code @Controller} and {@code @RestController}. Use attributes of
* the annotation to apply more specific filtering criteria.
*
* <p><b>NOTE:</b> {@code @RestControllerAdvice} is processed if an appropriate
* {@code HandlerMapping}-{@code HandlerAdapter} pair is configured such as the
* {@code RequestMappingHandlerMapping}-{@code RequestMappingHandlerAdapter} pair
* which are the default in the MVC Java config and the MVC namespace.
* <p>See {@link ControllerAdvice} for more details.
*
* @author Rossen Stoyanchev
* @author Sam Brannen