阅读 749

基于@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状态码返回。其实问题也不大,接口文档最重要的是后端写的爽,前端看的明白就可以了。嗯,能偷懒就行。