django-rest-framework框架总结之认证权限限流过滤分页及异常处理

Posted 2023-02-04 七月的小尾巴

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了django-rest-framework框架总结之认证权限限流过滤分页及异常处理相关的知识，希望对你有一定的参考价值。

认证 Authentication

REST 框架提供了几种即用的身份验证方案，并且支持实现自定义认证。

我们需要在 setting.py 文件中设置 DEFAULT_AUTHENTICATION_CLASSES 全局默认身份验证方案。例如。


REST_FRAMEWORK = 
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework.authentication.BasicAuthentication',
        'rest_framework.authentication.SessionAuthentication',
    ]

还可以基于每个视图或每个视图集设置 permission_classes ，且视图中定义的认证方案会高于 DEFAULT_AUTHENTICATION_CLASSES 全局配置。

from rest_framework.authentication import SessionAuthentication, BasicAuthentication
from rest_framework.permissions import IsAuthenticated
from rest_framework.response import Response
from rest_framework.views import APIView

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

    def get(self, request, format=None):
        content = 
            'user': str(request.user),  # `django.contrib.auth.User` instance.
            'auth': str(request.auth),  # None
        
        return Response(content)

或者我们也可以使用装饰器 @api_view 结合函数视图一起使用。

@api_view(['GET'])
@authentication_classes([SessionAuthentication, BasicAuthentication])
@permission_classes([IsAuthenticated])
def example_view(request, format=None):
    content = 
        'user': str(request.user),  # `django.contrib.auth.User` instance.
        'auth': str(request.auth),  # None
    
    return Response(content)

认证失败通常会有两种响应：

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

权限 Permissions

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

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

设置权限策略

可以使用该设置全局设置默认 DEFAULT_PERMISSION_CLASSES 权限策略。例如

REST_FRAMEWORK = 
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.IsAuthenticated',
    ]

如果配置文件中未指明，则设置默认为允许无限制访问

'DEFAULT_PERMISSION_CLASSES': [
   'rest_framework.permissions.AllowAny',
]

DRF中提供的权限策略

AllowAny 允许所有用户
IsAuthenticated 仅通过认证的用户
IsAdminUser 仅管理员用户
IsAuthenticatedOrReadOnly 认证的用户可以完全操作，否则只能 Get 读取

还可以基于每个视图或者每个视图集设置身份验证策略，使用基于 APIView 类的视图。

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

class ExampleView(APIView):
    permission_classes = [IsAuthenticated]

    def get(self, request, format=None):
        content = 
            'status': 'request was permitted'
        
        return Response(content)

或者可以使用 api_view 装饰器与基于函数的视图一起使用。


from rest_framework.decorators import api_view, permission_classes
from rest_framework.permissions import IsAuthenticated
from rest_framework.response import Response

@api_view(['GET'])
@permission_classes([IsAuthenticated])
def example_view(request, format=None):
    content = 
        'status': 'request was permitted'
    
    return Response(content)

注意：类属性或装饰器设置新的权限类时，他的优先级会高于 setting.py 文件中的配置。

如果他们继承自 rest_framework.permissions.BasePermission ，IsAuthenticatedOrReadOnly，则可以使用标准Python 按位运算符组合权限。

from rest_framework.permissions import BasePermission, IsAuthenticated, SAFE_METHODS
from rest_framework.response import Response
from rest_framework.views import APIView

class ReadOnly(BasePermission):
    def has_permission(self, request, view):
        return request.method in SAFE_METHODS

class ExampleView(APIView):
    permission_classes = [IsAuthenticated|ReadOnly]

    def get(self, request, format=None):
        content = 
            'status': 'request was permitted'
        
        return Response(content)

注意： 它支持&（和），|（或）和~（不是）。

自定义权限策略

如需自定义权限，需要继承 rest_framework.permissions.BasePermission 父类，并实现以下任何一种方法，或者全部

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

如果应向请求授予访问权限，则应返回 True ，否则应返回 False.

如果测试失败，自定义权限将引发异常。若要更改与异常关联的错误消息，请直接在自定义权限上实现属性。

from rest_framework import permissions

class CustomerAccessPermission(permissions.BasePermission):
    message = 'Adding customers not allowed.'

    def has_permission(self, request, view):
         ...

示例

下面是一个权限类示例，该权限类根据阻止列表检查传入请求的 IP 地址，并在 IP 被阻止时拒绝请求。

from rest_framework import permissions

class BlocklistPermission(permissions.BasePermission):
    """
    Global permission check for blocked IPs.
    """

    def has_permission(self, request, view):
        ip_addr = request.META['REMOTE_ADDR']
        blocked = Blocklist.objects.filter(ip_addr=ip_addr).exists()
        return not blocked

除了针对所有传入请求运行的全局权限外，您还可以创建对象级权限，这些权限仅针对影响特定对象实例的操作运行。例如：

