07-01 其他功能組件

其他功能組件

1、過濾Filtering

對於列表數據可能需要根據字段進行過濾，我們可以通過添加django-fitlter擴展來增強支持。

pip install django-filter

在配置文件中增加過濾后端的設置：

INSTALLED_APPS = [
    ...
    'django_filters',  # 需要注冊應用，
]

REST_FRAMEWORK = {
    ...
    'DEFAULT_FILTER_BACKENDS': ('django_filters.rest_framework.DjangoFilterBackend',)
}

在視圖中添加filter_fields屬性，指定可以過濾的字段

class BookListView(ListAPIView):
    queryset = BookInfo.objects.all()
    serializer_class = BookInfoSerializer
    filter_fields = ('btitle', 'bread')

# 127.0.0.1:8000/books/?btitle=西游記

2、排序

對於列表數據，REST framework提供了OrderingFilter過濾器來幫助我們快速指明數據按照指定字段進行排序。

使用方法：

在類視圖中設置filter_backends，使用rest_framework.filters.OrderingFilter過濾器，REST framework會在請求的查詢字符串參數中檢查是否包含了ordering參數，如果包含了ordering參數，則按照ordering參數指明的排序字段對數據集進行排序。

前端可以傳遞的ordering參數的可選字段值需要在ordering_fields中指明。

示例：

class BookListView(ListAPIView):
    queryset = BookInfo.objects.all()
    serializer_class = BookInfoSerializer
    filter_backends = [OrderingFilter]
    ordering_fields = ('id', 'bread', 'bpub_date')

# 127.0.0.1:8000/books/?ordering=-bread

3、分頁Pagination

REST framework提供了分頁的支持。

我們可以在配置文件中設置全局的分頁方式，如：

REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS':  'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 100  # 每頁數目
}

也可通過自定義Pagination類，來為視圖添加不同分頁行為。在視圖中通過pagination_clas屬性來指明。

class LargeResultsSetPagination(PageNumberPagination):
    page_size = 1000
    page_size_query_param = 'page_size'
    max_page_size = 10000
class BookDetailView(RetrieveAPIView):
    queryset = BookInfo.objects.all()
    serializer_class = BookInfoSerializer
    pagination_class = LargeResultsSetPagination

注意：如果在視圖內關閉分頁功能，只需在視圖內設置

pagination_class = None

4、可選分頁器

1） PageNumberPagination

前端訪問網址形式：

GET  http://api.example.org/books/?page=4

可以在子類中定義的屬性：

• page_size 每頁數目
• page_query_param 前端發送的頁數關鍵字名，默認為"page"
• page_size_query_param 前端發送的每頁數目關鍵字名，默認為None
• max_page_size 前端最多能設置的每頁數量

from rest_framework.pagination import PageNumberPagination

class StandardPageNumberPagination(PageNumberPagination):
    page_size_query_param = 'page_size'
    max_page_size = 10

class BookListView(ListAPIView):
    queryset = BookInfo.objects.all().order_by('id')
    serializer_class = BookInfoSerializer
    pagination_class = StandardPageNumberPagination

# 127.0.0.1/books/?page=1&page_size=2

2）LimitOffsetPagination

前端訪問網址形式：

GET http://api.example.org/books/?limit=100&offset=400

可以在子類中定義的屬性：

• default_limit 默認限制，默認值與PAGE_SIZE設置一直
• limit_query_param limit參數名，默認'limit'
• offset_query_param offset參數名，默認'offset'
• max_limit 最大limit限制，默認None

from rest_framework.pagination import LimitOffsetPagination

class BookListView(ListAPIView):
    queryset = BookInfo.objects.all().order_by('id')
    serializer_class = BookInfoSerializer
    pagination_class = LimitOffsetPagination

# 127.0.0.1:8000/books/?offset=3&limit=2

5、異常處理 Exceptions

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

REST framework定義的異常

• APIException 所有異常的父類
• ParseError 解析錯誤
• AuthenticationFailed 認證失敗
• NotAuthenticated 尚未認證
• PermissionDenied 權限決絕
• NotFound 未找到
• MethodNotAllowed 請求方式不支持
• NotAcceptable 要獲取的數據格式不支持
• Throttled 超過限流次數
• ValidationError 校驗失敗

6、自動生成接口文檔

REST framework可以自動幫助我們生成接口文檔。

接口文檔以網頁的方式呈現。

自動接口文檔能生成的是繼承自APIView及其子類的視圖。

安裝依賴

REST framewrok生成接口文檔需要coreapi庫的支持。

pip install coreapi

設置接口文檔訪問路徑

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

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

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

from rest_framework.documentation import include_docs_urls

urlpatterns = [
    ...
    path('docs/', include_docs_urls(title='站點頁面標題'))
]

文檔描述說明的定義位置

1） 單一方法的視圖，可直接使用類視圖的文檔字符串，如

class BookListView(generics.ListAPIView):
    """
    返回所有圖書信息.
    """

2）包含多個方法的視圖，在類視圖的文檔字符串中，分開方法定義，如

class BookListCreateView(generics.ListCreateAPIView):
    """
    get:
    返回所有圖書信息.

    post:
    新建圖書.
    """

3）對於視圖集ViewSet，仍在類視圖的文檔字符串中封開定義，但是應使用action名稱區分，如

class BookInfoViewSet(mixins.ListModelMixin, mixins.RetrieveModelMixin, GenericViewSet):
    """
    list:
    返回圖書列表數據

    retrieve:
    返回圖書詳情數據

    latest:
    返回最新的圖書數據

    read:
    修改圖書的閱讀量
    """

訪問接口文檔網頁

兩點說明：

1） 視圖集ViewSet中的retrieve名稱，在接口文檔網站中叫做read

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

class BookInfo(models.Model):
    ...
    bread = models.IntegerField(default=0, verbose_name='閱讀量', help_text='閱讀量')
    ...

或

class BookReadSerializer(serializers.ModelSerializer):
    class Meta:
        model = BookInfo
        fields = ('bread', )
        extra_kwargs = {
            'bread': {
                'required': True,
                'help_text': '閱讀量'
            }
        }

7、Xadmin

xadmin是Django的第三方擴展，可是使Django的admin站點使用更方便。

文檔：https://xadmin.readthedocs.io/en/latest/index.html

安裝

通過如下命令安裝xadmin的最新版

pip install https://codeload.github.com/sshwsfc/xadmin/zip/django2

在配置文件中注冊如下應用

BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
# 把apps目錄設置環境變量中的導包路徑
sys.path.append( os.path.join(BASE_DIR,"luffy/apps") )


INSTALLED_APPS = [
    ...
    'xadmin',
    'crispy_forms',
    'reversion',
    ...
]

# 修改使用中文界面
LANGUAGE_CODE = 'zh-Hans'

# 修改時區
TIME_ZONE = 'Asia/Shanghai'

xadmin有建立自己的數據庫模型類，需要進行數據庫遷移

python manage.py makemigrations
python manage.py migrate

在總路由中添加xadmin的路由信息

import xadmin
xadmin.autodiscover()

# version模塊自動注冊需要版本控制的 Model
from xadmin.plugins import xversion
xversion.register_models()

urlpatterns = [
    path(r'xadmin/', xadmin.site.urls)
]

創建超級用戶

python manage.py createsuperuser

使用

• xadmin不再使用Django的admin.py，而是需要編寫代碼在adminx.py文件中。
• xadmin的站點管理類不用繼承admin.ModelAdmin，而是直接繼承object即可。

例如：在子應用中創建adminx.py文件。

站點的全局配置

import xadmin
from xadmin import views

class BaseSetting(object):
    """xadmin的基本配置"""
    enable_themes = True  # 開啟主題切換功能
    use_bootswatch = True

xadmin.site.register(views.BaseAdminView, BaseSetting)

class GlobalSettings(object):
    """xadmin的全局配置"""
    site_title = "路飛學城"  # 設置站點標題
    site_footer = "路飛學城有限公司"  # 設置站點的頁腳
    menu_style = "accordion"  # 設置菜單折疊

xadmin.site.register(views.CommAdminView, GlobalSettings)

站點Model管理

xadmin可以使用的頁面樣式控制基本與Django原生的admin一直。

• list_display 控制列表展示的字段

  list_display = ['id', 'btitle', 'bread', 'bcomment']
  

• search_fields 控制可以通過搜索框搜索的字段名稱，xadmin使用的是模糊查詢

  search_fields = ['id','btitle']
  

• list_filter 可以進行過濾操作的列，對於分類、性別、狀態

  list_filter = ['is_delete']
  

• ordering 默認排序的字段

• readonly_fields 在編輯頁面的只讀字段

• exclude 在編輯頁面隱藏的字段

• list_editable 在列表頁可以快速直接編輯的字段

• show_detail_fields 在列表頁提供快速顯示詳情信息

• refresh_times 指定列表頁的定時刷新

  refresh_times = [5, 10,30,60]  # 設置允許后端管理人員按多長時間(秒)刷新頁面
  

• list_export 控制列表頁導出數據的可選格式

  list_export = ('xls', 'xml', 'json')   list_export設置為None來禁用數據導出功能
  list_export_fields = ('id', 'btitle', 'bpub_date')
  

• show_bookmarks 控制是否顯示書簽功能

  show_bookmarks = True
  

• data_charts 控制顯示圖表的樣式

  data_charts = {
          "order_amount": {
            'title': '圖書發布日期表', 
            "x-field": "bpub_date", 
            "y-field": ('btitle',),
            "order": ('id',)
          },
      #    支持生成多個不同的圖表
      #    "order_amount": {
      #      'title': '圖書發布日期表', 
      #      "x-field": "bpub_date", 
      #      "y-field": ('btitle',),
      #      "order": ('id',)
      #    },
      }
  

  • title 控制圖標名稱
  • x-field 控制x軸字段
  • y-field 控制y軸字段，可以是多個值
  • order 控制默認排序

• model_icon 控制菜單的圖標

  class BookInfoAdmin(object):
      model_icon = 'fa fa-gift'
  
  xadmin.site.register(models.BookInfo, BookInfodmin)