Django REST framework 的功能

1. 認證Authentication

　　　　方法一：在配置文件中配置全局默認的認證方案

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': ( 'rest_framework.authentication.BasicAuthentication', # 基本認證 'rest_framework.authentication.SessionAuthentication', # session認證  ) }

　　　 方法二：在每一個視圖中經過authentication_classess屬性來設置

from rest_framework.authentication import SessionAuthentication, BasicAuthentication
from rest_framework.views import APIView class ExampleView(APIView): authentication_classes = (SessionAuthentication, BasicAuthentication) ...

認證失敗會有兩種可能的返回值：

• 401 Unauthorized 未認證
• 403 Permission Denied 權限被禁止

2. 權限Permissions　

　　　　權限控制能夠限制用戶對於視圖的訪問和對於具體數據對象的訪問。

　　　　　　（1）在執行視圖的dispatch()方法前，會先進行視圖訪問權限的判斷

　　　　　　（2）在經過get_object()獲取具體對象時，會進行對象訪問權限的判斷

　　　　使用：

　　　　方法一：在配置文件中設置默認的權限管理類

REST_FRAMEWORK = {
    'DEFAULT_PERMISSION_CLASSES': ( 'rest_framework.permissions.IsAuthenticated', ) }

　　　　方法二：在視圖中經過permission_classes屬性來設置，

from rest_framework.permissions import IsAuthenticated
from rest_framework.views import APIView class ExampleView(APIView): permission_classes = (IsAuthenticated,) ...

提供的權限

• AllowAny 容許全部用戶
• IsAuthenticated 僅經過認證的用戶
• IsAdminUser 僅管理員用戶
• IsAuthenticatedOrReadOnly 認證的用戶能夠徹底操做，不然只能get讀取

自定義權限

自定義權限，需繼承rest_framework.permissions.BasePermission父類，並實現如下兩個任何一個方法或所有

• .has_permission(self, request, view)

  是否能夠訪問視圖， view表示當前視圖對象

• .has_object_permission(self, request, view, obj)

  是否能夠訪問數據對象， view表示當前視圖， obj爲數據對象

class MyPermission(BasePermission):
    def has_object_permission(self, request, view, obj): """控制對obj對象的訪問權限，此案例決絕全部對對象的訪問""" return False

3. 限流Throttling

　　能夠對接口訪問的頻次進行限制，以減輕服務器壓力。

　　使用

　　在配置文件中，使用DEFAULT_THROTTLE_CLASSES和DEFAULT_THROTTLE_RATES進行全局配置

　　DEFAULT_THROTTLE_RATES可使用second,minute,hour或者day來指明週期

REST_FRAMEWORK = {
    'DEFAULT_THROTTLE_CLASSES': ( 'rest_framework.throttling.AnonRateThrottle', 'rest_framework.throttling.UserRateThrottle' ), 'DEFAULT_THROTTLE_RATES': { 'anon': '100/day', 'user': '1000/day' } }

在視圖中經過throttle_classess屬性來配置，如

from rest_framework.throttling import UserRateThrottle
from rest_framework.views import APIView class ExampleView(APIView): throttle_classes = (UserRateThrottle,) ...

可選限流類

1） AnonRateThrottle

限制全部匿名未認證用戶，使用IP區分用戶。

使用DEFAULT_THROTTLE_RATES['anon'] 來設置頻次

2）UserRateThrottle

限制認證用戶，使用User id 來區分。

使用DEFAULT_THROTTLE_RATES['user'] 來設置頻次

3）ScopedRateThrottle

限制用戶對於每一個視圖的訪問頻次，使用ip或user id。

4. 過濾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 = BookSerializer
    filter_fields = ('btitle', 'bread')

5. 排序

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

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

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

6. 分頁Pagination

　　在配置文件設置全局的分頁方式

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

 

　　可使用Pagination類爲視圖添加不一樣分頁　

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   # 若等於None，能夠在視圖內關閉分頁功能

