php - 如何在接口(interface)文档中记录@throws

Question

我正在编写一个 PHP 库，但我有一个顾虑。我的界面中有类似以下内容的内容:

<?php
/**
 * My interface
 *
 * ...
 */
interface MyInterface
{
    /**
     * This method does foo.
     *
     * @throws \RuntimeException If foo can't be done.
     */
    public function fooAndBar();
}
?>

现在，@throws条目并不完全正确，因为接口(interface)实际上并不执行任何操作，而纯粹用于抽象实现细节。然而，我一直使用它，因为当出现问题时，我所有的接口(interface)实现都会抛出异常。

但是另一个开发人员可能会编写一个不会失败的实现(因此它不会抛出异常)，或者他/她可能想要使用另一个异常类。

在这种情况下，我应该如何在接口(interface)声明中记录@throws？是否应该记录下来？

Answer 1

考虑使用接口(interface)的代码:

public function doSomething(MyInterface $my) { ... }

如果其中一个实现可能会引发异常，您将需要确保处理异常的可能性。

所以，是的，应该记录下来。

即使只有一个实现抛出异常，异常处理仍然需要到位。当然，这并不意味着每个方法都应该有一个@throws。它仍然应该只在适当的地方使用(当您期望实现合法地需要抛出异常时)。

作为更具体的示例，请考虑以下内容:

interface LogWriter
{

    /**
     * @throws LogWriterException
     */
    public function write($entry);

}


class DbLogWriter
{

    public function __construct(PDO $db)
    {
        //store $db somewhere
    }

    public function write($entry)
    {
        try {
            //store $entry in the database
        } catch (PDOException $e) {
            throw new LogWriterException(...);
        }
    }

}

class NullLogWriter
{
    public function write($entry) { }
}

可以采取某些措施来尝试降低写入数据库时​​发生异常的可能性，但归根结底，这不是异常安全的操作。因此，DbLogWriter::write应该会抛出异常。

现在考虑一下空编写器，它只是丢弃条目。那里绝对不会出现任何问题，因此不需要异常(exception)。

但是如果你有一些$log怎么办？你所知道的就是它是 LogWriter 的实现。您是否认为它不会抛出异常并可能意外地让一个冒泡，或者您是否认为它可以抛出 LogWriterException ？为了安全起见，我假设它可以抛出 LogWriterException。

如果用户只知道$log是一个 LogWriter，但只有 DbLogWriter 被记录为抛出异常，用户可能没有意识到 $log->write(...) 可以抛出异常。另外，当稍后创建 FileLogWriter 时，这意味着已经设置了实现可以并且可能会抛出的异常的预期(没有人会期望 FileLogWriter 抛出 RandomNewException )。