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

接口定义合同。实现类是否抛出异常是PHP中的实现细节，因为方法签名中没有throws关键字（如Java中）。添加@throws注释不能在技术上强制执行合同，但它可以指示约定（返回值btw相同）。这是否足够好取决于你自己决定。

在旁注中，如果开发人员提出了一个不会引发问题的实现，因为无论如何都必须为那些抛出的实现添加try / catch块（按照惯例）。如果实现开始抛出与DocBlock中指示的不同的Exception，那将是一个问题，因为它不会被捕获。

Answer 2

考虑使用界面的代码：

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

如果即使其中一个实现可以抛出异常，您也需要确保处理异常的可能性。

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

即使只有一个实现抛出异常，仍然需要进行异常处理。当然，这并不意味着每个方法都应该对其进行打击。它应该仍然只在适当的地方使用（你希望实现合法地需要抛出异常）。

作为一个更具体的例子，请考虑以下事项：

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 writer，它只会丢弃条目。绝对没有什么可以在那里出错，因此，不需要例外。

然而，如果你有一些$log而且所有你知道的是它是LogWriter的实现。你是否认为它不会抛出异常并且可能意外地让一个泡沫冒出来，或者你是否认为它可以抛出LogWriterException？我会保持安全，并假设它可以抛出一个LogWriterException。

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

如何在界面文档中记录@throws

2 个答案: