Introduction

Spring's @AliasFor is not limited to type-level annotations. It also works on annotations that target method parameters, but there is an important nuance: aliasing only helps when Spring or your own code reads that annotation through Spring's merged-annotation model.

What @AliasFor Actually Does

@AliasFor declares that two annotation attributes represent the same underlying setting. That gives callers a more ergonomic API and helps when one annotation attribute is meant to mirror another.

A parameter annotation can use the same mechanism as any other annotation:

1package example.web;
2
3import java.lang.annotation.ElementType;
4import java.lang.annotation.Retention;
5import java.lang.annotation.RetentionPolicy;
6import java.lang.annotation.Target;
7
8import org.springframework.core.annotation.AliasFor;
9
10@Target(ElementType.PARAMETER)
11@Retention(RetentionPolicy.RUNTIME)
12public @interface CurrentUser {
13
14    @AliasFor("name")
15    String value() default "";
16
17    @AliasFor("value")
18    String name() default "";
19}

With that declaration, @CurrentUser("id") and @CurrentUser(name = "id") are equivalent from Spring's point of view.

Reading Aliases from a Parameter

The alias does not become useful by magic. Something still has to inspect the parameter annotation and resolve the merged view. A common example is a custom Spring MVC argument resolver.

1package example.web;
2
3import org.springframework.core.MethodParameter;
4import org.springframework.core.annotation.MergedAnnotation;
5import org.springframework.core.annotation.MergedAnnotations;
6import org.springframework.stereotype.Component;
7import org.springframework.web.bind.support.WebDataBinderFactory;
8import org.springframework.web.context.request.NativeWebRequest;
9import org.springframework.web.method.support.HandlerMethodArgumentResolver;
10import org.springframework.web.method.support.ModelAndViewContainer;
11
12@Component
13public class CurrentUserArgumentResolver implements HandlerMethodArgumentResolver {
14
15    @Override
16    public boolean supportsParameter(MethodParameter parameter) {
17        return parameter.hasParameterAnnotation(CurrentUser.class);
18    }
19
20    @Override
21    public Object resolveArgument(
22            MethodParameter parameter,
23            ModelAndViewContainer mavContainer,
24            NativeWebRequest webRequest,
25            WebDataBinderFactory binderFactory) {
26
27        MergedAnnotation<CurrentUser> annotation =
28                MergedAnnotations.from(parameter.getParameter()).get(CurrentUser.class);
29
30        String key = annotation.getString("value");
31        return webRequest.getAttribute(key, NativeWebRequest.SCOPE_REQUEST);
32    }
33}

Using MergedAnnotations is the important part. If you read raw reflection values naively, you can miss the alias semantics that Spring provides.

A controller can then use either attribute name:

1package example.web;
2
3import org.springframework.web.bind.annotation.GetMapping;
4import org.springframework.web.bind.annotation.RestController;
5
6@RestController
7public class UserController {
8
9    @GetMapping("/me")
10    public String me(@CurrentUser("userId") String userId) {
11        return userId;
12    }
13}

When @AliasFor Helps on Parameters

The main value is API design. Many parameter annotations want a short unnamed attribute for the common case, plus a descriptive named attribute for clarity. value and name are a typical pair.

This pattern is especially useful when you are building:

• custom MVC argument annotations
• validation or mapping annotations processed by Spring infrastructure
• meta-annotations that mirror attributes from another Spring annotation

If you are only using plain Java reflection and never pass through Spring's annotation utilities, @AliasFor adds no benefit. The annotation compiles, but nothing resolves the alias relationship for you.

Meta-Annotation Use Is Different

Spring also supports @AliasFor(annotation = SomeAnnotation.class, attribute = "value") for composed annotations. That is a related but separate use case. On parameter annotations, you can use the same pattern if you are composing another annotation and need to expose one of its attributes under a new name.

The important rule is consistency:

• aliases must point at each other
• both attributes should have the same return type
• both should usually declare the same default value

If those conditions do not match, Spring will treat the annotation as misconfigured.

Common Pitfalls

The biggest mistake is expecting @AliasFor to change how Java annotations work by themselves. It is a Spring feature layered on top of Java metadata, so it only matters when Spring code reads the annotation in an alias-aware way.

Another common problem is asymmetric configuration. If value aliases name but name does not alias value, Spring will reject the setup. The contract must be two-way and internally consistent.

Developers also sometimes use aliases to paper over unclear API design. If the annotation has three or four names for the same concept, readability gets worse instead of better. Usually one short alias pair is enough.

Finally, be careful with examples copied from type-level annotations like @RequestMapping. Those patterns are valid, but parameter processing is different because your resolver or framework integration has to inspect the method parameter itself.

Summary

• '@AliasFor works on ElementType.PARAMETER annotations.'
• The alias is only meaningful when Spring reads the annotation through merged-annotation support.
• Use MergedAnnotations or other Spring utilities instead of raw reflection when resolving parameter aliases.
• Keep alias pairs symmetric with matching types and default values.
• Use parameter aliases to improve API ergonomics, not to hide confusing annotation design.