Java编译报错unreported exception <XXX>的含义、原理及修复方法

Java新手开发者经常会遇到如下形式的编译报错：

error: unreported exception <XXX>; must be caught or declared to be thrown

报错信息中的<XXX>代表某一异常类的类名，以下是对应问题的解答：

这是Java编译器在静态检查阶段抛出的语法错误，直白解释就是：你的代码里存在可能抛出<XXX>类型异常的执行逻辑，但你既没有编写代码捕获处理这个异常，也没有在当前方法的签名上声明该方法可能抛出这个异常，违反了Java的语法强制要求，编译器直接阻断编译流程。

触发该错误的核心是Java语言设计的受检异常（Checked Exception）强制校验机制：

• Java将所有异常分为两大类：
  • 受检异常：除了RuntimeException、Error及其子类之外的所有异常，编译器对这类异常有强制处理要求
  • 非受检异常：RuntimeException、Error及其子类，比如常见的空指针异常NullPointerException、参数非法异常IllegalArgumentException都属于这类，编译器不做强制处理要求
• 针对受检异常，Java语言规范明确要求：如果方法内的执行逻辑（包括调用声明了抛出受检异常的JDK/第三方方法、手动通过throw关键字抛出受检异常实例）可能抛出某类受检异常，开发者必须在两种处理方案中二选一，没有其他合规选项：
  1. 在当前方法内部通过try-catch块捕获对应异常，编写异常发生后的处理逻辑
  2. 在当前方法的签名上通过throws关键字声明本方法可能抛出该异常，将异常处理的责任转交给当前方法的上层调用者
• 你看到这个报错，本质就是编译器检查到代码里存在未按上述规则处理的受检异常，直接报错提示。

最常见的触发场景示例（报错中XXX为FileNotFoundException）：

// 这段代码无法通过编译，会直接抛出题目中的错误
public void loadFile() {
    // FileInputStream的构造方法明确声明会抛出FileNotFoundException（受检异常）
    FileInputStream inputStream = new FileInputStream("./config.properties");
}

根据业务场景选择以下两种合规方案即可：

• 方案1：在当前方法内捕获并处理异常
  用try-catch块包裹可能抛出异常的代码段，在catch块中编写异常发生后的实际处理逻辑（比如记录错误日志、提示用户操作有误、回收已打开的资源等），示例：

  public void loadFile() {
      try {
          FileInputStream inputStream = new FileInputStream("./config.properties");
      } catch (FileNotFoundException e) {
          // 编写实际处理逻辑，比如打印异常栈方便排查、提示用户配置文件不存在
          e.printStackTrace();
      }
  }
  

• 方案2：在方法签名上声明抛出异常，将处理权交给上层调用者
  如果当前方法的定位是工具方法、不适合直接处理异常，可以直接在方法签名后追加throws 对应异常类名，让调用该方法的上层逻辑来处理这个异常，示例：

  // 声明方法会抛出FileNotFoundException，所有调用loadFile的位置都需要按规则处理该异常
  public void loadFile() throws FileNotFoundException {
      FileInputStream inputStream = new FileInputStream("./config.properties");
  }
  

修复时注意避开新手常见的坑：

• 不要为了省事直接捕获顶层的Exception甚至Throwable，会把所有非预期的异常一并吞掉，后续出问题极难排查
• 不要写空的catch块，异常发生后没有任何处理逻辑会直接掩盖问题，导致故障定位成本极高
• 非受检异常不需要做上述处理，编译器不会对这类异常做强制检查

内容的提问来源于stack exchange，提问作者Stephen C