drf——认证，权限，限流，过滤，排序，分页，异常处理，接口文档生成

一认证Authentication

认证失败会有两种可能的返回值：

401 Unauthorized 未认证
403 Permission Denied 权限被禁止

全局配置：配置文件

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

局部配置

from rest_framework.authentication import SessionAuthentication, BasicAuthentication
from rest_framework.views import APIView

class ExampleView(APIView):
    authentication_classes = [SessionAuthentication, BasicAuthentication]

自定义认证

1 类 继承 BaseAuthentication

  方法 authenticate方法 认证逻辑
    
  认证通过，返回两个值 : user , token 
  认证失败，抛异常：APIException或者AuthenticationFailed
  from rest_framework.exceptions import AuthenticationFailed
  raise AuthenticationFailed('认证失败')

2 全局使用，局部使用

3 其实不继承 BaseAuthentication , 写认证类也可以，鸭子类型，这个类只是强制要写
  需要注意，如果配置多个认证类，要把返回两个值的放到最后

源码分析
self.perform_authentication(request)
就一句话：request.user，需要去drf的Request对象中找user属性（方法） 

Request类中的user方法，刚开始来，没有_user,走 self._authenticate()

dispatch定制Request时：authenticators=self.get_authenticators()  # 得到的是列表，元素是认证类对象
    def get_authenticators(self):
        return [auth() for auth in self.authentication_classes]
    
    authentication_classes可以在类视图中自定义，或者配置文件默认：
    authentication_classes = api_settings.DEFAULT_AUTHENTICATION_CLASSES
	DEFAULTS = {
    	'DEFAULT_AUTHENTICATION_CLASSES': [
        	'rest_framework.authentication.SessionAuthentication',
        	'rest_framework.authentication.BasicAuthentication'
    	],}

	request.user : Request类的 执行_authenticate(self):

    self.authenticators = authenticators or ()
    def _authenticate(self):
 # 遍历拿到一个个认证器，进行认证
# self.authenticators配置的一堆认证类产生的认证类对象组成的 list
# self.authenticators 你在视图类中配置的一个个的认证类：
# authentication_classes=[认证类1，认证类2]，对象的列表
        for authenticator in self.authenticators:
            try:
                # 认证器(对象)调用认证方法authenticate(认证类对象self, request请求对象)
                # 返回值：登陆的用户 与 认证的信息 组成的 tuple
                # 该方法被try包裹，代表该方法会抛异常，抛异常就代表认证失败
                user_auth_tuple = authenticator.authenticate(self) #注意这self是request对象
            except exceptions.APIException:
                self._not_authenticated()
                raise

            # 返回值的处理
            if user_auth_tuple is not None:
                self._authenticator = authenticator
                # 如何有返回值，就将 登陆用户 与 登陆认证 分别保存到 request.user、request.auth
                self.user, self.auth = user_auth_tuple
                return
        # 如果返回值user_auth_tuple为空，代表认证通过，但是没有 登陆用户 与 登陆认证信息，代表游客
        self._not_authenticated()

from rest_framework.authentication import BaseAuthentication
from rest_framework.exceptions import AuthenticationFailed
from app01.models import UserToken

class MyAuthentication(BaseAuthentication):
    def authenticate(self, request):
        token=request.GET.get('token')
        if  token:
            user_token=UserToken.objects.filter(token=token).first()
            if user_token:
                return user_token.user,token
            else:
                raise AuthenticationFailed('认证失败')
        else:
            raise AuthenticationFailed('请求地址中需要携带token')

使用

全局使用，在setting.py中配置
REST_FRAMEWORK={
    "DEFAULT_AUTHENTICATION_CLASSES":["app01.app_auth.MyAuthentication",]
}

局部使用
authentication_classes=[MyAuthentication]
局部禁用
authentication_classes=[]

二权限Permissions

全局设置配置文件

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

如果未指明，则采用如下默认配置

'DEFAULT_PERMISSION_CLASSES': (
   'rest_framework.permissions.AllowAny',
)

局部使用

from rest_framework.permissions import IsAuthenticated
from rest_framework.views import APIView

class ExampleView(APIView):
    permission_classes = (IsAuthenticated,)

提供的权限

AllowAny 允许所有用户
IsAuthenticated 仅通过认证的用户
IsAdminUser 仅管理员用户
IsAuthenticatedOrReadOnly 已经登陆认证的用户可以对数据进行增删改操作，没有登陆认证的只能查看数据。

from rest_framework.authentication import SessionAuthentication
from rest_framework.permissions import IsAuthenticated
from rest_framework.generics import RetrieveAPIView

