rest_framework 集成使用 django-filter

在rest_framework中查询结果集有两种方式，一种是重写get_queryset()，另外一种是使用通用的filter_backends

一、重写`get_queryset()`查询结果

example 1. 根据查询参数进行过滤

class PurchaseList(generics.ListAPIView):
    serializer_class = PurchaseSerializer
    queryset = Purchase.objects,all()

    def get_queryset(self):
        queryset = self.queryset
        # 根据查询参数进行过滤
        price = self.request.query_params.get('price', None)

        try:
            price = float(price)
        except Exception:
            price = None

        if price is not None:
            queryset = queryset.filter(purchaser__price=price)
        return queryset

example 2. 根据网址进行过滤

url('^purchases/(?P.+)/$', PurchaseList.as_view()),

class PurchaseList(generics.ListAPIView):
    serializer_class = PurchaseSerializer

    def get_queryset(self):
        username = self.kwargs['username']
        return Purchase.objects.filter(purchaser__username=username)

通过重写get_queryset()能够实现查询功能，但是为每一个资源都手写查询是很麻烦的。使用filter_backends 与 django-filter可以帮助我们更好的完成这种工作。

二、在视图类中配置`filter_backends`

注意：使用filter_backends的前提是我们的视图类继承了mixins.ListModelMixin,该组件提供的list方法调用了filter_queryset。如果我们自己重写了list，则获取queryset时需要使用：

queryset = self.filter_queryset(self.get_queryset())

class ListModelMixin:
    """
    List a queryset.
    """
    def list(self, request, *args, **kwargs):
        # 这里`filter_queryset`, 实际调用了`backend().filter_queryset`
        queryset = self.filter_queryset(self.get_queryset())

        page = self.paginate_queryset(queryset)
        if page is not None:
            serializer = self.get_serializer(page, many=True)
            return self.get_paginated_response(serializer.data)

        serializer = self.get_serializer(queryset, many=True)
        return Response(serializer.data)

filter_backends可以是一个类列表，提供多个filter_backends则可以实现多种方式的查询。

1. 使用`DjangoFilterBackend`实现`字段查询`

rest_framework本身不提供DjangoFilterBackend，而是使用第三方库django-filter的DjangoFilterBackend

1.1 安装`django-filter`

使用pip进行安装

pip install django-filter

1.2 使用`DjangoFilterBackend`配合`filterset_fields`

example 1. 在ViewSet类中使用filter_backends 与 filterset_fields

# models.py
from django.db import models


class Manufacturer(models.Model):
    name = models.CharField(max_length=64)


class Product(models.Model):
    name = models.CharField(max_length=255)
    price = models.FloatField()
    description = models.TextField()
    release_date = models.DateField(auto_now=True)
    manufacturer = models.ForeignKey(Manufacturer, on_delete=models.CASCADE)

# views.py
from rest_framework.viewsets import ModelViewSet
from django_filters.rest_framework import DjangoFilterBackend
from rest_framework import serializers
from my_app.models import Product


class ProductSerializer(serializers.ModelSerializer):
    class Meta:
        model = Product
        fields = '__all__'


class ProductViewSet(ModelViewSet):
    queryset = Product.objects.all()
    serializer_class = ProductSerializer
    filter_backends = [DjangoFilterBackend, ]
    filterset_fields = ['name', 'manufacturer', 'price'] # 支持精准匹配的字段

# urls.py

from rest_framework.routers import DefaultRouter
router = DefaultRouter()
router.register('products', views.ProductViewSet)

urlpatterns = router.urls

在ViewSet中，使用filterset_fields来表明支持查询的字段，filterset_fields并不是ViewSet自带的属性，只有在使用filter_backends才会使用该属性。

这样我们就可以向下面这样执行字段查询

http://127.0.0.1:8000/products/?name=sdfd&price=23.65&manufacturer=1

1.3 使用`DjangoFilterBackend`配合`filterset_class`

在1.2中，我们可以通过filterset_fields指定查询字段，但是这只能指定model中存在的字段。使用filterset_class可以帮助我们自定义制定查询。

filterset_class 与 filterset_fields是互斥的，我们只需要使用两者的一个。

1. 创建filterset_class

import django_filters.rest_framework as filters
from my_app.models import Product


