Mastering Spring Boot’s @AliasFor: Flexible Annotation Customization

Environment: Spring Boot 3.5.0

1. Introduction

@AliasFor has been available since Spring 4.2. It can be used to declare an alias for an attribute inside a single annotation or within a meta‑annotation. When applied, the alias allows the two attributes to be used interchangeably, and in composed annotations it can override the attribute of the meta‑annotation.

2. Practical examples

2.1 Explicit alias inside an annotation

In Spring’s own @ComponentScan the attribute value is declared as an alias for basePackages and vice‑versa:

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Documented
@Repeatable(ComponentScans.class)
public @interface ComponentScan {
    @AliasFor("basePackages")
    String[] value() default {};

    @AliasFor("value")
    String[] basePackages() default {};
    // ...
}

Therefore the following two usages are equivalent:

@ComponentScan(basePackages = "com.pack")
@ComponentScan(value = "com.pack")

Because both attributes are default, the annotation can also be written as:

@ComponentScan("com.pack")

2.2 Explicit alias in a composed annotation

Define a meta‑annotation @PackMapping that composes @RequestMapping and uses @AliasFor to map its own attributes to those of @RequestMapping:

@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@RequestMapping
public @interface PackMapping {
    @AliasFor(annotation = RequestMapping.class, attribute = "method")
    RequestMethod[] action() default {};

    @AliasFor(annotation = RequestMapping.class, attribute = "path")
    String[] route() default {};
}

Using the composed annotation:

@RestController
@RequestMapping("/api")
public class ApiController {
    @PackMapping(action = RequestMethod.GET, route = "/query")
    public ResponseEntity<?> query() { /* ... */ }
}

2.3 Implicit alias

When additional attributes in @PackMapping are also annotated with @AliasFor("path"), they become implicit aliases of each other. The following definition makes value, mapping and route interchangeable:

@AliasFor(annotation = RequestMapping.class, attribute = "path")
String[] value() default {};

@AliasFor(annotation = RequestMapping.class, attribute = "path")
String[] mapping() default {};

@AliasFor(annotation = RequestMapping.class, attribute = "path")
String[] route() default {};

2.4 Test program and results

A reflective test iterates over the methods of ApiController and prints the merged annotations for both PackMapping and RequestMapping:

for (Method method : ApiController.class.getMethods()) {
    if (method.isAnnotationPresent(PackMapping.class)) {
        System.err.println(AnnotatedElementUtils.getAllMergedAnnotations(method, PackMapping.class));
        System.err.println(AnnotatedElementUtils.getAllMergedAnnotations(method, RequestMapping.class));
    }
}

Output shows that the aliasing works as expected:

[@com.pack.mapping.annotation.PackMapping(action={GET}, route={"/query"})]
[@org.springframework.web.bind.annotation.RequestMapping(consumes={}, headers={}, method={GET}, name="", params={}, path={"/query"}, produces={}, value={"/query"})]

These examples demonstrate how @AliasFor can simplify attribute naming, enable attribute overriding in composed annotations, and create both explicit and implicit alias relationships.