如何在接口文档中记录@throws

Question

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

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

现在，@throws条目并不完全正确，因为接口实际上并不做任何事情，只是用来抽象实现细节。但是，我总是使用它，因为当出现问题时，我所有的接口实现都会抛出异常。

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

在这种情况下，我应该如何在接口声明中记录@throws？它应该被记录下来吗？

Answer 1

考虑一下使用接口的代码：

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会抛出异常。

现在考虑null写入器，它只会丢弃条目。在那里绝对没有任何可能出错的地方，因此，不需要异常。

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

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

Answer 2

接口定义契约。在PHP中，实现类是否抛出异常是一个实现细节，因为在方法签名中没有throws关键字(就像在Java中一样)。添加@throws注释在技术上不能强制执行约定，但它可以指示约定(返回值btw也是如此)。这是否足够好，由您自己决定。

顺便说一句，如果开发人员想出了一个不会抛出的实现，那就不会有问题，因为你无论如何都要为抛出的实现添加try/catch块(按照惯例)。如果一个实现开始抛出一个与DocBlock中指示的不同的异常，这将是一个问题，因为这样它就不会被捕获。