　6.1可選分頁器

 

（1）PageNumberPagination

from rest_framework.pagination import PageNumberPagination

在子類中定義的屬性：

　　page_size 每頁數目

　　page_query_param 前端發送的頁數關鍵字名，默認爲"page"

　　page_size_query_param 前端發送的每頁數目關鍵字名，默認爲None

　　max_page_size 前端最多能設置的每頁數量

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 = BookSerializer
    pagination_class = StandardPageNumberPagination

前端訪問網址形式：

GET  http://api.xxxx.com/xxx/?page=4

（2）LimitOffsetPagination

from rest_framework.pagination import LimitOffsetPagination

能夠在子類中定義的屬性：

　　　　　　default_limit 默認限制，默認值與PAGE_SIZE設置一致

　　　　　　limit_query_param limit參數名，默認'limit'

　　　　　　offset_query_param offset參數名，默認'offset'

　　　　　　max_limit 最大limit限制，默認None

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

前端訪問網址形式：

GET http://api.xxxx.com/xxx/?limit=100&offset=400

7. 版本Versioning

REST framework提供了版本號的支持。

在須要獲取請求的版本號時，能夠經過request.version來獲取。

默認版本功能未開啓，request.version返回None。

class BookDetailView(RetrieveAPIView):
    queryset = BookInfo.objects.all()

    def get_serializer_class(self):
        if self.request.version == '1.0':
            return BookInfoSerializer
        else:
            return BookInfoSerializer2

開啓版本支持功能，須要在配置文件中設置DEFAULT_VERSIONING_CLASS

REST_FRAMEWORK = {
    'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.NamespaceVersioning'
}

其餘可選配置：

• DEFAULT_VERSION 默認版本號，默認值爲None
• ALLOWED_VERSIONS 容許請求的版本號，默認值爲None
• VERSION_PARAM 識別版本號參數的名稱，默認值爲'version'

支持的版本處理方式

1） AcceptHeaderVersioning

請求頭中傳遞的Accept攜帶version

GET /bookings/ HTTP/1.1
Host: example.com
Accept: application/json; version=1.0

2）URLPathVersioning

URL路徑中攜帶

urlpatterns = [
    url(
        r'^(?P<version>(v1|v2))/bookings/$',
        bookings_list,
        name='bookings-list'
    ),
    url(
        r'^(?P<version>(v1|v2))/bookings/(?P<pk>[0-9]+)/$',
        bookings_detail,
        name='bookings-detail'
    )
]

3）NamespaceVersioning

命名空間中定義

# bookings/urls.py
urlpatterns = [
    url(r'^$', bookings_list, name='bookings-list'),
    url(r'^(?P<pk>[0-9]+)/$', bookings_detail, name='bookings-detail')
]

# urls.py
urlpatterns = [
    url(r'^v1/bookings/', include('bookings.urls', namespace='v1')),
    url(r'^v2/bookings/', include('bookings.urls', namespace='v2'))
]

4）HostNameVersioning

主機域名攜帶

GET /bookings/ HTTP/1.1
Host: v1.example.com
Accept: application/json

5）QueryParameterVersioning

查詢字符串攜帶

GET /something/?version=0.1 HTTP/1.1
Host: example.com
Accept: application/json

8. 異常處理Exceptions

　　自定義異常處理函數

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': 'project.app.utils.custom_exception_handler'
}

若未聲明，採用默認的方式

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

REST framework定義的異常

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

9.自動生成接口文檔　　

REST framework能夠自動幫助咱們生成接口文檔，接口文檔以網頁的方式呈現。

　　9.1 安裝依賴

pip install coreapi

　　9.2 設置接口文檔訪問路徑

from rest_framework.documentation import include_docs_urls

urlpatterns = [
    ...
　　# 參數爲title爲接口文檔網站的標題
    url(r'^docs/', include_docs_urls(title='My API title'))
]