Laravel核心解讀–異常處理

kevinyan發表於2019-05-13
Laravel

異常處理是程式設計中十分重要但也最容易被人忽視的語言特性，它為開發者提供了處理程式執行時錯誤的機制，對於程式設計來說正確的異常處理能夠防止洩露程式自身細節給使用者，給開發者提供完整的錯誤回溯堆疊，同時也能提高程式的健壯性。

這篇文章我們來簡單梳理一下Laravel中提供的異常處理能力，然後講一些在開發中使用異常處理的實踐，如何使用自定義異常、如何擴充套件Laravel的異常處理能力。

註冊異常Handler

這裡又要回到我們說過很多次的Kernel處理請求前的bootstrap階段，在bootstrap階段的IlluminateFoundationBootstrapHandleExceptions 部分中Laravel設定了系統異常處理行為並註冊了全域性的異常處理器:

class HandleExceptions
{
    public function bootstrap(Application $app)
    {
        $this->app = $app;

        error_reporting(-1);

        set_error_handler([$this, `handleError`]);

        set_exception_handler([$this, `handleException`]);

        register_shutdown_function([$this, `handleShutdown`]);

        if (! $app->environment(`testing`)) {
            ini_set(`display_errors`, `Off`);
        }
    }
    
    
    public function handleError($level, $message, $file = ``, $line = 0, $context = [])
    {
        if (error_reporting() & $level) {
            throw new ErrorException($message, 0, $level, $file, $line);
        }
    }
}

set_exception_handler([$this, `handleException`])將HandleExceptions的handleException方法註冊為程式的全域性處理器方法:

public function handleException($e)
{
    if (! $e instanceof Exception) {
        $e = new FatalThrowableError($e);
    }

    $this->getExceptionHandler()->report($e);

    if ($this->app->runningInConsole()) {
        $this->renderForConsole($e);
    } else {
        $this->renderHttpResponse($e);
    }
}

protected function getExceptionHandler()
{
    return $this->app->make(ExceptionHandler::class);
}

// 渲染CLI請求的異常響應
protected function renderForConsole(Exception $e)
{
    $this->getExceptionHandler()->renderForConsole(new ConsoleOutput, $e);
}

// 渲染HTTP請求的異常響應
protected function renderHttpResponse(Exception $e)
{
    $this->getExceptionHandler()->render($this->app[`request`], $e)->send();
}

在處理器裡主要通過ExceptionHandler的report方法上報異常、這裡是記錄異常到storage/laravel.log檔案中，然後根據請求型別渲染異常的響應生成輸出給到客戶端。這裡的ExceptionHandler就是AppExceptionsHandler類的例項，它是在專案最開始註冊到服務容器中的：

// bootstrap/app.php

/*
|--------------------------------------------------------------------------
| Create The Application
|--------------------------------------------------------------------------
*/

$app = new IlluminateFoundationApplication(
    realpath(__DIR__.`/../`)
);

/*
|--------------------------------------------------------------------------
| Bind Important Interfaces
|--------------------------------------------------------------------------
*/
......

$app->singleton(
    IlluminateContractsDebugExceptionHandler::class,
    AppExceptionsHandler::class
);

這裡再順便說一下set_error_handler函式，它的作用是註冊錯誤處理器函式，因為在一些年代久遠的程式碼或者類庫中大多是採用PHP那件函式trigger_error函式來丟擲錯誤的，異常處理器只能處理Exception不能處理Error，所以為了能夠相容老類庫通常都會使用set_error_handler註冊全域性的錯誤處理器方法，在方法中捕獲到錯誤後將錯誤轉化成異常再重新丟擲，這樣專案中所有的程式碼沒有被正確執行時都能丟擲異常例項了。

/**
 * Convert PHP errors to ErrorException instances.
 *
 * @param  int  $level
 * @param  string  $message
 * @param  string  $file
 * @param  int  $line
 * @param  array  $context
 * @return void
 *
 * @throws ErrorException
 */
public function handleError($level, $message, $file = ``, $line = 0, $context = [])
{
    if (error_reporting() & $level) {
        throw new ErrorException($message, 0, $level, $file, $line);
    }
}

常用的Laravel異常例項

Laravel中針對常見的程式異常情況丟擲了相應的異常例項，這讓開發者能夠捕獲這些執行時異常並根據自己的需要來做後續處理（比如：在catch中呼叫另外一個補救方法、記錄異常到日誌檔案、傳送報警郵件、簡訊）

在這裡我列一些開發中常遇到異常，並說明他們是在什麼情況下被丟擲的，平時編碼中一定要注意在程式裡捕獲這些異常做好異常處理才能讓程式更健壯。

  • IlluminateDatabaseQueryException Laravel中執行SQL語句發生錯誤時會丟擲此異常，它也是使用率最高的異常，用來捕獲SQL執行錯誤，比方執行Update語句時很多人喜歡判斷SQL執行後判斷被修改的行數來判斷UPDATE是否成功，但有的情景裡執行的UPDATE語句並沒有修改記錄值，這種情況就沒法通過被修改函式來判斷UPDATE是否成功了，另外在事務執行中如果捕獲到QueryException 可以在catch程式碼塊中回滾事務。
  • IlluminateDatabaseEloquentModelNotFoundException 通過模型的findOrFail和firstOrFail方法獲取單條記錄時如果沒有找到會丟擲這個異常(find和first找不到資料時會返回NULL)。
  • IlluminateValidationValidationException 請求未通過Laravel的FormValidator驗證時會丟擲此異常。
  • IlluminateAuthAccessAuthorizationException 使用者請求未通過Laravel的策略（Policy）驗證時丟擲此異常
  • SymfonyComponentRoutingExceptionMethodNotAllowedException 請求路由時HTTP Method不正確
  • IlluminateHttpExceptionsHttpResponseException Laravel的處理HTTP請求不成功時丟擲此異常

