DRF框架中常用的组件

目录

• 1. 认证
  • 1.1全局认证
  • 1.2部分认证
• 2.权限
  • 2.1提供的权限
  • 2.2全局配置
  • 2.3局部权限
  • 2.4自定义权限
• 3. 限流
  • 3.1定义
  • 3.2全局限流
  • 3.3局部限流
• 4. 过滤
  • 4.1定义
  • 4.2全局配置
  • 4.3局部配置
• 5. 排序
  • 5.1基本排序
  • 2.过滤排序
• 6. 分页
  • 6.1.全局分页
  • 2.自定义分页
    • 1.页码分页类
    • 2.偏移分页类
• 7. 异常处理 Exceptions
  • 1.DRF的异常
  • 2.自定义异常
• 8. 自动生成接口文档
  • 8.1. 安装依赖
  • 8.2. 设置接口文档访问路径
    • 8.3. 文档描述说明的定义位置
  • 8.4. 访问接口文档网页
    • 两点说明：

https://blog.csdn.net/weixin_44689630/article/details/118079118

为了方便接下来的学习，我们创建一个新的子应用 opt

python manage.py startapp opt

提前在总路由和配置文件中注册子应用和配置总路由。

# settings.py中注册子应用：
INSTALLED_APPS = [
  # ....
  'opt',
]


# 总路由中加上：
path("opt/",include("opt.urls")),

因为接下来的功能中需要使用到登陆功能，所以我们使用django内置admin站点并创建一个管理员.

python manage.py createsuperuser

创建管理员以后，访问admin站点，先修改站点的语言配置:

# settings.py
LANGUAGE_CODE = 'zh-hans'
TIME_ZONE = 'Asia/Shanghai'

访问admin 站点效果：

1. 认证

1.1全局认证

可以在/rest_framework/settings.py配置文件中查询全局默认的认证方案

可以在项目的主应用的settings.py配置文件中加入以下配置覆盖全局默认的配置方案

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

1.2部分认证

可以在每个视图中通过设置authentication_classess类属性来设置

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

class ExampleView(APIView):
    # 类属性
    authentication_classes = [SessionAuthentication, BasicAuthentication]
    def get(self,request):
        pass

认证失败会有两种可能的返回值,这个需要我们配合权限组件来使用：

编码	含义
401	Unauthorized 未认证
403	Permission Denied 权限被禁止

2.权限

权限控制可以限制用户对于视图的访问和对于具体数据模型对象的访问。

• 在执行视图的as_view()方法的dispatch()方法前,会先进行视图访问权限的判断
• 在通过get_object()获取具体模型对象时,会进行模型对象访问权限的判断

2.1提供的权限

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

2.2全局配置

在配置文件settings.py中全局设置默认的权限管理类，如：

REST_FRAMEWORK = {
    ....
    #  权限[全局配置，所有的视图都会被影响到]
    'DEFAULT_PERMISSION_CLASSES': (
        'rest_framework.permissions.IsAuthenticated', # 已经登录认证的用户才能访问
    )
}

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

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

注意

drf的配置信息,需要卸载django的配置文件,而且必须写在REST_FRAMEWORK的字典中,才能被drf识别

chorme浏览器进入无痕模式的快捷键，Ctrl+Shift+N

2.3局部权限

可以在具体的视图中通过permission_classes属性来设置，如:

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]

2.4自定义权限

自定义权限,需继承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 and request.user.username == "xiaoming":
            return True

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

3. 限流

3.1定义

目地:

可以对接口访问的频次进行限制,以减轻服务器压力,或者实现特定的业务

场景:

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

Throttling限流类

可选类
AnonRateThrottle	限制所有匿名未认证用户,使用IP区分用户,使用DEFAULT_THROTTLE_RATES['anon'] 来设置频次
UserRateThrottle	限制认证用户,使用User id 来区分,使用DEFAULT_THROTTLE_RATES['user'] 来设置频次
ScopedRateThrottle	限制用户对于每个视图的访问频次,使用ip或user id

APIView的流量控制属性

属性名
throttle_scope	节流范围
throttle_classes	节流类

3.2全局限流

可以在配置文件中

使用DEFAULT_THROTTLE_CLASSES(启用的限制类)

DEFAULT_THROTTLE_RATES(限制频率)进行全局配置

REST_FRAMEWORK = {
    'DEFAULT_THROTTLE_CLASSES': ( # 全局启用的限制类
        'rest_framework.throttling.AnonRateThrottle',# 匿名用户
        'rest_framework.throttling.UserRateThrottle'# 登录用户
        'rest_framework.throttling.ScopedRateThrottle',#指定用户
    ),
    'DEFAULT_THROTTLE_RATES': {   # 限制频率
        'anon': '3/minute',
        'user': '10/minute',
        'access': '5/minute', # 这个是自定义限流的频率配置
        'contacts': '1000/day',
        'uploads': '20/day'
    }
}

3.3局部限流

DEFAULT_THROTTLE_RATES 可以使用 second, minute, hour 或day来指明周期.也可以在具体视图中通过throttle_classess属性来配置

如setting.py

REST_FRAMEWORK = {
    'DEFAULT_THROTTLE_RATES':{
        'anon':'2/minute',
        'user':'4/minute',
        'jason':'3/minute'
    }
}

views.py

from rest_framework.throttling import UserRateThrottle,AnonRateThrottle,ScopedRateThrottle
from rest_framework.viewsets import ModelViewSet
from .models import Student

class Student13APIViewSet(ReadOnlyModelViewSet):
    #匿名用户
    throttle_classes = (AnonRateThrottle,)
    serializer_class = StudentModelSerializer
    queryset = Student.objects.all()


