@AliasFor 是 Spring 5.2 引入的元注解，用于双向声明属性别名，支持属性重命名、同注解内互为别名及组合注解透传父级属性，需成对使用且类型默认值一致。
@AliasFor 是 Spring 5.2 引入的核心元注解，用于在自定义注解中**双向声明属性别名**，解决属性重命名、复用和语义增强问题。它不改变运行时行为，而是让编译器和 Spring 容器识别“这两个属性必须等价且互为镜像”。
属性重命名：让新注解复用已有注解的语义
当你基于某个 Spring 注解（如 @Cacheable）封装新注解时，可能希望改用更符合业务的属性名，但又不能破坏底层逻辑。这时用 @AliasFor 将新属性指向原注解对应属性即可。
例如，定义一个简化版缓存注解，把 value 改叫 cacheName：
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Cacheable // 继承其行为
public @interface MyCacheable {
@AliasFor(annotation = Cacheable.class, attribute = "value")
String cacheName() default "";
@AliasFor(annotation = Cacheable.class, attribute = "key")
String key() default "";
}
此时 @MyCacheable(cacheName = "user") 等价于 @Cacheable(value = "user")，Spring 解析时会自动映射过去。
立即学习“Java免费学习笔记（深入）”；
同一注解内属性互为别名：提升使用灵活性
在自定义注解内部，可让两个属性互指，实现“写一个等于写两个”。常用于兼容旧命名或提供多语义入口。
比如定义一个日志注解，允许用户用 level 或 logLevel 表达同一含义：
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Loggable {
@AliasFor("logLevel")
String level() default "INFO";
@AliasFor("level")
String logLevel() default "INFO";
}
- 必须成对出现，且类型、默认值完全一致
- 调用时只允许指定其中一个，否则编译报错：
@Loggable(level="DEBUG", logLevel="WARN")❌ - 若都不指定，则取默认值；指定任意一个，另一个自动同步
组合注解中透传父级属性：避免重复声明
当构建组合注解（如同时启用缓存 + 监控 + 降级）时，多个子注解可能都有 value 属性。用 @AliasFor 可统一收口到顶层注解的一个属性上。
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Cacheable
@Monitorable
@Fallback
public @interface SmartMethod {
@AliasFor(annotation = Cacheable.class, attribute = "value")
@AliasFor(annotation = Monitorable.class, attribute = "group")
@AliasFor(annotation = Fallback.class, attribute = "service")
String value() default "";
}
这样 @SmartMethod(value = "user-service") 会同时设置缓存名、监控分组、降级服务标识，无需分别配置。
注意事项与常见坑点
-
@AliasFor必须标注在方法上，不能标在注解类本身 - 别名链不能循环（A→B，B→C，C→A 不合法）
- 仅支持 编译期静态解析，不支持运行时动态计算别名
- Spring Boot 2.2+ 默认启用严格别名检查，若别名未被正确覆盖会启动失败
- IDE 可能不识别别名关系，建议配合 Javadoc 说明