class IsOwnerOrReadOnly(permissions.BasePermission):
    """
    Object-level permission to only allow owners of an object to edit it.
    Assumes the model instance has an `owner` attribute.
    """

    def has_object_permission(self, request, view, obj):
        # Read permissions are allowed to any request,
        # so we'll always allow GET, HEAD or OPTIONS requests.
        if request.method in permissions.SAFE_METHODS:
            return True

        # Instance must have an attribute named `owner`.
        return obj.owner == request.user

限流 Throttling

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

设置限流策略

可以在配置文件中，使用 DEFAULT_THROTTLE_RATES 中进行全局配置。

REST_FRAMEWORK = 
    'DEFAULT_THROTTLE_CLASSES': [
        #  适用于任何用户对接口访问的限制
        'rest_framework.throttling.AnonRateThrottle',
        # 登录用户对接口访问的限制
        'rest_framework.throttling.UserRateThrottle'
    ],
    'DEFAULT_THROTTLE_RATES': 
        'anon': '100/day',
        'user': '1000/day'

AnonRateThrottle：限制所有匿名未认证的用户，使用 IP 区分用户。
UserRateThrottle：限制认证用户，使用 user_id 来区分
ScopedRateThrottle：限制用户对于每个视图访问频次，使用 IP 或者 user_id

DEFAULT_THROTTLE_RATES 可以使用 second ， minute，hour，或者 day 来指定周期。
同样还可以基于每个视图或者每个视图集设置限流策略，使用基于类视图。

from rest_framework.response import Response
from rest_framework.throttling import UserRateThrottle
from rest_framework.views import APIView

class ExampleView(APIView):
    throttle_classes = [UserRateThrottle]

    def get(self, request, format=None):
        content = 
            'status': 'request was permitted'
        
        return Response(content)

如果将装饰器 @api_view 与基于函数的视图一起使用，则可以使用以下装饰器。

@api_view(['GET'])
@throttle_classes([UserRateThrottle])
def example_view(request, format=None):
    content = 
        'status': 'request was permitted'
    
    return Response(content)

还可以为使用 @action 装饰器创建的路由设置限制类。以这种方式设置的限制类将覆盖任何视图集级别类设置。

@action(detail=True, methods=["post"], throttle_classes=[UserRateThrottle])
def example_adhoc_method(request, pk=None):
    content = 
        'status': 'request was permitted'
    
    return Response(content)

ScopedRateThrottle 自定义限流

REST_FRAMEWORK = 
    'DEFAULT_THROTTLE_CLASSES': [
        'rest_framework.throttling.ScopedRateThrottle'
    ],
    'DEFAULT_THROTTLE_RATES': 
        'uploads': '100/day',
        'contacts': '1000/day'
    


class ExampleView(APIView):
    throttle_scope = "contacts"

过滤 Filtering

Filtering 可以针对列表数据根据字段进行过滤

针对当前用户进行筛选

您可能希望筛选查询集，以确保仅返回与发出请求的当前经过身份验证的用户相关的结果。我们可以使用 request.user 来获取当前用户。

from myapp.models import Purchase
from myapp.serializers import PurchaseSerializer
from rest_framework import generics

class PurchaseList(generics.ListAPIView):
    serializer_class = PurchaseSerializer

    def get_queryset(self):
        """
        This view should return a list of all the purchases
        for the currently authenticated user.
        """
        user = self.request.user
        return Purchase.objects.filter(purchaser=user)

针对网址进行筛选

另一种筛选方式可能涉及根据 URL 的某些部分限制查询集。例如

re_path('^purchases/(?P<username>.+)/$', PurchaseList.as_view()),

然后，可以编写一个视图，该视图返回按 URL 的用户名部分筛选的查询集：

class PurchaseList(generics.ListAPIView):
    serializer_class = PurchaseSerializer

    def get_queryset(self):
        """
        This view should return a list of all the purchases for
        the user as determined by the username portion of the URL.
        """
        username = self.kwargs['username']
        return Purchase.objects.filter(purchaser__username=username)

根据查询参数进行筛选

筛选初始查询集的最后一个示例是根据 url 中的查询参数确定初始查询集。

我们可以覆盖以处理诸如，并且仅当参数包含在 URL 中时才过滤查询集：.get_queryset()

http://example.com/api/purchases?username=denvercoder9username

class PurchaseList(generics.ListAPIView):
    serializer_class = PurchaseSerializer

    def get_queryset(self):
        """
        Optionally restricts the returned purchases to a given user,
        by filtering against a `username` query parameter in the URL.
        """
        queryset = Purchase.objects.all()
        username = self.request.query_params.get('username')
        if username is not None:
            queryset = queryset.filter(purchaser__username=username)
        return queryset

Generic Filtering 通用筛选