class Student14APIViewSet(ModelViewSet):
    #认证用户
    throttle_classes = (UserRateThrottle,)
    serializer_class = StudentModelSerializer
    queryset = Student.objects.all()
    
class Student15APIViewSet(ModelViewSet):
    #自定义用户
    throttle_classes = [ScopedRateThrottle]
    throttle_scope="jason"
    serializer_class = StudentModelSerializer
    queryset = Student.objects.all()

4. 过滤

4.1定义

对于列表数据可能需要根据字段进行过滤，我们可以通过添加django-fitlter扩展来增强支持。

pip install django-filter

在配置文件settings.py中增加过滤组件的设置：

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

4.2全局配置

REST_FRAMEWORK = {
    ...
    # 全局配置，也可以使用局部配置
    'DEFAULT_FILTER_BACKENDS': ('django_filters.rest_framework.DjangoFilterBackend',)
}

4.3局部配置

注意:

局部配置的前提是进行全局配置,然后再在视图类中添加类属性filter_fields,指定可以过滤的字段

5. 排序

对于列表数据,按照指定字段进行排序,REST framework会在请求的查询字符串参数中检查是否包含了ordering参数，如果包含了ordering参数，则按照ordering参数指明的排序字段对数据集进行排序,ordering参数的可选字段值需要在ordering_fields中指明。

from rest_framework.filters import OrderingFilter

5.1基本排序

from rest_framework.filters import 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字段进行升序排序

2.过滤排序

注意

因为排序配置和过滤配置使用同一个类属性,如果需要在过滤以后再次进行排序,则需要两者同步,要么一起写在全局配置中,要么一起写在视图类中,否则会出现过滤组件使用无效的情况

配置文件：

REST_FRAMEWORK = {
    #过滤组件[全局引入]
  'DEFAULT_FILTER_BACKENDS'('django_filters.rest_framework.DjangoFilterBackend','rest_framework.filters.OrderingFilter')
    
}

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

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

6. 分页

6.1.全局分页

REST framework提供了分页的支持,我们可以在配置文件中设置全局的分页方式,如：

REST_FRAMEWORK = {
    #设置了全局分页,那么在drf中凡是调用了ListModelMixin的list(),都会自动分页
    'DEFAULT_PAGINATION_CLASS':  'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 100  # 每页数目
}

class 视图类(ListAPIView):
    # 只存在少部分数据,关闭分页功能
  pagination_class = None

2.自定义分页

也可通过自定义Pagination类,来为视图添加不同分页行为。在视图中通过pagination_clas属性来指明

1.页码分页类

前端访问网址形式：

GET  http://127.0.0.1:8000/students/?page=4

PageNumberPagination

属性	含义
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
    # 允许客户端通过get参数来控制每一页的数据量
    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.偏移分页类

前端访问网址形式：

GET http://127.0.0.1/four/students/?limit=100&offset=100

LimitOffsetPagination

属性	含义
default_limit	默认限制,默认值与PAGE_SIZE设置一致
limit_query_param	limit参数名,默认’limit’
offset_query_param	offset参数名,默认’offset’
max_limit	最大limit限制,默认None

7. 异常处理 Exceptions

1.DRF的异常

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

2.自定义异常

REST framework提供了自定义异常处理,我们可以自定义的方式来编写异常处理函数.例如我们想在要创建一个自定义异常函数,这个函数,我们保存到当前主应用中[注意在实际工作中,我们可以设置一个单独的独立的公共目录来保存这种公共的函数/工具/类库,也就是说,很多的没有在上面列出来的异常,就需要我们在自定义异常中自己处理了

在主应用的配置文件settings.py中声明自定义的异常处理

REST_FRAMEWORK = {
    # 异常处理
    'EXCEPTION_HANDLER': 'drfdemo.exceptions.custom_exception_handler',
}

如果未声明,会采用默认的方式,如下rest_frame/settings.py

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

drfdemo/exceptions.py

from rest_framework.views import exception_handler as drf_exception_handler
from django.db import DatabaseError
from rest_framework.response import Response
from rest_framework import status
def custom_exception_handler(exc, context):
    """
    自定义异常处理函数
    :param exc: 异常对象，本次发生的异常对象
    :param context: 字典，异常出现时的执行上下文环境
    :return:
    """
    # 先让drf进行异常判断
    response = drf_exception_handler(exc, context)

    # 判断response对象是否为None
    if response is None:
        """出现drf不能处理的异常"""
        if isinstance(exc, DatabaseError):
            view = context.get("view")
            print(f"数据库报错,{view}:{exc}")
            return Response({"detail":"服务器内部错误!"}, status=status.HTTP_507_INSUFFICIENT_STORAGE)

        if isinstance(exc, ZeroDivisionError):
            view = context.get("view")
            print(f"0不能做为除数!{view}:{exc}")
            return Response({"detail":"服务器内部错误!"}, status=status.HTTP_500_INTERNAL_SERVER_ERROR)

    return response

8. 自动生成接口文档

官方文档：http://core-api.github.io/python-client/

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

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

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

8.1. 安装依赖

REST framewrok生成接口文档需要coreapi库的支持。

pip install coreapi

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

在settings.py中配置接口文档。

REST_FRAMEWORK = {
    # 。。。 其他选项
    # 接口文档
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema',
}

注意:

#1.搜索self.request.method方法在文件中的使用
if self.request.method.lower() == "get":
            return StudentModelSerializer
#2.将代码修改为以下    
if self.request and self.request.method.lower() == "get":
    return StudentModelSerializer   

在总路由中添加接口文档路径。

文档路由对应的视图配置为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:
    修改图书的阅读量
    """

注意 help_text

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': '年龄'
            }
        }