擴充套件Laravel的異常處理器

上面說了Laravel把AppExceptionsHandler 註冊成功了全域性的異常處理器，程式碼中沒有被catch到的異常，最後都會被AppExceptionsHandler捕獲到，處理器先上報異常記錄到日誌檔案裡然後渲染異常響應再傳送響應給客戶端。但是自帶的異常處理器的方法並不好用，很多時候我們想把異常上報到郵件或者是錯誤日誌系統中，下面的例子是將異常上報到Sentry系統中，Sentry是一個錯誤收集服務非常好用：

public function report(Exception $exception)
{
    if (app()->bound(`sentry`) && $this->shouldReport($exception)) {
        app(`sentry`)->captureException($exception);
    }

    parent::report($exception);
}

還有預設的渲染方法在表單驗證時生成響應的JSON格式往往跟我們專案裡統一的JOSN格式不一樣這就需要我們自定義渲染方法的行為。

public function render($request, Exception $exception)
{
    //如果客戶端預期的是JSON響應,  在API請求未通過Validator驗證丟擲ValidationException後
    //這裡來定製返回給客戶端的響應.
    if ($exception instanceof ValidationException && $request->expectsJson()) {
        return $this->error(422, $exception->errors());
    }

    if ($exception instanceof ModelNotFoundException && $request->expectsJson()) {
        //捕獲路由模型繫結在資料庫中找不到模型後丟擲的NotFoundHttpException
        return $this->error(424, `resource not found.`);
    }


    if ($exception instanceof AuthorizationException) {
        //捕獲不符合許可權時丟擲的 AuthorizationException
        return $this->error(403, "Permission does not exist.");
    }

    return parent::render($request, $exception);
}

自定義後，在請求未通過FormValidator驗證時會丟擲ValidationException， 之後異常處理器捕獲到異常後會把錯誤提示格式化為專案統一的JSON響應格式並輸出給客戶端。這樣在我們的控制器中就完全省略了判斷表單驗證是否通過如果不通過再輸出錯誤響應給客戶端的邏輯了，將這部分邏輯交給了統一的異常處理器來執行能讓控制器方法瘦身不少。

使用自定義異常

這部分內容其實不是針對Laravel框架自定義異常，在任何專案中都可以應用我這裡說的自定義異常。

我見過很多人在Repository或者Service類的方法中會根據不同錯誤返回不同的陣列，裡面包含著響應的錯誤碼和錯誤資訊，這麼做當然是可以滿足開發需求的，但是並不能記錄發生異常時的應用的執行時上下文，發生錯誤時沒辦法記錄到上下文資訊就非常不利於開發者進行問題定位。

下面的是一個自定義的異常類

namespace AppExceptions;

use RuntimeException;
use Throwable;

class UserManageException extends RuntimeException
{
    /**
     * The primitive arguments that triggered this exception
     *
     * @var array
     */
    public $primitives;
    /**
     * QueueManageException constructor.
     * @param array $primitives
     * @param string $message
     * @param int $code
     * @param Throwable|null $previous
     */
    public function __construct(array $primitives, $message = "", $code = 0, Throwable $previous = null)
    {
        parent::__construct($message, $code, $previous);
        $this->primitives = $primitives;
    }

    /**
     * get the primitive arguments that triggered this exception
     */
    public function getPrimitives()
    {
        return $this->primitives;
    }
}

定義完異常類我們就能在程式碼邏輯中丟擲異常例項了

class UserRepository
{
  
    public function updateUserFavorites(User $user, $favoriteData)
    {
        ......
        if (!$executionOne) {
            throw new UserManageException(func_get_args(), `Update user favorites error`, `501`);
        }
        
        ......
        if (!$executionTwo) {
            throw new UserManageException(func_get_args(), `Another Error`, `502`);
        }
        
        return true;
    }
}

class UserController extends ...
{
    public function updateFavorites(User $user, Request $request)
    {
        .......
        $favoriteData = $request->input(`favorites`);
        try {
            $this->userRepo->updateUserFavorites($user, $favoritesData);
        } catch (UserManageException $ex) {
            .......
        }
    }
}

除了上面Repository列出的情況更多的時候我們是在捕獲到上面列舉的通用異常後在catch程式碼塊中丟擲與業務相關的更細化的異常例項方便開發者定位問題，我們將上面的updateUserFavorites 按照這種策略修改一下

public function updateUserFavorites(User $user, $favoriteData)
{
    try {
        // database execution
        
        // database execution
    } catch (QueryException $queryException) {
        throw new UserManageException(func_get_args(), `Error Message`, `501` , $queryException);
    }

    return true;
}

在上面定義UserMangeException類的時候第四個引數$previous是一個實現了Throwable介面類例項，在這種情景下我們因為捕獲到了QueryException的異常例項而丟擲了UserManagerException的例項，然後通過這個引數將QueryException例項傳遞給PHP異常的堆疊，這提供給我們回溯整個異常的能力來獲取更多上下文資訊，而不是僅僅只是當前丟擲的異常例項的上下文資訊， 在錯誤收集系統可以使用類似下面的程式碼來獲取所有異常的資訊。

while($e instanceof Exception) {
    echo $e->getMessage();
    $e = $e->getPrevious();
}

異常處理是PHP非常重要但又容易讓開發者忽略的功能，這篇文章簡單解釋了Laravel內部異常處理的機制以及擴充套件Laravel異常處理的方式方法。更多的篇幅著重分享了一些異常處理的程式設計實踐，這些正是我希望每個讀者都能看明白並實踐下去的一些程式設計習慣，包括之前分享的Interface的應用也是一樣。

相關文章