亚洲在线久爱草,狠狠天天香蕉网,天天搞日日干久草,伊人亚洲日本欧美

首頁 慕課教程 RESTful 規范教程 RESTful 規范教程 13 異常處理與自動生成文檔
ExcellentDavid · 更新于 2020-04-14

異常處理與自動生成文檔

“圣人千慮，必有一失”，程序也是如此。當 RESTful Web API 服務器發生異常，該如何處理呢？構建好的 RESTful Web API，客戶端開發人員又該如何調用呢？這一節，我們就為大家一一道來。

1.異常處理

當遇到異常時，Django Rest framework 會自動捕獲，并按默認邏輯處理。我們也可以通過自定義異常處理函數來實現對異常的處理。

from rest_framework.views import exception_handler

def custom_exception_handler(exc, context):
    # 先調用REST framework默認的異常處理方法獲得標準錯誤響應對象
    response = exception_handler(exc, context)

    # 在此處補充自定義的異常處理
    if response is not None:
        response.data['status_code'] = response.status_code

    return response

在配置文件中聲明自定義的異常處理

REST_FRAMEWORK = {
    'EXCEPTION_HANDLER': 'my_project.my_app.utils.custom_exception_handler'
}

如果未聲明，會采用默認的方式，如下

REST_FRAMEWORK = {
    'EXCEPTION_HANDLER': 'rest_framework.views.exception_handler'
}

例如：

補充上處理關于數據庫的異常

from rest_framework.views import exception_handler as drf_exception_handler
from rest_framework import status
from django.db import DatabaseError

def exception_handler(exc, context):
    response = drf_exception_handler(exc, context)

    if response is None:
        view = context['view']
        if isinstance(exc, DatabaseError):
            print('[%s]: %s' % (view, exc))
            response = Response({'detail': '服務器內部錯誤'}, status=status.HTTP_507_INSUFFICIENT_STORAGE)

    return response

2.REST framework 提供的異常類

  • APIException 所有異常的父類；

  • ParseError 解析錯誤；

  • AuthenticationFailed 認證失敗；

  • NotAuthenticated 尚未認證；

  • PermissionDenied 權限決絕；

  • NotFound 未找到；

  • MethodNotAllowed 請求方式不支持；

  • NotAcceptable 要獲取的數據格式不支持；

  • Throttled 超過限流次數；

  • ValidationError 校驗失敗。

3.自動生成接口文檔

在前后端分離的項目中，在完成接口的開發之后，后端開發人員需要為前端人員編寫接口文檔，介紹接口調用方法和需要傳遞的參數。在 Django Rest framework 編寫接口后，可以自動生成接口文檔，這無疑減輕了不少工作量。

接口文檔以網頁的方式呈現，在生產接口文檔前，需要做如下操作：

3.1 安裝依賴

Django Rest framework 自動生成接口文檔，需要coreapi庫的支持，在終端輸入如下命令：

pip install coreapi

3.2 在設置文件中進行配置

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'
}

3.3 配置接口文檔訪路由地址

在總路由中添加接口文檔路徑。

文檔路由對應的視圖配置為rest_framework.documentation.include_docs_urls，

參數title為接口文檔網站的標題。

from rest_framework.documentation import include_docs_urls

urlpatterns = [
    ...
    path('docs/', include_docs_urls(title='接口文檔'))
]

4. 文檔描述說明的定義位置

  1. 單一方法的視圖，可直接使用類視圖的文檔字符串，如：
class StudentView(generics.ListAPIView):
    """
    返回所有學生信息.
    """
  1. 包含多個方法的視圖，在類視圖的文檔字符串中，分開方法定義，如：
class StudentListCreateView(generics.ListCreateAPIView):
    """
    get:
    返回所有學生信息.

    post:
    新建學生信息.
    """
  1. 對于視圖集 ViewSet，仍在類視圖的文檔字符串中分開定義，但是應使用操作動作名稱來區分，如：
class BookInfoViewSet(mixins.ListModelMixin, mixins.RetrieveModelMixin, GenericViewSet):
    """
    list:
    返回學生列表數據

    retrieve:
    返回學生詳情數據

    latest:
    返回最新的學生數據
    """

5. 訪問接口文檔網頁

注意：

  1. 視圖集 ViewSet 中的 retrieve 方法，在接口文檔中被稱作 read；

  2. 參數的 Description 需要在模型類或序列化器類的字段中以 help_text 選項定義，如：

class StudentsModel(models.Model):
    ...
    s_name = models.CharField(max_length=8, verbose_name='學生姓名', help_text='學生姓名')
    ...

6.小結

本小節為大家介紹了 API 實現過程中異常處理和 API 文檔的生成。熟練運用異常處理技巧，可以很大程度上避免程序出錯，保證穩定運行。API 文檔的生成功能，可以快速生成 API 使用手冊，而無需另外書寫，這讓廣大程序員擺脫了寫文檔的煩惱。