记录接口抛出的 RuntimeException

Question

我有以下界面：

public interface DataReceiver {
    public Data getData();
}

具体的接收器有不同的数据源，因此抛出不同的异常：

public class DeviceDataReceiver implements DataReceiver {
    // Gets data from some hardware device
    // Exceptions include: DeviceNotConnected, DeviceNotLicensed, RequestTimeout, etc
    public Data getData() { ... }
}

public class FileDataReceiver implements DataReceiver {
    // Gets data from a file on disc
    // Exceptions include: FileNotFound, BadFormat
    public Data getData() { ... }
}

我使用 @throws Javadoc 标签在类中记录了这些 RuntimeExceptions。

我苦苦挣扎的是如何记录界面，因为这将是我图书馆的用户在遇到错误时首先看到的东西（我在整个 public API 而不是具体的类)。记录派生类的所有异常听起来对我来说不是很有吸引力，因为它们根本没有关系。

这种情况下有什么最佳做法吗？

Answer 1

What i am struggling with is how to document the interface, since it will be the first thing a user of my library looks at, when he gets an error (I use the interface throughout my public API instead of the concrete classes). Documenting all the exceptions of the derived classes doesn't sound very appealing to me, since they have no relation at all.

如果你想记录这些异常，我认为你认为它们是为客户处理的异常。如果是这样，为什么不使用已检查的异常？
我知道有两种思考方式，但问自己这个问题很有趣。

如果您认为这些异常不是原始的，需要检查和处理（或抛出），我也不认为您需要在接口中引用它们。此外，从理论上讲，接口不应与其规范中的实现耦合。
然而，你可以在接口方法中根据实现指定什么，它可能会抛出 RuntimeException subclasses。
此外，如果你掌握了这些异常的代码源，也许你可以使用抽象class作为祖先异常，并使你的子class继承到这个抽象class。这样，您就可以在您的界面中记录这个超级异常。

最后，您的设计鼓励您的客户在使用 DataReceiver subclasses 时不要按接口编程，否则客户会冒没有特定 javadoc 的风险，并且他们不会直接看到可能抛出的特定异常使用 .
的实现方法所以，也许您还应该在界面中对其进行精确设置。

记录接口抛出的 RuntimeException

Documenting thrown RuntimeExceptions for Interfaces

java

documentation

javadoc