错误代码处理程序抛出的异常的 Javadoc @throws 标记

Question

我正在将 C Api 桥接到 Java Api。 C Api 对异常情况使用错误代码。由于每个函数都返回这样一个错误代码并且有很多错误代码（大约 100 个），我编写了一个错误代码处理程序，将错误代码转换为一堆更一般的运行时异常：

public class ErrorCodeHandler {
    public static void handle(int status) {
        switch(status) {
            case SUCCESS:
                return; // In case of success, simply return
            case NO_VALID_DATA:
                throw new DataError("No valid data");
            ...
            case NO_CONNECTION:
                throw new ConnectionError("No connection");
        }
    }
}

我所有的自定义异常类都继承自特定于我的应用程序的基本异常类：

public class MyException extends RuntimeException { ... }
public class DataException extends MyException { ... }
...

我的方法只是对调用 C API 返回的错误代码调用句柄：

public void someMethod() {
    int status = cBinding.someMethod();
    ErrorCodeHandler.handle(status);
}

如果发生错误，该方法将抛出相应的异常。如果没有，它会简单地返回。

现在我面临如何记录这种异常处理的问题。我读到您没有将运行时异常添加为 throws 子句，而是使用 Javadoc @throws 标记对其进行记录。

现在我的问题是，我应该为每个我知道可以从方法抛出的不同异常添加一个@throws 标签（间接通过查找可能的错误代码），还是应该只记录一个通用的@throws MyException？我觉得第一种方法会使我的文档变得混乱，其中包含许多大部分无用的 @throws 标签（很多这些错误代码非常罕见），并且记录这些将是一项非常艰巨的工作。第二种方法主要是复制粘贴，但我会失去异常层次结构给我的优势。

有没有人做过类似的事情？有关如何记录此类内容的任何建议？

Answer 1

在你的 javadoc 中写 @throws MyException if underlying service fails 这样的东西是完全合理的。它在 Java SE 中相当普遍；例如：

• Files.copy 只有 @throws 子句用于 IOException 和 IOException 的两个子类，尽管它可以抛出许多其他 IOException 子类。
• JDBC 方法 Statement.execute 有一个用于 SQLException 的 @throws 子句和一个 SQLException 子类，尽管还有许多其他 SQLException 子类可以抛出。