Java工程化实践：利用@Documented规范项目注解

在Ja va工程化实践中，@Documented 这个元注解经常被低估，但它其实是个隐藏的“效率插件”。它不改变注解的运行时行为，却能大幅提升代码可维护性和团队协作效率——只要被标注的注解出现在类、方法或字段上，Ja vadoc 工具就会自动将其纳入生成的文档中。换句话说，它能让你自定义的注解从“黑盒”变成“白纸黑字”。

让自定义注解“看得见”

很多团队会定义诸如 @ApiVersion、@DeprecatedSince 或 @TenantAware 这类业务语义注解，但默认情况下，它们不会出现在 Ja vadoc 输出里。用户查阅 API 文档时，根本看不到这些关键约束或约定。

只需在注解定义上添加 @Documented，就能让其“浮出水面”：

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.TYPE})
public @interface ApiVersion {
    String value();
}

这样，当开发者为某个接口加上 @ApiVersion("v2")，生成的 Ja vadoc 页面中，该注解及其值就会清晰显示在方法签名下方。文档自动同步，无需额外维护。

与 @Retention 和 @Target 配合使用更规范

@Documented 很少单独出场。它需要与 @Retention（决定注解保留策略）以及 @Target（限定使用位置）协同，构成完整的注解契约：

• @Retention(RetentionPolicy.SOURCE) 的注解无法在运行时读取，也不建议加 @Documented，因为仅用于编译期检查，文档意义有限；
• @Retention(RetentionPolicy.RUNTIME) 的注解最常用，配合 @Documented 能兼顾运行时反射和文档可见性；
• @Target 要准确限定作用范围，比如 @ApiVersion 不应允许加在局部变量上，否则文档会显得混乱且无意义。

一个简单的原则：如果注解需要被外部调用方理解，就让它保留到运行时并出现在文档里。

避免文档“噪音”，合理控制粒度

不是所有注解都适合加 @Documented。以下情况建议谨慎或不加：

• 纯框架内部使用的注解（如 Spring 的 @Autowired），由框架自行处理，暴露给业务开发者反而造成干扰；
• 大量重复、低信息量的标记型注解（如 @Loggable 仅表示打日志，无参数且无业务含义），容易稀释文档重点；
• 处于快速迭代中的实验性注解，尚未稳定，提前写入文档可能引发误解。

判断标准很简单：这个注解是否承载了需要被调用方明确知晓的契约、约束或语义？如果是，就值得被文档化；否则，放它一马。

集成到 CI/CD 中，确保文档同步更新

光加了 @Documented 不够，还要保证 Ja vadoc 构建真正执行并发布。可在 Ma ven 的 pom.xml 中配置：

  org.apache.ma ven.plugins
  ma ven-ja vadoc-plugin
  3.5.0
  
    
      attach-ja vadocs
      ja vadoc
    
  

再结合 CI 流程（如 Jenkins 或 GitHub Actions），每次推送代码后自动生成并部署 Ja vadoc，才能让 @Documented 发挥实际价值。

不复杂但容易忽略——一行 @Documented，换来的是团队成员对业务规则的统一理解，是新人上手时少查源码、多看文档的体验提升。