如何验证自定义Runtime Exception在Javadoc中均已覆盖？

针对你维护的公共库需要持续校验公共方法是否遗漏自定义RuntimeException的@throws Javadoc声明这个需求，我整理了几个可行的方案，从现成工具到定制化实现都有，帮你解决编译器不检查RuntimeException的痛点：

一、用现成静态代码分析工具做持续校验 #

这些工具可以集成到构建流程里，每次编译/打包自动检查，不用手动操作：

• Checkstyle：这是最适合做Javadoc规则校验的工具之一。你可以配置它的JavadocThrows检查器，指定只针对你的自定义RuntimeException（比如RuntimeFooException）。具体来说，在Checkstyle的配置文件里，给JavadocThrows添加requiredThrows规则，要求只要公共方法抛出了这些自定义RuntimeException（不管是直接抛还是间接转换来的），必须在Javadoc里有对应的@throws标签说明原因。然后通过maven-checkstyle-plugin把Checkstyle集成到Maven构建中，设置为verify阶段执行，一旦发现遗漏就终止构建，强制开发者补充文档。
• IntelliJ IDEA 实时检查：在IDEA的「Settings > Editor > Inspections」里，找到「Java > Javadoc > Missing @throws tag for exception」，然后点击「Configure」，添加你的自定义RuntimeException类到需要检查的列表里。这样在开发的时候，只要你写的公共方法抛出了这些异常但没加@throws，IDEA会立刻标红提示，从源头避免遗漏。还可以把这个Inspection Profile导出给团队成员共享，确保所有人的开发环境都有同样的检查。
• SpotBugs/FindBugs 自定义检测器：虽然这类工具主要找代码bug，但你可以写一个自定义检测器，扫描所有公共方法的字节码，检查方法中是否抛出了你的自定义RuntimeException，同时检查对应的Javadoc是否存在@throws标签。如果没有，就标记为bug。这种方式可以处理一些间接抛出的情况（比如私有方法抛CheckedException转Runtime的场景）。

二、开发自定义Maven插件（深度贴合你的场景） #

你提到已经有初始项目，那完全可以自己开发一个Maven插件，精准适配你的异常转换逻辑：

1. 用JavaParser或者ASM解析项目的源代码/字节码，遍历所有公共方法；
2. 追踪方法的调用链，比如像你例子里的publicMethod调用privateMethod1，后者又调用privateMethod2抛出CheckedFooException，最终在publicMethod转成RuntimeFooException——插件需要识别这种间接转换的情况，判断publicMethod需要添加@throws RuntimeFooException的Javadoc；
3. 检查该公共方法的Javadoc是否包含对应的@throws标签和原因描述；
4. 在Maven的verify阶段执行插件，发现遗漏就抛出错误，阻止构建。

这种方案完全定制化，能完美处理你那种「私有方法抛CheckedException，公共方法转RuntimeException」的场景，比正则搜索靠谱得多。

三、优化你现有的CheckedException转Runtime方案 #

如果你暂时不想开发插件，可以优化之前的思路，减少繁琐性：

• 封装一个统一的异常转换工具类，把重复的try-catch逻辑抽出来：

  public class ExceptionWrapper {
      public static RuntimeFooException wrap(CheckedFooException e) {
          return new RuntimeFooException(e);
      }
  }
  

  这样公共方法里的代码会简洁很多：

  public void publicMethod() {
      try {
          privateMethod1();
      } catch (CheckedFooException e) {
          throw ExceptionWrapper.wrap(e);
      }
  }
  

• 然后用Checkstyle的正则检查，或者写一个简单的Groovy脚本集成到Maven构建中，扫描所有调用ExceptionWrapper.wrap(CheckedFooException)的公共方法，检查它们的Javadoc是否包含@throws RuntimeFooException。比如用JavaParser遍历源代码，找到所有这类方法，再检查Javadoc标签。

额外小技巧 #

给你的自定义RuntimeException类加一个专属注解，比如@DocumentedRuntime，这样静态分析工具或者自定义插件可以通过注解快速识别需要检查的异常，不用硬编码类名，后续新增异常类也更方便扩展。

内容的提问来源于stack exchange，提问作者Benny Bottema