可以使用 DEFAULT_FILTER_BACKENDS 设置默认过滤器

REST_FRAMEWORK = 
    'DEFAULT_FILTER_BACKENDS': ['django_filters.rest_framework.DjangoFilterBackend']

还可以按视图或视图集设置筛选器后端，使用基于 GenericAPIView 类的视图。

import django_filters.rest_framework
from django.contrib.auth.models import User
from myapp.serializers import UserSerializer
from rest_framework import generics

class UserListView(generics.ListAPIView):
    queryset = User.objects.all()
    serializer_class = UserSerializer
    filter_backends = [django_filters.rest_framework.DjangoFilterBackend]

DjangoFilterBackend

django-filter 库包含一个类支持 REST 框架的高度可自定义 DjangoFilterBackend 字段筛选。
要使用 DjangoFilterBackend ，请先安装 django-filter

pip install django-filter

然后添加到 Django 的 INSTALLED_APPS ：

INSTALLED_APPS = [
    ...
    'django_filters',
    ...
]

将筛选器后端添加到设置中：

REST_FRAMEWORK = 
    'DEFAULT_FILTER_BACKENDS': ['django_filters.rest_framework.DjangoFilterBackend']

或者将过滤器后端添加到单个视图或视图集

from django_filters.rest_framework import DjangoFilterBackend

class UserListView(generics.ListAPIView):
    ...
    filter_backends = [DjangoFilterBackend]

如果您只需要简单的基于相等的过滤，则可以在视图或视图集上设置 filterset_fields 属性，列出要过滤的字段集。

class ProductList(generics.ListAPIView):
    queryset = Product.objects.all()
    serializer_class = ProductSerializer
    filter_backends = [DjangoFilterBackend]
    filterset_fields = ['category', 'in_stock']

设置了 filterset_fields ，则可以通过如下方式发送请求

http://example.com/api/products?category=clothing&in_stock=True

SearchFilter 搜索过滤器

SearchFilter 类支持简单的基于单个查询参数的搜索，并且基于 Django 管理员的搜索功能。

from rest_framework import filters

class UserListView(generics.ListAPIView):
    queryset = User.objects.all()
    serializer_class = UserSerializer
    filter_backends = [filters.SearchFilter]
    search_fields = ['username', 'email']

客户端通过进行查询来筛选列表中的项目，例如：

默认搜索参数名为 search

http://example.com/api/users?search=russell

还可以使用查找 API 双下划线表示法对外键或 ManyToManyField 执行相关查找：

search_fields = ['username', 'email', 'profile__profession']

对于 JSONField 和 HStoreField 字段，您可以使用相同的双下划线表示法根据数据结构中的嵌套值进行筛选：

search_fields = ['data__breed', 'data__owner__other_pets__0__name']

默认情况下，搜索将使用不区分大小写的部分匹配。搜索参数可以包含多个搜索词，这些搜索词应以空格和/或逗号分隔。如果使用多个搜索词，则仅当提供的所有词都匹配时，才会在列表中返回对象。

可以通过在 search_fields 前面加上各种字符来限制搜索行为。

“^” 从搜索开始。
“=”完全匹配。
“@”全文搜索。（目前仅支持 Django 的 PostgreSQL 后端。）
‘$’ 正则表达式搜索。

search_fields = ['=username', '=email']

OrderingFilter 排序过滤器

OrderingFilter 类支持简单的查询参数控制的结果排序。默认情况下，查询参数名为 ordering
例如，要按用户名对用户进行排序：

http://example.com/api/users?ordering=username

客户端还可以通过在字段名称前面加上“-”来指定反向排序，如下所示：

http://example.com/api/users?ordering=-username

还可以指定多个排序：

http://example.com/api/users?ordering=account,username

建议显式指定 API 应在排序筛选器中允许哪些字段。您可以通过在视图上设置属性来执行此操作，如下所示：

class UserListView(generics.ListAPIView):
    queryset = User.objects.all()
    serializer_class = UserSerializer
    filter_backends = [filters.OrderingFilter]
    ordering_fields = ['username', 'email']

这有助于防止意外的数据泄露，例如允许用户根据密码哈希字段或其他敏感数据进行排序。

如果未在视图上指定 ordering_fields 属性，则筛选器类将默认允许用户筛选属性指定的serializer_class 序列化程序上的任何可读字段。

如果确信视图使用的查询集不包含任何敏感数据，则还可以通过使用特殊值 __all__ 显式指定视图应允许对任何模型字段或查询集聚合进行排序。

class BookingsListView(generics.ListAPIView):
    queryset = Booking.objects.all()
    serializer_class = BookingSerializer
    filter_backends = [filters.OrderingFilter]
    ordering_fields = '__all__'

指定默认排序

如果在视图上设置了 ordering 属性，则将将其用作默认排序。