class StudentAPIView(RetrieveAPIView):
    queryset = Student.objects.all()
    serializer_class = StudentSerializer
    
    authentication_classes = [SessionAuthentication]  # 认证
    permission_classes = [IsAuthenticated]            # 权限

自定义权限

继承rest_framework.permissions.BasePermission父类，并实现以下两个方法的一个或全部

.has_permission(self, request, view)

是否可以访问视图， view表示当前视图对象
.has_object_permission(self, request, view, obj)

是否可以访问数据对象， view表示当前视图， obj为数据对象

在当前子应用下，创建一个权限文件permissions.py中声明自定义权限类:

from rest_framework.permissions import BasePermission

class IsXiaoMingPermission(BasePermission):
    def has_permission(self, request, view):
        if( request.user.username == "xiaoming" ):
            return True
        #  有权限 True 无权限 False

全局使用

REST_FRAMEWORK={
    "DEFAULT_AUTHENTICATION_CLASSES":["app01.app_auth.MyAuthentication",],
    'DEFAULT_PERMISSION_CLASSES': [
        'app01.app_auth.UserPermission',
    ],
}

局部使用

from .permissions import IsXiaoMingPermission
class StudentViewSet(ModelViewSet):
    queryset = Student.objects.all()
    serializer_class = StudentSerializer
    
    permission_classes = [IsXiaoMingPermission]

局部禁用

class TestView(APIView):
    permission_classes = []

三限流Throttling

可以对接口访问的频次进行限制，以减轻服务器压力。

一般用于付费购买次数,投票等场景使用.

使用

全局使用

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

DEFAULT_THROTTLE_RATES 可以使用 second, minute, hour 或day来指明周期。

局部使用

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。

不同的视图，设置 throttle_scope：

class ContactListView(APIView):
    throttle_scope = 'contacts'


class ContactDetailView(APIView):
    throttle_scope = 'contacts'


class UploadView(APIView):
    throttle_scope = 'uploads'


REST_FRAMEWORK = {
    'DEFAULT_THROTTLE_CLASSES': (
        'rest_framework.throttling.ScopedRateThrottle',
    ),
    'DEFAULT_THROTTLE_RATES': {
        'contacts': '1000/day',
        'uploads': '20/day'
    }
}

实例

全局配置

    'DEFAULT_THROTTLE_RATES': {
        'anon': '3/minute',
        'user': '10/minute'
    }

from rest_framework.authentication import SessionAuthentication
from rest_framework.permissions import IsAuthenticated
from rest_framework.generics import RetrieveAPIView
from rest_framework.throttling import UserRateThrottle

class StudentAPIView(RetrieveAPIView):
    queryset = Student.objects.all()
    serializer_class = StudentSerializer
    
    authentication_classes = [SessionAuthentication]
    permission_classes = [IsAuthenticated]
    
    throttle_classes = (UserRateThrottle,)

根据ip进行频率限制：

# 类，继承SimpleRateThrottle，重写get_cache_key 

from rest_framework.throttling import ScopedRateThrottle,SimpleRateThrottle

class MyThrottle(SimpleRateThrottle):
    scope='luffy'
    def get_cache_key(self, request, view):
        return request.META.get('REMOTE_ADDR')
    
# 局部使用，全局使用

REST_FRAMEWORK={
    'DEFAULT_THROTTLE_CLASSES': (
        'utils.throttling.MyThrottle',
    ),
    'DEFAULT_THROTTLE_RATES': {
        'luffy': '3/m'  # key要跟类中的scop对应
    },
}

# python3 manage.py runserver 0.0.0.0:8000   局域网相互访问

自定义频率

# 自定制频率类，需要写两个方法
	# 判断是否限次：没有限次True，限次False
    	def allow_request(self, request, view):
            
    # 限次后调用，显示还需等待多长时间才能再访问，返回等待的时间seconds
    	def wait(self):

import time

class IPThrottle():
    
    VISIT_DIC = {}
    def __init__(self):
        self.history_list=[]
    def allow_request(self, request, view):
        ip=request.META.get('REMOTE_ADDR')
        ctime=time.time()
        if ip not in self.VISIT_DIC:
            self.VISIT_DIC[ip]=[ctime,]
            return True
        self.history_list=self.VISIT_DIC[ip]   #当前访问者时间列表拿出来
        while True:
            if ctime-self.history_list[-1]>60:
                self.history_list.pop() # 把最后一个移除
            else:
                break
        if len(self.history_list)<3:
            self.history_list.insert(0,ctime)
            return True
        else:
            return False

    def wait(self):
        ctime=time.time()
        return 60-(ctime-self.history_list[-1])

