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");
        }
    }
}

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

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子类。

Javadoc @throws由错误代码处理程序

1 个答案: