如何在界面文档中记录@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

接口定义合同.实现类是否抛出异常是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抛出a RandomNewException).