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'))

]

巴特西

Django REST framework 的功能

提供的权限

可选限流类

支持的版本处理方式

REST framework定义的异常

最新文章

热门文章