注解应仅承载元数据，不掺杂业务逻辑；须配完整Javadoc、IDE支持及默认值约束；解析逻辑统一收口于框架层切面；禁用无显式入口的“魔法注解”。
注解本身不执行逻辑，但过度堆砌会让关键行为“消失”在标记里，导致调用链断裂、断点失效、错误路径难追踪。避免这个问题，核心不是少用注解，而是让注解的意图可感知、行为可定位、边界可控制。
明确注解职责边界：只承载元数据，不替代业务判断
注解应只声明“做什么”，绝不掺杂“怎么做”或“何时做”的条件分支。比如：
- ✅ 合理：
@Retry(maxAttempts = 3, backoff = 100)—— 仅声明重试策略参数，具体重试时机、异常过滤、降级 fallback 全部由统一处理器实现； - ❌ 危险：
@Retry(on = "IOException.class", unless = "result != null")—— 把本该写在 Service 层的判断逻辑塞进注解属性，既难读又难调试，还绕过 IDE 类型检查。
一旦注解开始携带表达式、SpEL 或布尔逻辑，它就从“标签”退化为“微型脚本”，违背了元数据的轻量本质。
强制配套文档与 IDE 支持：让注解即文档
每个自定义注解必须满足三项硬性要求，否则禁止上线：
立即学习“Java免费学习笔记（深入）”；
- 注解类上带完整 Javadoc，说明适用场景、生效范围（
@Target）、生命周期（@Retention）和典型误用示例； - 所有属性提供清晰默认值，并标注是否必填、取值约束（如
@Min(1) @Max(10)）； - 配合
@Target({METHOD, TYPE})和@Documented，确保 IDE 能跳转到定义、显示参数提示、校验非法赋值。
没有 Javadoc 的注解，和没写的注释一样不可信；不能被 IDE 理解的注解，等于埋在代码里的黑盒。
集中处理、分层暴露：注解只出现在契约层，逻辑收口在处理器
业务方法上允许加注解，但绝不允许在注解处理器里写业务分支。正确做法是：
- Controller 或 Service 方法上使用
@Validate、@Audit、@Trace等语义化注解； - 所有注解解析逻辑统一收在框架层 AOP 切面或 Spring
@Aspect中，且切面内部只做通用动作（如反射取值、记录日志、抛统一异常）； - 真正需要分支决策的地方（如“用户 VIP 才缓存”），改用显式 if 判断 + 注解参数驱动（
@Cache(enabled = "#user.vip")），而非把判断逻辑写进注解定义。
这样调试时，断点打在切面入口就能看到所有注解生效点；出问题时，堆栈里不会出现十层嵌套的注解代理类，而是一目了然的切面方法名。
禁用“魔法注解”：拒绝无显式触发点的行为
以下注解模式一律禁止，因其完全切断调试路径：
- 无任何显式调用入口的“自动初始化”注解（如
@AutoInit在类加载时静默执行 DB 连接）； - 依赖静态块、类加载器钩子或
static {}实现的注解效果； - 未声明
@Retention(RUNTIME)却期望运行时生效的注解（编译期保留的注解无法被反射读取）。
所有注解效果，必须能通过明确的入口点（如 Spring 的 @Bean 方法、AOP 的 @Around、或手动调用 AnnotationProcessor.process()）触发和验证。
