基於@nestjs/swagger，封裝自定義異常響應的裝飾器

概念

Swagger 是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。

Nest 是用於構建高效且可伸縮Web應用程序的漸進式 Node.js 框架。

@nestjs/swagger 是爲Nest定製的Swagger模塊，用裝飾器的方式來生成描述RESTful api的文檔。

背景

爲了自定義描述某個接口的響應，能夠使用@ApiResponse()，示例代碼以下：

@ApiResponse({ status: 403, description: 'Forbidden.'})
複製代碼

此外，爲了方便與Nest內置的常見異常相對應，@nestjs/swagger封裝了一系列常見的異常響應：

@ApiOkResponse()
@ApiCreatedResponse()
@ApiBadRequestResponse()
@ApiUnauthorizedResponse()
@ApiNotFoundResponse()
@ApiForbiddenResponse()
@ApiMethodNotAllowedResponse()
@ApiNotAcceptableResponse()
@ApiRequestTimeoutResponse()
@ApiConflictResponse()
@ApiGoneResponse()
@ApiPayloadTooLargeResponse()
@ApiUnsupportedMediaTypeResponse()
@ApiUnprocessableEntityResponse()
@ApiInternalServerErrorResponse()
@ApiNotImplementedResponse()
@ApiBadGatewayResponse()
@ApiServiceUnavailableResponse()
@ApiGatewayTimeoutResponse()
複製代碼

可是對於自定義的異常響應，仍是須要用@ApiResponse()去實現，每次都要手寫錯誤碼和錯誤信息。

內容

基於能偷懶就毫不多幹活的懶人理念，筆者封裝了一個@ApiFailResponse()來實現根據自定義異常來描述異常響應。示例代碼以下：

@ApiFailResponse({
    type: ApiErrorException,
})
複製代碼

最終效果以下圖：

咱們能夠看到只須要傳入一個異常類，就能夠把錯誤碼和對應的描述在接口文檔中呈現出來，一切都顯得so easy。那麼接下來，讓咱們看看ApiFailResponse的具體實現，代碼以下：

export const ApiFailResponse = (metadata: ResponseMetadata) => {
    // 獲取參數type中的異常類型，並實例化
    const type: AppException = new metadata.type()
    return ApiResponse({
        ...metadata,
        status: type.getStatusCode(),
        description: type.getMsg(),
    })
}
複製代碼

Tip：ApiErrorException繼承於AppException，AppException是筆者本身封裝的異常類型，getStatusCode()方法可獲取錯誤碼，getMsg()可獲取錯誤信息。

具體實現參考上篇文章《如何封裝一個Nest風格的異常》
複製代碼

ApiFailResponse首先實例化一個異常，再獲取異常的錯誤碼和錯誤信息，賦值給status和description。用這種方式就把異常的錯誤碼和錯誤信息暴露給Swagger接口文檔。

尾聲

在這裏可能有人提出疑問，status的本意應該是指http狀態碼，而不是錯誤碼。那麼爲何不把錯誤和錯誤信息，都放到description中？這樣status就仍是能保持本意。

其實這是由於swagger在一個接口中，相同status只能描述一個響應。也就是說，咱們沒法同時描述兩個status都爲200的響應。因此這裏才把錯誤碼當作http狀態碼返回。其實問題也不大，接口文檔最重要的是後端寫的爽，前端看的明白就能夠了。嗯，能偷懶就行。