#全局使用，局部使用

# SimpleRateThrottle源码分析
    def get_rate(self):
        if not getattr(self, 'scope', None):
            msg = ("You must set either `.scope` or `.rate` for '%s' throttle" %
                   self.__class__.__name__)
            raise ImproperlyConfigured(msg)

        try:
            return self.THROTTLE_RATES[self.scope]  # scope：'user' => '3/min'
        except KeyError:
            msg = "No default throttle rate set for '%s' scope" % self.scope
            raise ImproperlyConfigured(msg)
    def parse_rate(self, rate):
        if rate is None:
            return (None, None)
        #3  mmmmm
        num, period = rate.split('/')  # rate：'3/min'
        num_requests = int(num)
        duration = {'s': 1, 'm': 60, 'h': 3600, 'd': 86400}[period[0]]
        return (num_requests, duration)
    def allow_request(self, request, view):
        if self.rate is None:
            return True
        #当前登录用户的ip地址
        self.key = self.get_cache_key(request, view)  # key：'throttle_user_1'
        if self.key is None:
            return True

        # 初次访问缓存为空，self.history为[]，是存放时间的列表
        self.history = self.cache.get(self.key, [])
        # 获取一下当前时间，存放到 self.now
        self.now = self.timer()

        # Drop any requests from the history which have now passed the
        # throttle duration

        # 当前访问与第一次访问时间间隔如果大于60s，第一次记录清除，不再算作一次计数
        # 10 20 30 40
        # self.history:[10:23,10:55]
        # now:10:56
        while self.history and  self.now - self.history[-1] >= self.duration:
            self.history.pop()

        # history的长度与限制次数3进行比较
        # history 长度第一次访问0，第二次访问1，第三次访问2，第四次访问3失败
        if len(self.history) >= self.num_requests:
            # 直接返回False，代表频率限制了
            return self.throttle_failure()

        # history的长度未达到限制次数3，代表可以访问
        # 将当前时间插入到history列表的开头，将history列表作为数据存到缓存中，key是throttle_user_1，过期时间60s
        return self.throttle_success()

四过滤Filtering

pip install django-filter

配置文件中增加过滤后端的设置：

INSTALLED_APPS = [
    'django_filters',  # 需要注册应用，
]

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

在视图中添加filter_fields属性

class StudentListView(ListAPIView):
    queryset = Student.objects.all()
    serializer_class = StudentSerializer
    filter_fields = ('age', 'sex')

# 127.0.0.1:8000/four/students/?sex=1

五排序

对于列表数据，REST framework提供了OrderingFilter过滤器来帮助我们快速指明数据按照指定字段进行排序。

使用方法：

在类视图中设置filter_backends，使用rest_framework.filters.OrderingFilter过滤器

class StudentListView(ListAPIView):
    queryset = Student.objects.all()
    serializer_class = StudentModelSerializer
    
    filter_backends = [OrderingFilter]
    ordering_fields = ('id', 'age')

# 127.0.0.1:8000/books/?ordering=-age
# -id 表示针对id字段进行倒序排序
# id  表示针对id字段进行升序排序

如果需要在过滤以后再次进行排序，则需要两者结合!

from rest_framework.generics import ListAPIView
from students.models import Student
from .serializers import StudentModelSerializer
from django_filters.rest_framework import DjangoFilterBackend

class Student3ListView(ListAPIView):
    queryset = Student.objects.all()
    serializer_class = StudentModelSerializer
    
    filter_fields = ('age', 'sex')
    # 因为局部配置会覆盖全局配置,所以需要重新把过滤组件核心类再次声明,
    # 否则过滤功能会失效
    filter_backends = [OrderingFilter,DjangoFilterBackend]
    ordering_fields = ('id', 'age')

六分页Pagination

REST framework提供了分页的支持。

全局使用

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

局部使用

from  rest_framework.pagination import PageNumberPagination,LimitOffsetPagination,CursorPagination

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

可选分页器

1） PageNumberPagination

前端访问网址形式：

GET  http://127.0.0.1:8000/students/?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 = 2
    page_size_query_param = "size"
    max_page_size = 10
    page_query_param = "p"

class StudentAPIView(ListAPIView):
    queryset = Student.objects.all()
    serializer_class = StudentModelSerializer
    
    pagination_class = StandardPageNumberPagination

# 127.0.0.1/four/students/?p=1&size=5

2）LimitOffsetPagination

前端访问网址形式：

GET http://127.0.0.1/four/students/?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 StandardLimitOffsetPagination(LimitOffsetPagination):
    default_limit = 2
    limit_query_param = "size"
    offset_query_param = "start"

