注释类型 ControllerAdvice
@Target(TYPE) @Retention(RUNTIME) @Documented @Component public @interface ControllerAdvice
Specialization of@Component
for classes that declare@ExceptionHandler
,@InitBinder
, or@ModelAttribute
methods to be shared across multiple@Controller
classes.Classes annotated with
@ControllerAdvice
can be declared explicitly as Spring beans or auto-detected via classpath scanning. All such beans are sorted based onOrdered
semantics or@Order
/@Priority
declarations, withOrdered
semantics taking precedence over@Order
/@Priority
declarations.@ControllerAdvice
beans are then applied in that order at runtime. Note, however, that@ControllerAdvice
beans that implementPriorityOrdered
are not given priority over@ControllerAdvice
beans that implementOrdered
. In addition,Ordered
is not honored for scoped@ControllerAdvice
beans — for example if such a bean has been configured as a request-scoped or session-scoped bean. For handling exceptions, an@ExceptionHandler
will be picked on the first advice with a matching exception handler method. For model attributes and data binding initialization,@ModelAttribute
and@InitBinder
methods will follow@ControllerAdvice
order.Note: For
@ExceptionHandler
methods, a root exception match will be preferred to just matching a cause of the current exception, among the handler methods of a particular advice bean. However, a cause match on a higher-priority advice will still be preferred over any match (whether root or cause level) on a lower-priority advice bean. As a consequence, please declare your primary root exception mappings on a prioritized advice bean with a corresponding order.By default, the methods in an
@ControllerAdvice
apply globally to all controllers. Use selectors such asannotations()
,basePackageClasses()
, andbasePackages()
(or its aliasvalue()
) to define a more narrow subset of targeted controllers. If multiple selectors are declared, booleanOR
logic is applied, meaning selected controllers should match at least one selector. Note that selector checks are performed at runtime, so adding many selectors may negatively impact performance and add complexity.- 从以下版本开始:
- 3.2
- 作者:
- Rossen Stoyanchev, Brian Clozel, Sam Brannen
- 另请参阅:
Controller
,RestControllerAdvice
可选元素概要
可选元素 修饰符和类型 可选元素 说明 Class<? extends Annotation>[]
annotations
Array of annotation types.Class<?>[]
assignableTypes
Array of classes.Class<?>[]
basePackageClasses
Type-safe alternative tobasePackages()
for specifying the packages in which to select controllers to be advised by the@ControllerAdvice
annotated class.String[]
basePackages
Array of base packages.String[]
value
Alias for thebasePackages()
attribute.
元素详细资料
value
@AliasFor("basePackages") String[] value
Alias for thebasePackages()
attribute.Allows for more concise annotation declarations — for example,
@ControllerAdvice("org.my.pkg")
is equivalent to@ControllerAdvice(basePackages = "org.my.pkg")
.- 从以下版本开始:
- 4.0
- 另请参阅:
basePackages()
- 默认值:
- {}
basePackages
@AliasFor("value") String[] basePackages
Array of base packages.Controllers that belong to those base packages or sub-packages thereof will be included — for example,
@ControllerAdvice(basePackages = "org.my.pkg")
or@ControllerAdvice(basePackages = {"org.my.pkg", "org.my.other.pkg"})
.value()
is an alias for this attribute, simply allowing for more concise use of the annotation.Also consider using
basePackageClasses()
as a type-safe alternative to String-based package names.- 从以下版本开始:
- 4.0
- 默认值:
- {}
basePackageClasses
Class<?>[] basePackageClasses
Type-safe alternative tobasePackages()
for specifying the packages in which to select controllers to be advised by the@ControllerAdvice
annotated class.Consider creating a special no-op marker class or interface in each package that serves no purpose other than being referenced by this attribute.
- 从以下版本开始:
- 4.0
- 默认值:
- {}
assignableTypes
Class<?>[] assignableTypes
Array of classes.Controllers that are assignable to at least one of the given types will be advised by the
@ControllerAdvice
annotated class.- 从以下版本开始:
- 4.0
- 默认值:
- {}
annotations
Class<? extends Annotation>[] annotations
Array of annotation types.Controllers that are annotated with at least one of the supplied annotation types will be advised by the
@ControllerAdvice
annotated class.Consider creating a custom composed annotation or use a predefined one, like
@RestController
.- 从以下版本开始:
- 4.0
- 默认值:
- {}