class UserListView(generics.ListAPIView):
    queryset = User.objects.all()
    serializer_class = UserSerializer
    filter_backends = [filters.OrderingFilter]
    ordering_fields = ['username', 'email']
    ordering = ['username']

分页 Pagination

DRF 中也给我们提供了分页支持。

分页仅仅使用通用视图或视图集时，才会自动执行分页。注意如果使用的是常规 APIView ，则需要自行调用分页 API，以确保返回分页响应。
有关示例，可以参考 mixins.ListModelMixin 和 generics.GenericAPIView 类的源代码。
可以通过将分页类设置为 None 来关闭分页。

可以使用 DEFAULT_PAGINATION_CLASS 和 PAGE_SIZE 设置键全局设置分页样式。例如，要使用内置的限制/偏移分页，您可以执行以下操作：

REST_FRAMEWORK = 
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.LimitOffsetPagination',
    'PAGE_SIZE': 100

如果要修改分页样式的特定方面，则需要覆盖其中一个分页类，并设置要更改的属性。

class LargeResultsSetPagination(PageNumberPagination):
    page_size = 1000
    page_size_query_param = 'page_size'
    max_page_size = 10000

class StandardResultsSetPagination(PageNumberPagination):
    page_size = 100
    page_size_query_param = 'page_size'
    max_page_size = 1000

可以使用pagination_class 属性将新样式应用于视图：

class BillingRecordsView(generics.ListAPIView):
    queryset = Billing.objects.all()
    serializer_class = BillingRecordsSerializer
    pagination_class = LargeResultsSetPagination

或者使用 DEFAULT_PAGINATION_CLASS 设置键全局应用样式。例如：

REST_FRAMEWORK = 
    'DEFAULT_PAGINATION_CLASS': 'apps.core.pagination.StandardResultsSetPagination'

PageNumberPagination 页码分页

首先需要在 DEFAULT_PAGINATION_CLASS 和 PAGE_SIZE 设置键全局设置分页样式。

REST_FRAMEWORK = 
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 100

请求：

https://api.example.org/accounts/?page=4

响应：

HTTP 200 OK

    "count": 1023,
    "next": "https://api.example.org/accounts/?page=5",
    "previous": "https://api.example.org/accounts/?page=3",
    "results": [
       …
    ]

**注意：如果我们在视图中需要关闭分页功能，可我们只需要在视图中设置pagination_class 为 None **

pagination_class = None

PageNumberPagination 类包含许多属性，可以重写这些属性以修改 PageNumberPagination 分页样式。

若要设置这些属性，应重写 PageNumberPagination 类，然后启用自定义分页类，如上所示

django_paginator_class：要使用的 Django Paginator类。默认值为 django.core.paginator.Paginator ，这对于大多数用例来说应该没问题。
page_size：指示页面大小的数值。如果设置 PAGE_SIZE，这将覆盖该设置。默认为 PAGE_SIZE 与设置键相同的值。
page_query_param：一个字符串值，指示要用于分页控件的查询参数的名称。
page_size_query_param：如果设置，则这是一个字符串值，指示允许客户端基于每个请求设置页面大小的查询参数的名称。默认值为 None ，表示客户端可能无法控制请求的页面大小。
max_page_size：如果设置，则这是一个数值，指示允许的最大请求页面大小。仅当还设置了 page_size_query_param此属性时，此属性才有效。
last_page_strings：字符串值的列表或元组，指示可与一起使用以请求集合中的最后一页的值。默认值 page_query_param

LimitOffsetPagination 偏移分页

要全局启用 LimitOffsetPagination 样式，请使用以下配置：

REST_FRAMEWORK = 
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.LimitOffsetPagination'

请求：

GET https://api.example.org/accounts/?limit=100&offset=400

响应：

HTTP 200 OK

    "count": 1023,
    "next": "https://api.example.org/accounts/?limit=100&offset=500",
    "previous": "https://api.example.org/accounts/?limit=100&offset=300",
    "results": [
       …
    ]

自定义分页样式

若要创建自定义分页序列化程序类，应继承 pagination.BasePagination 子类，重写 paginate_queryset(self, queryset, request, view=None) 和 get_paginated_response(self, data)方法：

class CustomPagination(pagination.PageNumberPagination):
    def get_paginated_response(self, data):
        return Response(
            'links': 
                'next': self.get_next_link(),
                以上是关于django-rest-framework框架总结之认证权限限流过滤分页及异常处理的主要内容，如果未能解决你的问题，请参考以下文章 
 django-rest-framework框架总结之View视图之APIViewGenericAPIView视图集ViewSet
 Django-rest-framework --- 总结
 python django-rest-framework 3.3.3 更新嵌套序列化程序
 断言错误：Django-rest-Framework
 Django-rest-framework 中的全局异常处理
 使用 django-rest-framework 序列化程序检索外键值