最佳實踐：在php-doc中使用@throws，以及如何處理它

Question

假設我有一個類，有這樣的方法：

/*
 *
 * Loads the user from username.
 *
 * @param string $username The username
 *
 * @return UserInterface
 *
 * @throws userNotFoundException if the user is not found
 */
public function getUser($username)
{
    // someFunction return an UserInterface class if found, or null if not.
    $user = someFunction('SELECT ....', $username);
    if ($user === null) {
        throw new userNotFoundException();
    }

    return $user
}

現在讓我們假設someFunction可能因XYZ原因而拋出InvalidArgumentException / RuntimeException / PDOException 。 我該怎么辦？ 什么不是？

1號

添加所有可能在php-docs中拋出someFunction異常。

/*
 *
 * Loads the user from username.
 *
 * @param string $username The username
 *
 * @return UserInterface
 *
 * @throws userNotFoundException if the user is not found
 * @throws InvalidArgumentException
 * @throws ...
 */

2號

添加try-catch塊以確保該方法僅拋出異常文檔

/*
 *
 * Loads the user from username.
 *
 * @param string $username The username
 *
 * @return UserInterface
 *
 * @throws userNotFoundException if the user is not found
 * @throws RuntimeException 
 */
public function getUser($username)
{
    try {
        $user = someFunction('SELECT ....', $username);
    } catch (Exception $e) {
        throw new RuntimeException();
    }

    if ($user === null) {
        throw new userNotFoundException();
    }

    return $user
}

3號

什么都不做

Answer 1

就個人而言，我會考慮將@throws視為類似於Java的已檢查異常

它在Java中的工作方式是，基本上可以拋出從RuntimeException繼承的異常，而不必處理。 任何其他類型的異常必須有一個try-catch塊來處理它們。 此處理代碼必須在調用者中。

基本上在PHP中有點像這樣：

當方法具有@throws注釋時，您必須添加代碼來處理其異常。

在調用代碼中處理時，任何未提及的異常都是可選的。

---

現在，我不是100％自己遵循這個原則。 整個處理異常的事情取決於程序員的偏好，但這只是關於我認為如何以合理的方式處理它的一些想法。

Answer 2

關於文檔，如果函數顯式拋出異常，那么它應該包含在函數的文檔中。 因此，對於每個throw語句，PHP文檔中應該有相應的@throws 。

關於處理，如果在拋出異常時應該執行某些操作，則捕獲它。 否則，讓它冒泡 - 只要有一個catch語句將在以后處理它。

更新：

幾年后，我改變了這樣一種觀點，即當異常仍然與模塊的抽象級別相關時，應該只允許異常“冒泡”未修改。 應采用捕獲和重新投擲策略使異常更有意義。 它還應該通過避免不必要地披露有關抽象的模塊的信息來使錯誤處理更安全。

/**
 * @throws UserNotFoundException
 */
public function getUser($username)
{
    try {
        $user = someFunction('SELECT ....', $username);
    } catch (DatabaseException $dbe) {

        /* Re-throw since a database exception may no longer be
         * meaningful to the caller.
         */
        throw new UserNotFoundException();
    }

    return $user
}

Answer 3

從文檔維護的角度來看，我只會為特別拋出的異常添加@throw行，否則您將很快得到過時的文檔。

Answer 4

第二 ，但也許在返回之前拋出，因為拋出動作將在返回之前發生...