注解驱动开发是围绕元数据构建可预测、可复用、低侵入的协作机制，核心在于注解声明意图、框架执行意图；需明确区分编译期（APT）与运行时（反射）处理场景，遵循最小完备原则设计注解，并配套可测试、可调试的基础设施，优先协同主流框架而非重复造轮子。
注解驱动开发（Annotation-Driven Development）不是简单地“加几个注解”，而是围绕元数据构建一套可预测、可复用、低侵入的协作机制。核心在于：让注解成为意图的声明，让处理器或框架成为意图的执行者。设计得当，能显著减少样板代码、提前暴露问题、统一约束逻辑。
明确注解职责边界：编译期 vs 运行时
混淆使用场景是效率低下的主因。必须在设计之初就决定注解生命周期和处理时机：
- 编译期处理（APT）：适用于生成代码、强制校验、类型安全增强。例如 @GenerateBuilder、@Data（Lombok）、自定义参数校验注解配合 APT 生成校验逻辑。优势是零运行时开销、IDE 可跳转、编译失败即知错。
-
运行时处理（反射）：适用于动态行为控制，如 Spring 的 @Autowired（依赖查找）、@Transactional（AOP 拦截）、@RequestMapping（路由分发）。需确保注解声明为
@Retention(RetentionPolicy.RUNTIME)，并搭配 Bean 后置处理器或 AOP 切面。 - 避免把本该编译期完成的事拖到运行时——比如字段非空校验，用
@NotBlank+@Valid是运行时方案；若想在编译阶段就报错（如 DTO 字段缺失必填注解），就得配套写一个 APT 校验器。
设计自定义注解时遵循最小完备原则
一个好注解应语义清晰、职责单一、易于组合。不要试图用一个注解解决所有问题：
- 用
@Target精确限定作用位置（如只允许标在方法上，就别放开到类或参数）； - 用
@Retention明确保留策略（SOURCE 足够就不用 CLASS 或 RUNTIME）； - 成员尽量少而必要，优先提供默认值。例如日志注解
@LogExecution(level = Level.INFO)比@LogExecution(level = "INFO", includeArgs = true, excludeReturn = false)更易用； - 支持组合注解：如 Spring 的
@GetMapping就是@RequestMapping(method = RequestMethod.GET)的语义封装，开发者无需记忆底层细节。
配套基础设施要轻量、可测试、可调试
注解本身只是“开关”，真正提效的是背后可信赖的支撑链路：
立即学习“Java免费学习笔记（深入）”；
- APT 处理器必须通过
Filer生成合法 Java 源码，并用Messager输出清晰错误信息（如 “@Retryable 不能用于 static 方法”），而不是抛异常静默失败； - 运行时处理器（如 Spring 的
BeanPostProcessor）应避免复杂逻辑，优先委托给专门组件（如校验交由Validator，事务交由TransactionInterceptor）； - 所有注解逻辑都应有对应单元测试：对 APT，测试生成的源码是否符合预期；对运行时，用模拟上下文验证行为是否触发；
- 提供调试钩子：比如在 APT 中添加
-XprintProcessorInfo日志开关，或在 Spring 注解处理器中输出“已处理类 X 的 Y 注解”便于排查漏扫。
与主流框架协同，不重复造轮子
不要孤立设计注解体系。优先适配已有生态，降低学习与集成成本：
- Web 层直接用 Spring MVC 的
@PathVariable、@RequestHeader，而非另建一套 HTTP 参数绑定注解； - 数据持久层用 JPA 的
@Entity、@Column，再叠加自定义扩展（如@Encrypt表示字段需加密存储），而非从头设计 ORM 注解； - 校验统一基于 Jakarta Bean Validation（
@NotNull,@Size），再通过ConstraintValidator实现业务规则，保持校验语义一致； - 若需跨框架能力（如同时支持 Spring 和 Micrometer），注解定义应保持纯接口，实现逻辑下沉到 SPI 或抽象模块。