class ProductFilter(filters.FilterSet):
    # p_name 实际是查询`name`字段
    p_name = filters.CharFilter(field_name='name')

    class Meta:
        model = Product
        # 对于`model`中存在的字段，可以直接指定字段名
        fields = ['price', 'release_date'] 
        # 最终支持查询的字段包含自定义的`p_name`与  `fields`中指定的字段

1. 在 ViewSet中指定filterset_class值

class ProductViewSet(ModelViewSet):
    queryset = Product.objects.all()
    serializer_class = ProductSerializer
    filter_backends = [DjangoFilterBackend, ]
    filterset_class = ProductFilter

通过自定义filterset_class类，我们可以传入model中不存在的字段p_name

http://127.0.0.1:8000/products/?p_name=sdfd&price=23.65&manufacturer=1

除了修改字段名，filterset_class还可以实现django的field__lookuptype=value查询，以及跨关系查询。

import django_filters.rest_framework as filters
from my_app.models import Product


class ProductFilter(filters.FilterSet):
    p_name = filters.CharFilter(field_name='name')
    
    # 用法和`django`一样
    # 这里会自动补全中间的双下划线
    min_price = filters.NumberFilter(field_name='price', lookup_expr='gte')
    max_price = filters.NumberFilter(field_name='price', lookup_expr='lte')
    min_year = filters.NumberFilter(field_name='release_date', lookup_expr='year__gte')

    class Meta:
        model = Product
        fields = ['price', 'release_date', 'manufacturer__name']

可以实现以下访问

[http://127.0.0.1:8000/products/?manufacturer__name=fksd&min_price=35&min_year=1983

2. 使用`SearchFilter`实现`搜索`查询

SearchFilter为rest_framework自带的类，它可以搜索模型（包含模型关系）中的文本类型的字段

2.1 使用`SearchFilter`配合`search_fields`一起使用

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

跨关系搜索也是一样支持的

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

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

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

'^'从开头匹配。
'='完全匹配。
'@'（当前仅支持Django的PostgreSQL后端。）
'$'正则表达式匹配。

例如：

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

2.2 动态指定`search_fields`

有的时候我们无法事先指定查询字段,而是要根据request的请求内容给予开放查询字段。

继承SearchFilter并覆盖该get_search_fields()函数。重写get_search_fields()
后，指定的search_fields就不再生效了。

from rest_framework import filters

class CustomSearchFilter(filters.SearchFilter):
    search_param = 'find' # 这里可以修改查询的参数，默认为`search`
    def get_search_fields(self, view, request):
        # view 就是当前视图对象
        # 返回一个列表字段
        ……

3. 使用`OrderingFilter`对查询结果排序

注意：OrderingFilter从rest_framework导入，而不是django_filters
这两个库都有OrderingFilter,容易弄混。

3.1 设置排序参数名称

OrderingFilter的默认表示排序的参数为ordering，但是可以在settings.py文件中设置ORDERING_PARAM覆盖，这样对所有使用OrderingFilter都生效

REST_FRAMEWORK = {
    'ORDERING_PARAM': 'order_by',
}

或者继承OrderingFilter，重写ordering_param属性

class MyOrderingFilter(OrderingFilter):
    ordering_param = 'order_by'

例如，按用户名订购用户：

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

客户端还可以通过在字段名称前添加“-”来指定相反的顺序，如下所示：

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

也可以指定多个顺序：

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

3.2 设置排序字段

如果没有设置允许排序的字段，将默认为允许用户对由serializer_class属性指定的序列化器上的任何可读字段进行过滤。
通过设置ordering_fields可以明确指定允许排序的字段

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

设置ordering_fields = '__all__'将允许对模型中的所有字段进行排序

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

3.3 指定默认排序字段

通过ordering可以设置默认排序，当用户没有传入排序字段，就按照ordering值进行排序。

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

rest_framework 集成使用 django-filter

一、重写get_queryset()查询结果

二、在视图类中配置filter_backends

1. 使用DjangoFilterBackend实现字段查询

1.1 安装django-filter

1.2 使用DjangoFilterBackend配合filterset_fields

1.3 使用DjangoFilterBackend配合filterset_class

2. 使用SearchFilter实现搜索查询

2.1 使用SearchFilter配合search_fields一起使用

2.2 动态指定search_fields

3. 使用OrderingFilter对查询结果排序