记录由未知参数引起的异常的最佳实践

Question

这是一个最佳实践问题。我希望在这里提出这个问题是可以的。我正在创建一个将用作API的一部分的接口。我有一个名为getSomeObject()的方法，它在幕后有一个计算逻辑并返回SomeObject。我在后面调用抛出IllegalArgumentException的方法，因此我的getSomeObject()方法可能会抛出此异常。我遇到的问题是API的用户不熟悉API的内部工作方式，也不理解抛出异常的原因。由于参数是在我的方法中创建的，并且用户甚至不知道该参数存在。我试图记录它，但这种异常的原因会使API的用户感到困惑。所以我的问题是，这样的情况最好的方法是什么？记录此异常的正确方法是什么？

Answer 1

从不带任何参数的方法中抛出IllegalArgumentException确实令人困惑。

如果未正确定义getSomeObject之外的某些内容，我认为您会收到该异常。所以你可以抛出一个IllegalStateException，并在你的javadoc中用解释记录它：

@throws IllegalStateException If member variable xyz is not initialised.  
                              This can happen if method `init()` has not been   
                              called before `getSomeObject`.

Answer 2

当你说你的内部代码有可能抛出IllegalArgumentException时，你是如何处理它的？
是由用户输入错误引起的吗？
如果没有那么你应该抓住它并处理它，如果你仍然必须抛出它，它必须转化为一个例外，用户可以理解
或者这种情况发生的可能性不大，纯粹是理论上的？
如果这是用户应该处理的有效异常情况，则应抛出适当的已检查异常并在界面中声明它