class StudentAPIView(ListAPIView):
    queryset = Student.objects.all()
    serializer_class = StudentModelSerializer
    pagination_class = StandardLimitOffsetPagination

3）CursorPagination

cursor_query_param = 'cursor' 每一页查询的key
page_size = 2 每页显示的条数
ordering = '-id' 排序字段

class MyCursorPagination(CursorPagination):
    cursor_query_param = 'cursor'
    page_size = 2
    ordering = '-id'
    
class BookView(ListAPIView):
    # queryset = models.Book.objects.all().filter(is_delete=False)
    queryset = models.Book.objects.all()
    serializer_class = BookModelSerializer
    
    pagination_class = MyCursorPagination

APIView 分页

class BookView(APIView):
    
    def get(self,request,*args,**kwargs):
        book_list=models.Book.objects.all()
        # 实例化得到一个分页器对象
        page_cursor=MyPageNumberPagination()

        book_list=page_cursor.paginate_queryset(book_list,request,view=self)
        next_url =page_cursor.get_next_link()
        pr_url=page_cursor.get_previous_link()
        book_ser=BookModelSerializer(book_list,many=True)
        
        return Response(data=book_ser.data)

#settings.py
REST_FRAMEWORK={
    'PAGE_SIZE': 2,
}

七异常处理 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 None:
        response.data['status_code'] = response.status_code

    return response

配置文件中声明自定义异常处理

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

如果未声明，会采用默认的方式，如下

rest_frame/settings.py

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):
            response = Response({'detail': '服务器内部错误'}, status=status.HTTP_507_INSUFFICIENT_STORAGE)
    return response

REST framework定义的异常

APIException 所有异常的父类
ParseError 解析错误
AuthenticationFailed 认证失败
NotAuthenticated 尚未认证
PermissionDenied 权限决绝
NotFound 未找到
MethodNotAllowed 请求方式不支持
NotAcceptable 要获取的数据格式不支持
Throttled 超过限流次数
ValidationError 校验失败

也就是说，很多的没有在上面列出来的异常，就需要我们在自定义异常中自己处理了。

八自动生成接口文档

REST framework可以自动帮助我们生成接口文档。

接口文档以网页的方式呈现。

自动接口文档能生成的是继承自APIView及其子类的视图。

8.1. 安装依赖

pip install coreapi

8.2. 设置接口文档访问路径

路由配置

rest_framework.documentation.include_docs_urls

参数title为接口文档网站的标题。

from rest_framework.documentation import include_docs_urls

urlpatterns = [
    path('docs/', include_docs_urls(title='站点页面标题'))
]

8.3. 文档描述说明的定义位置

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:
    修改图书的阅读量
    """

8.4. 访问接口文档网页

浏览器访问 127.0.0.1:8000/docs/，即可看到自动生成的接口文档。

æ¥å£ææ¡£ç½é¡µ

两点说明：

1）视图集ViewSet中的retrieve名称，在接口文档网站中叫做read

2）参数的Description需要在模型类或序列化器类的字段中以help_text选项定义，如：

class Student(models.Model):
    ...
    age = models.IntegerField(default=0, verbose_name='年龄', help_text='年龄')
    ...

或

class StudentSerializer(serializers.ModelSerializer):
    class Meta:
        model = Student
        fields = "__all__"
        extra_kwargs = {
            'age': {
                'required': True,
                'help_text': '年龄'
            }
        }

drf——认证，权限，限流，过滤，排序，分页，异常处理，接口文档生成

一认证Authentication

全局配置 ：配置文件

局部配置

自定义认证

使用

二 权限Permissions

全局设置 配置文件

如果未指明，则采用如下默认配置

局部使用

提供的权限

自定义权限

全局使用

局部使用

局部禁用

三 限流Throttling

使用

全局使用

局部使用

可选限流类

实例

全局配置

自定义频率

四 过滤Filtering

五 排序

六 分页Pagination

全局使用

局部使用

局部禁用

可选分页器

1） PageNumberPagination

2）LimitOffsetPagination

3）CursorPagination

APIView 分页

七 异常处理 Exceptions

REST framework定义的异常

八 自动生成接口文档

8.1. 安装依赖

8.2. 设置接口文档访问路径

8.3. 文档描述说明的定义位置

8.4. 访问接口文档网页

两点说明：

全局配置：配置文件

二权限Permissions

全局设置配置文件

三限流Throttling

四过滤Filtering

五排序

六分页Pagination

七异常处理 Exceptions

八自动生成接口文档