Django REST framework的使用总结

10,090 阅读17分钟
  • 在序列化与反序列化时,虽然操作的数据不尽相同,但是执行的过程却是相似的,也就是说这部分代码是可以复用简化编写的;

  • 在开发REST API的视图中,虽然每个视图具体操作的数据不同,但增、删、改、查的实现流程基本套路化,所以这部分代码也是可以复用简化编写;

Django REST framework 框架是一个用于构建Web API 的强大而又灵活的工具。通常简称为DRF框架 或 REST framework。DRF框架是建立在Django框架基础之上,由Tom Christie大牛二次开发的开源项目。

1.特点

  • 提供了定义序列化器Serializer的方法,可以快速根据 Django ORM 或者其它库自动序列化/反序列化;

  • 提供了丰富的类视图、Mixin扩展类,简化视图的编写;

  • 丰富的定制层级:函数视图、类视图、视图集合到自动生成 API,满足各种需要;

  • 多种身份认证和权限认证方式的支持;

  • 内置了限流系统;

  • 直观的 API web 界面;

  • 可扩展性,插件丰富

2.环境安装与配置

pip install djangorestframework  #安装

DRF需要以下依赖:

  • Python (2.7, 3.2, 3.3, 3.4, 3.5, 3.6)

  • Django (1.11, 2.0)

DRF是以Django扩展应用的方式提供的,所以我们可以直接利用已有的Django环境而无需从新创建。(若没有Django环境,需要先创建环境安装Django)

django配置文件settings.py(以具体项目为准)的INSTALLED_APPS中添加'rest_framework'。

INSTALLED_APPS = [    ...    'rest_framework',]

3.序列化器

序列化器的作用:

  1. 进行数据的校验

  2. 对数据对象进行转换

3.1Serializer

DRF中的Serializer使用类来定义,须继承自rest_framework.serializers.Serializer

先建一个数据库模型类BookInfo.

class BookInfo(models.Model):
    btitle = models.CharField(max_length=20, verbose_name='名称')
    bpub_date = models.DateField(verbose_name='发布日期', null=True)
    bread = models.IntegerField(default=0, verbose_name='阅读量')
    bcomment = models.IntegerField(default=0, verbose_name='评论量')
    image = models.ImageField(upload_to='booktest', verbose_name='图片', null=True)

想要为这个模型类提供一个序列化器,可以定义如下:

class BookInfoSerializer(serializers.Serializer):
    """图书数据序列化器"""
    id = serializers.IntegerField( read_only=True)
    btitle = serializers.CharField( max_length=20)
    bpub_date = serializers.DateField( )
    bread = serializers.IntegerField()
    bcomment = serializers.IntegerField( )
    image = serializers.ImageField( )

read_only指定只参与序列化,max_length限定字符串最大长度。字段里不传参数序列化与反序列化都参与。

注意:serializer不是只能为数据库模型类定义,也可以为非数据库模型类的数据定义。serializer是独立于数据库之外的存在。

字段与选项

常用字段类型

字段字段构造方式
BooleanFieldBooleanField()
NullBooleanFieldNullBooleanField(),# null,True,False
CharFieldCharField(max_length=None, min_length=None, allow_blank=False, trim_whitespace=True)
EmailFieldEmailField(max_length=None, min_length=None, allow_blank=False)
RegexFieldRegexField(regex, max_length=None, min_length=None, allow_blank=False)
SlugFieldSlugField(max
length=50, min_length=None, allow_blank=False) 正则字段,验证正则模式 [a-zA-Z0-9
-]+
URLFieldURLField(max_length=200, min_length=None, allow_blank=False)
UUIDFieldUUIDField(format='hex_verbose') format: 1) 'hex_verbose'"5ce0e9a5-5ffa-654b-cee0-1238041fb31a" 2) 'hex'"5ce0e9a55ffa654bcee01238041fb31a" 3)'int' - 如: "123456789012312313134124512351145145114" 4)'urn' 如: "urn:uuid:5ce0e9a5-5ffa-654b-cee0-1238041fb31a"
IPAddressFieldIPAddressField(protocol='both', unpack_ipv4=False, **options)
IntegerFieldIntegerField(max_value=None, min_value=None)
FloatFieldFloatField(max_value=None, min_value=None)
DecimalFieldDecimalField(max_digits, decimal_places, coerce_to_string=None, max_value=None, min_value=None) max_digits: 最多位数 decimal_palces: 小数点位置
DateTimeFieldDateTimeField(format=api_settings.DATETIME_FORMAT, input_formats=None)
DateFieldDateField(format=api_settings.DATE_FORMAT, input_formats=None)
TimeFieldTimeField(format=api_settings.TIME_FORMAT, input_formats=None)
DurationFieldDurationField()
ChoiceFieldChoiceField(choices)  # choices与Django的用法相同
MultipleChoiceFieldMultipleChoiceField(choices)
FileFieldFileField(max_length=None, allow_empty_file=False, use_url=UPLOADED_FILES_USE_URL)
ImageFieldImageField(max_length=None, allow_empty_file=False, use_url=UPLOADED_FILES_USE_URL)
ListFieldListField(child=, min_length=None, max_length=None)
DictFieldDictField(child=)

通用参数说明:

参数名称说明
read_only表明该字段仅用于序列化输出,默认False
write_only表明该字段仅用于反序列化输入,默认False
required表明该字段在反序列化时必须输入,默认True
default反序列化时使用的默认值
allow_null表明该字段是否允许传入None,默认False
validators该字段使用的验证器
error_messages包含错误编号与错误信息的字典
label用于HTML展示API页面时,显示的字段名称
help_text用于HTML展示API页面时,显示的字段帮助提示信息

3.2 序列化使用

1) 先查询出一个图书对象或所有图书

from book.models import BookInfo

book = BookInfo.objects.get(id=1)
# books = BookInfo.objects.all()

2) 构造序列化器对象

from book.serializers import BookInfoSerializer​

serializer = BookInfoSerializer(book)

3)获取序列化数据

通过data属性可以获取序列化后的数据

serializer.data

4)如果要被序列化的是包含多条数据的查询集QuerySet,可以通过添加many=True参数补充说明,后面这句必加,不然会报错。

serializer = BookInfoSerializer(books, many=True)
serializer.data

完整代码:

import json
from django.http import JsonResponse
from django.views import View
from book.models import BookInfo


class BooksView(View):

    def get(self, request):
        '''
        :param request:
        :return: 查询所有图书
        '''
        books = BookInfo.objects.all()
        ser = BookInfoSerializer(books, many=True)
        data = ser.data
        return JsonResponse(data, safe=False)

关联对象嵌套序列化

BookInfo的关系模型类HeroInfo定义如下:

# 定义英雄模型类HeroInfo
class HeroInfo(models.Model):
    GENDER_CHOICES = (
        (0, 'female'),
        (1, 'male')
    )
    hname = models.CharField(max_length=20, verbose_name='名称')
    hgender = models.SmallIntegerField(choices=GENDER_CHOICES, default=0, verbose_name='性别')
    hcomment = models.CharField(max_length=200, null=True, verbose_name='描述信息')
    hbook = models.ForeignKey(BookInfo, related_name='heroes', on_delete=models.CASCADE, verbose_name='图书')  # 外键
    is_delete = models.BooleanField(default=False, verbose_name='逻辑删除')

    class Meta:
        db_table = 'tb_heros'
        verbose_name = '英雄'
        verbose_name_plural = verbose_name

    def __str__(self):
        return self.hname

BookInfoSerializer序列化器中添加下面字段及其说明:

1) PrimaryKeyRelatedField

此字段将被序列化为关联对象的主键。属性使用related_name的值,如果没有则使用关联类小写_set(heroinfo_set)

heroes = serializers.PrimaryKeyRelatedField( read_only=True)

指明字段时需要包含read_only=True或者queryset参数:

  • 包含read_only=True参数时,该字段将不能用作反序列化使用

from book.serializers import HeroInfoSerializer
from book.models import HeroInfo

hero = HeroInfo.objects.get(id=6)
serializer = HeroInfoSerializer(hero)
serializer.data
2) StringRelatedField

此字段将被序列化为关联对象的字符串表示方式(即heroinfo模型类__str__方法的返回值)

heroes = serializers.StringRelatedField()
3)使用关联对象的序列化器
heroes = HeroInfoSerializer(many=True)  # 根据指定的HeroSerialzier序列化中指定的字段返回

注意HeroInfoSerializer要先在BookInfoSerializer定义出来才能使用。

3.3 反序列化使用

  • 使用序列化器进行反序列化时,需要对数据进行验证后,才能获取验证成功的数据或保存成模型类对象;

  • 在获取反序列化的数据前,必须调用is_valid()方法进行验证,验证成功返回True,否则返回False;

  • 验证失败,可以通过序列化器对象的errors属性获取错误信息,返回字典,包含了字段和字段的错误。如果是非字段错误,可以通过修改REST framework配置中的NON_FIELD_ERRORS_KEY来控制错误字典中的键名;

  • 验证成功,可以通过序列化器对象的validated_data属性获取数据。

在定义序列化器时,指明每个字段的序列化类型和选项参数,本身就是一种验证行为。通过构造序列化器对象,并将要反序列化的数据传递给data构造参数,进而进行验证。

class BookView(View):
    def put(self, request, pk):
        data = json.loads(request.body.decode())
        # btitle = data.get('btitle')
        try:
            book = BookInfo.objects.get(pk=pk)
        except Exception:
            return JsonResponse({'errors': '未找到该书'})

        ser = BookInfoSerializer(book, data=data)
        ser.is_valid(raise_exception=True)
       

序列化器中还提供了下面的验证方式:

  • 验证单一字段

class BookInfoSerializer(serializers.Serializer):
   
    ...
    
        def validated_btitle(self, value):
        if value == 'python':
            raise serializers.ValidationError('书名python错误')
        return value
  • 验证多个字段

    class BookInfoSerializer(serializers.Serializer):
        """图书数据序列化器"""
        ...
    
        def validate(self, attrs):
            bread = attrs['bread']
            bcomment = attrs['bcomment']
            if bread < bcomment:
                raise serializers.ValidationError('阅读量小于评论量')
            return attrs

保存数据

如果在验证成功后,想要基于validated_data类属性完成数据对象的创建,可以通过实现create()和update()两个方法来实现。

class BookInfoSerializer(serializers.Serializer):
    """图书数据序列化器"""
    ...

    def create(self, validated_data):
        """新建"""
        return BookInfo(**validated_data)

    def update(self, instance, validated_data):
        """更新,instance为要更新的对象实例"""
        instance.btitle = validated_data.get('btitle', instance.btitle)
        instance.bpub_date = validated_data.get('bpub_date', instance.bpub_date)
        instance.bread = validated_data.get('bread', instance.bread)
        instance.bcomment = validated_data.get('bcomment', instance.bcomment)
        return instance

如果需要在返回数据对象的时候,也将数据保存到数据库中,则可以进行如下修改

class BookInfoSerializer(serializers.Serializer):
    """图书数据序列化器"""
    ...

    def create(self, validated_data):
        """新建"""
        return BookInfo.objects.create(**validated_data)

    def update(self, instance, validated_data):
        """更新,instance为要更新的对象实例"""
        instance.btitle = validated_data.get('btitle', instance.btitle)
        instance.bpub_date = validated_data.get('bpub_date', instance.bpub_date)
        instance.bread = validated_data.get('bread', instance.bread)
        instance.bcomment = validated_data.get('bcomment', instance.bcomment)
        instance.save()
        return instance

实现了上述两个方法后,在反序列化数据的时候,就可以通过save()方法返回一个数据对象实例了。

class BookView(View):
    def put(self, request, pk):
   
        data = json.loads(request.body.decode())
        # btitle = data.get('btitle')
        try:
            book = BookInfo.objects.get(pk=pk)
        except Exception:
            return JsonResponse({'errors': '未找到该书'})

        ser = BookSerializer(book, data=data)
        ser.is_valid(raise_exception=True)
        ser.save() #返回数据对象实例
        return JsonResponse(ser.data)

如果创建序列化器对象的时候,没有传递instance实例,则调用save()方法的时候,create()被调用,相反,如果传递了instance实例,则调用save()方法的时候,update()被调用。

3.4 模型类序列化器ModelSerializer

如果我们想要使用序列化器对应的是Django的模型类,DRF为我们提供了ModelSerializer模型类序列化器来帮助我们快速创建一个Serializer类。

ModelSerializer与常规的Serializer相同,但提供了:

  • 基于模型类自动生成一系列字段

  • 基于模型类自动为Serializer生成validators,比如unique_together

  • 包含默认的create()和update()的实现

定义

要使用要继承serializers.ModelSerializer

比如我们创建一个BookInfoSerializer:

class BookInfoSerializer(serializers.ModelSerializer):
    """图书数据序列化器"""
    class Meta:
        model = BookInfo
        fields = '__all__' # 返回所有字段
  • model 指明参照哪个模型类

  • fields 指明为模型类的哪些字段生成

我们可以在django环境中执行python manage.py shell命令来查看自动生成的BookInfoSerializer的具体实现。

>>> from booktest.serializers import BookInfoSerializer
>>> serializer = BookInfoSerializer()
>>> serializer
BookInfoSerializer():
    id = IntegerField(label='ID', read_only=True)
    btitle = CharField(label='名称', max_length=20)
    bpub_date = DateField(allow_null=True, label='发布日期', required=False)
    bread = IntegerField(label='阅读量', max_value=2147483647, min_value=-2147483648, required=False)
    bcomment = IntegerField(label='评论量', max_value=2147483647, min_value=-2147483648, required=False)
    image = ImageField(allow_null=True, label='图片', max_length=100, required=False)

指定字段

1) 使用fields来明确字段,__all__表名包含所有字段,也可以写明具体哪些字段,如

class BookInfoSerializer(serializers.ModelSerializer):
    """图书数据序列化器"""
    class Meta:
        model = BookInfo # 指定根据哪个模型类来序列化
        fields = ('id', 'btitle', 'bpub_date')

2) 使用exclude可以明确排除掉哪些字段

class BookInfoSerializer(serializers.ModelSerializer):
    """图书数据序列化器"""
    class Meta:
        model = BookInfo
        exclude = ('bread',)

3) 显示指明字段,如:

class HeroInfoSerializer(serializers.ModelSerializer):
    hbook = BookInfoSerializer()

    class Meta:
        model = HeroInfo
        fields = ('id', 'hname', 'hgender', 'hcomment', 'hbook')

4) 指明只读字段

可以通过read_only_fields指明只读字段,即仅用于序列化输出的字段

class BookInfoSerializer(serializers.ModelSerializer):
    """图书数据序列化器"""
    class Meta:
        model = BookInfo
        fields = ('id', 'btitle', 'bpub_date''bread', 'bcomment')
        read_only_fields = ('id', 'bread', 'bcomment')

添加额外参数

我们可以使用extra_kwargs参数为ModelSerializer添加或修改原有的选项参数

class BookInfoSerializer(serializers.ModelSerializer):
    
    """图书数据序列化器"""
    class Meta:
        model = BookInfo
        fields = ('id', 'btitle', 'bpub_date', 'bread', 'bcomment')
        extra_kwargs = {
            'bread': {'min_value': 0, 'required': True},
            'bcomment': {'min_value': 0, 'required': True},
        }

# BookInfoSerializer():
#    id = IntegerField(label='ID', read_only=True)
#    btitle = CharField(label='名称', max_length=20)
#    bpub_date = DateField(allow_null=True, label='发布日期', required=False)
#    bread = IntegerField(label='阅读量', max_value=2147483647, min_value=0, required=True)
#    bcomment = IntegerField(label='评论量', max_value=2147483647, min_value=0, required=True)

4.视图

4.1 Request

REST framework 传入DRF封装后视图的request对象不再是Django默认的HttpRequest对象,而是REST framework提供的扩展了HttpRequest类的Request类的对象。

REST framework 提供了Parser解析器,在接收到请求后会自动根据Content-Type指明的请求数据类型(如JSON、表单等)将请求数据进行parse解析,解析为类字典对象保存到Request对象中。

Request对象的数据是自动根据前端发送数据的格式进行解析之后的结果。

无论前端发送的哪种格式的数据,我们都可以以统一的方式读取数据。

data

request.data 返回解析之后的请求体(表单、json)数据。类似于Django中标准的request.POSTrequest.FILES属性,但提供如下特性:

  • 包含了解析之后的文件和非文件数据

  • 包含了对POST、PUT、PATCH请求方式解析后的数据

  • 利用了REST framework的parsers解析器,不仅支持表单类型数据,也支持JSON数据

query_params

request.query_params与Django标准的request.GET相同,用于获取查询字符串,只是更换了更正确的名称而已。

4.2 Response

rest_framework.response.Response

REST framework提供了一个响应类Response,使用该类构造响应对象时,响应的具体数据内容会被转换(render渲染)成符合前端需求的类型。

构造方式

Response(data, status=None, template_name=None, headers=None, content_type=None)

data数据不要是render处理之后的数据,只需传递python的内建类型数据即可,REST framework会使用renderer渲染器处理data

data不能是复杂结构的数据,如Django的模型类对象,对于这样的数据我们可以使用Serializer序列化器序列化处理后(转为了Python字典类型)再传递给data参数。

参数说明:

  • data: 为响应准备的序列化处理后的数据;

  • status: 状态码,默认200;

  • template_name: 模板名称,如果使用HTMLRenderer 时需指明;

  • headers: 用于存放响应头信息的字典;

  • content_type: 响应数据的Content-Type,通常此参数无需传递,REST framework会根据前端所需类型数据来设置该参数。

状态码

为了方便设置状态码,REST framewrokrest_framework.status模块中提供了常用状态码常量。

这样前面的获取与更新单一图书可改写为如下形式:

from rest_framework.views import APIView, View
from rest_framework.response import Response
from book.models import BookInfo
from book.serializers import BookInfoSerializer

class BooksView(APIView):
    
	def get(self, request, pk):
        """
         获取单一图书
        :param request:
        :return:
        """
        # 查询数据
        try:
            book = BookInfo.objects.get(id=pk)
        except:
            return Response({"error": '错误的id'}, status=400)

        # 返回结果

        ser = BookSerializer(book)

        return Response(ser.data)

    def put(self, request, pk):
            """
             更新单一图书
            :param request:
            :return:
            """
            # 1、获取前端数据
            data = request.data
            # 2、验证数据
            book = BookInfo.objects.get(id=pk)
            ser = BookInfoSerializer(book, data=data)
            ser.is_valid(raise_exception=True)
            # 3、更新数据
            ser.save()
            # 4、返回结果
            return Response(ser.data)

如果返回所有图书列表,不用再像以前JsonResponse中需指定safe=False了。

4.3 APIView

rest_framework.views.APIView

APIView是REST framework提供的所有视图的基类,继承自Django的View父类。

APIViewView的不同之处在于:

  • 传入到视图方法中的是REST framework的Request对象,而不是Django的HttpRequeset对象;

  • 视图方法可以返回REST framework的Response对象,视图会为响应数据设置(render)符合前端要求的格式;

  • 任何APIException异常都会被捕获到,并且处理成合适的响应信息;

  • 在进行dispatch()分发前,会对请求进行身份认证、权限检查、流量控制。

支持定义的属性:
  • authentication_classes 列表或元祖,身份认证类

  • permissoin_classes 列表或元祖,权限检查类

  • throttle_classes 列表或元祖,流量控制类

APIView中仍以常规的类视图定义方法来实现get() 、post() 或者其他请求方式的方法。

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

# url(r'^books/$', views.BookListView.as_view()),
class BookListView(APIView):
    def get(self, request):
        books = BookInfo.objects.all()
        serializer = BookInfoSerializer(books, many=True)
        return Response(serializer.data)

4.4 GenericAPIView

rest_framework.generics.GenericAPIView继承自APIVIew,增加了对于列表视图和详情视图可能用到的通用支持方法。通常使用时,可搭配一个或多个Mixin扩展类。

支持定义的属性:
  • 列表视图与详情视图通用:

    • queryset 列表视图的查询集

    • serializer_class 视图使用的序列化器

  • 列表视图使用:

    • pagination_class 分页控制类

    • filter_backends 过滤控制后端

  • 详情页视图使用:

    • lookup_field 查询单一数据库对象时使用的条件字段,默认为'pk'

    • lookup_url_kwarg 查询单一数据时URL中的参数关键字名称,默认与look_field相同

提供的方法:
  • 列表视图与详情视图通用:

    • get_queryset(self)

      返回视图使用的查询集,是列表视图与详情视图获取数据的基础,默认返回queryset属性,可以重写,例如:

      def get_queryset(self):
          user = self.request.user
          return user.accounts.all()
    • get_serializer_class(self)

      返回序列化器类,默认返回serializer_class,可以重写,例如:

      def get_serializer_class(self):
          if self.request.user.is_staff:
              return FullAccountSerializer
          return BasicAccountSerializer
    • get_serializer(self, *args, **kwargs)

      返回序列化器对象,被其他视图或扩展类使用,如果我们在视图中想要获取序列化器对象,可以直接调用此方法。

      注意,在提供序列化器对象的时候,REST framework会向对象的context属性补充三个数据:request、format、view,这三个数据对象可以在定义序列化器时使用。

  • 详情视图使用:

    • get_object(self) 返回详情视图所需的模型类数据对象,默认使用lookup_field参数来过滤queryset。 在试图中可以调用该方法获取详情信息的模型类对象。

      若详情访问的模型类对象不存在,会返回404。

      该方法会默认使用APIView提供的check_object_permissions方法检查当前对象是否有权限被访问。

class BooksView(GenericAPIView):
    queryset = BookInfo.objects.all() #指定查询集
    serializer_class = BookInfoSerializer # 指定序列化器

    def get(self, request):
        '''查询所有图书'''
        books = self.get_queryset() 获取查询集
        # book = self.get_object() 获取单一数据对象
        serializer = self.get_serializer(books, many = True) #获取序列化器
        return Response(serializer.data)
    
      def post(self, request):
        """
         保存图书
        """
        # 1、获取前端数据
        data = request.data
        # 2、验证数据
        ser = self.get_serializer(data=data)
        ser.is_valid(raise_exception=True)
        # 3、保存数据
        ser.save()
        # 4、返回结果
        return Response(ser.data)

两个类关系图如下:


5.五个扩展类

5.1 ListModelMixin

列表视图扩展类,提供list(request, *args, **kwargs)方法快速实现列表视图,返回200状态码。

from rest_framework.mixins import ListModelMixin

class BooksView(ListModelMixin, GenericAPIView):
    queryset = BookInfo.objects.all()
    serializer_class = BookInfoSerializer

    def get(self, request):
        return self.list(request)

5.2 CreateModelMixin

创建视图扩展类,提供create(request, *args, **kwargs)方法快速实现创建资源的视图,成功返回201状态码。如果序列化器对前端发送的数据验证失败,返回400错误。

from rest_framework.mixins import CreateModelMixin

class BooksView(CreateModelMixin, GenericAPIView):    
    serializer_class = BookInfoSerializer

    def post(self, request):
        return self.create(request)

5.3 RetrieveModelMixin

详情视图扩展类,提供retrieve(request, *args, **kwargs)方法,可以快速实现返回一个存在的数据对象。如果存在,返回200, 否则返回404。

class BooksView(RetrieveModelMixin, GenericAPIView):
    queryset = BookInfo.objects.all()
    serializer_class = BookInfoSerializer

    def get(self, request, pk):
        return self.retrieve(request)

5.4 UpdateModelMixin

更新视图扩展类,提供update(request, *args, **kwargs)方法,可以快速实现更新一个存在的数据对象。同时也提供partial_update(request, *args, **kwargs)方法,可以实现局部更新。

成功返回200,序列化器校验数据失败时,返回400错误。

5.5 DestroyModelMixin

删除视图扩展类,提供destroy(request, *args, **kwargs)方法,可以快速实现删除一个存在的数据对象。成功返回204,不存在返回404。


GenericAPIView配合扩展类使用举例如下,它为我们省略了很多代码。

from rest_framework.views import APIView, View
from rest_framework.generics import GenericAPIView
from rest_framework.mixins import CreateModelMixin, UpdateModelMixin, DestroyModelMixin, RetrieveModelMixin, ListModelMixin
from rest_framework.response import Response
from book.models import BookInfo
from book.serializers import BookInfoSerializer


class BooksView(CreateModelMixin, ListModelMixin, GenericAPIView):
    serializer_class = BookInfoSerializer  # 指定序列化器
    queryset = BookInfo.objects.all()  # 指定数据对象查询集

    def get(self, request):
        '''获取所有图书'''
        return self.list(request)

    def post(self, request):
        '''保存图书'''
        return self.create(request)


class BookView(GenericAPIView, RetrieveModelMixin, UpdateModelMixin):
    serializer_class = BookSerializer  # 指定序列化器
    queryset = BookInfo.objects.all()  # 指定数据对象查询集

    def get(self, request, pk):
        '''查询单一图书'''
        return self.retrieve(request, pk)

    def put(self, request, pk):
        '''修改图书'''
        return self.update(request.pk)
    def delete(self, request, pk):
        '''删除图书'''
        return self.destroy(request,pk)

5.6 可用子类视图

CreateAPIView

提供 post 方法

继承自: GenericAPIView、CreateModelMixin

ListAPIView

提供 get 方法

继承自:GenericAPIView、ListModelMixin

RetireveAPIView

提供 get 方法

继承自: GenericAPIView、RetrieveModelMixin

DestoryAPIView

提供 delete 方法

继承自:GenericAPIView、DestoryModelMixin

UpdateAPIView

提供 put 和 patch 方法

继承自:GenericAPIView、UpdateModelMixin

RetrieveUpdateAPIView

提供 get、put、patch方法

继承自: GenericAPIView、RetrieveModelMixin、UpdateModelMixin

RetrieveUpdateDestoryAPIView

提供 get、put、patch、delete方法

继承自:GenericAPIView、RetrieveModelMixin、UpdateModelMixin、DestoryModelMixin

使用举例:

from rest_framework.generics import ListCreateAPIView, RetrieveUpdateDestroyAPIView
from book.models import BookInfo
from book.serializers import BookInfoSerializer


class BooksView(ListCreateAPIView):
    serializer_class = BookSerializer  # 指定序列化器
    queryset = BookInfo.objects.all()  # 指定数据对象查询集


class BookView(RetrieveUpdateDestroyAPIView):
    serializer_class = BookInfoSerializer  # 指定序列化器
    queryset = BookInfo.objects.all()  # 指定数据对象查询集​

使用上面的代码就能完成所有的增删改查逻辑,大大简化了视图层里的代码,提高了开发效率,我们只需花时间写好序列化器里的验证逻辑就好了。

6.视图集

6.1 ViewSet

使用视图集ViewSet,可以将一系列逻辑相关的动作放到一个类中:

  • list() 提供一组数据

  • retrieve() 提供单个数据

  • create() 创建数据

  • update() 保存数据

  • destory() 删除数据

ViewSet视图集类不再实现get()、post()等方法,而是实现动作 action 如 list() 、create() 等。

视图集只在使用as_view()方法的时候,才会将action动作与具体请求方式对应上。如:

class BookInfoViewSet(viewsets.ViewSet):

    def list(self, request):
        ...

    def retrieve(self, request, pk=None):
        ...

在设置路由时,我们可以如下操作

urlpatterns = [
    url(r'^books/$', BookInfoViewSet.as_view({'get':'list'}),
    url(r'^books/(?P<pk>\d+)/$', BookInfoViewSet.as_view({'get': 'retrieve'})
]

action属性

视图集中,我们可以通过action对象属性来获取当前请求视图集时的action动作是哪个。

def get_serializer_class(self):
    if self.action == 'create':
        return OrderCommitSerializer
    else:
        return OrderDataSerializer

6.2 常用视图集父类

ViewSet

继承自APIView,作用也与APIView基本类似,提供了身份认证、权限校验、流量管理等。

在ViewSet中,没有提供任何动作action方法,需要我们自己实现action方法。

GenericViewSet

继承自GenericAPIView,作用也与GenericAPIVIew类似,提供了get_object、get_queryset等方法便于列表视图与详情信息视图的开发。

ModelViewSet

继承自GenericAPIVIew,同时包括了ListModelMixin、RetrieveModelMixin、CreateModelMixin、UpdateModelMixin、DestoryModelMixin。所以所有增删改查功能都具备。

#  路由层
     url(r'^books/$', view_set.BooksModelViewSet.as_view({'get': 'list', 'post': 'create'})),
     url(r'^books/(?P<pk>\d+)/$', view_set.BooksModelViewSet.as_view({'get': 'retrieve','put':'update','delete':'destroy'})),
    
 # 视图层
 class BooksModelViewSet(ModelViewSet):


    serializer_class = BookInfoSerializer
    queryset = BookInfo.objects.all()

ModelViewSet虽好,但有时也要按具体的逻辑考虑,例如注册,只需要保存数据到数据库,没必要把所有功能都暴露出去,也造成资源的浪费。

ReadOnlyModelViewSet

继承自GenericAPIVIew,同时包括了ListModelMixin、RetrieveModelMixin。


6.3 定义附加action

在视图集中,除了上述默认的方法动作外,还可以添加自定义动作。

添加自定义动作需要使用rest_framework.decorators.action装饰器。

以action装饰器装饰的方法名会作为action动作名,与list、retrieve等同。

action装饰器可以接收两个参数:

  • methods: 该action支持的请求方式,列表传递

  • detail: 表示是action中要处理的是否是视图资源的对象(即是否通过url路径获取主键)

    • True 表示使用通过URL获取的主键对应的数据对象

    •   False 表示不使用URL获取主键

6.4 路由Routers

对于视图集ViewSet,我们除了可以自己手动指明请求方式与动作action之间的对应关系外,还可以使用Routers来帮助我们快速实现路由信息。

REST framework提供了两个router

  • SimpleRouter

  • DefaultRouter

使用方法

1) 创建router对象,并注册视图集,例如

from rest_framework import routers

router = routers.SimpleRouter()
router.register(r'books', BookInfoViewSet, base_name='book')

register(prefix, viewset, base_name)

  • prefix 该视图集的路由前缀

  • viewset 视图集

  • base_name 路由名称的前缀

如上述代码会形成的路由如下:

^books/$    name: book-list
^books/{pk}/$   name: book-detail

2)添加路由数据

可以有两种方式:

urlpatterns = [    ...]
urlpatterns += router.urls

urlpatterns = [    ...,    url(r'^', include(router.urls))]

这种方式只会生成视图集扩展类里面定义的方法,对于自定义的方法不能生成。

视图集中包含附加action

导入rest_framework.decorators.action装饰器可解决上面问题。

...
from rest_framework.decorators import action

class BookInfoViewSet(mixins.ListModelMixin, mixins.RetrieveModelMixin, GenericViewSet):
    queryset = BookInfo.objects.all()
    serializer_class = BookInfoSerializer

    @action(methods=['get'], detail=False) #detail = False不生成正则匹配
    def latest(self, request, pk):
        ...

    @action(methods=['put'], detail=True)#detail = True生成正则匹配
    def read(self, request, pk):
        ...

此视图集会形成的路由:

^books/latest/$    name: book-latest
^books/{pk}/read/$  name: book-read

要使用自动生成路由的方法,视图必须继承自视图集。

除了SimpleRouter,还有DefaultRouter,区别在于后者能生成首页,而前者不能。

使用视图集只能处理前端通过request发过来的数据是表单或json数据的类型。

7 其他功能

7.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 权限被禁止

7.2 权限Permissions

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

  • 在执行视图的dispatch()方法前,会先进行视图访问权限的判断

  • 在通过get_object()获取具体对象时,会进行对象访问权限的判断

使用

可以在配置文件中设置默认的权限管理类,如

REST_FRAMEWORK = {
    'DEFAULT_PERMISSION_CLASSES': (
        'rest_framework.permissions.IsAuthenticated', # 授权访问
    )
}

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

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

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

from rest_framework.permissions import IsAuthenticated
from rest_framework.viewsets import ModelViewSet

BooksModelViewSet(ModelViewSet):
    permission_classes = (IsAuthenticated,) #登录授权用户
    ...


如果认证失败,返回如下信息:


提供的权限

  • AllowAny 允许所有用户

  • IsAuthenticated 仅通过认证的用户

  • IsAdminUser 仅管理员用户

  • IsAuthenticatedOrReadOnly 认证的用户可以完全操作,否则只能get读取

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

class BookListView(RetrieveAPIView):
    queryset = BookInfo.objects.all()
    serializer_class = BookInfoSerializer
    authentication_classes = [SessionAuthentication]
    permission_classes = [IsAuthenticated]

7.3 限流Throttling

可以对接口访问的频次进行限制,以减轻服务器压力,主要用于反爬虫

使用

可以在配置文件中,使用DEFAULT_THROTTLE_CLASSESDEFAULT_THROTTLE_RATES进行全局配置,

REST_FRAMEWORK = {
    'DEFAULT_THROTTLE_CLASSES': (
        'rest_framework.throttling.AnonRateThrottle',
        'rest_framework.throttling.UserRateThrottle'
    ),
    'DEFAULT_THROTTLE_RATES': {
        'anon': '4/day', # 匿名用户每天访问4次
        'user': '100/day'  # 登录用户访问100次
    }
}

DEFAULT_THROTTLE_RATES 可以使用 second, minute, hourday来指明周期。

也可以在具体视图中通过throttle_classess属性来配置,如

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

class BookListView(APIView):    throttle_classes = (UserRateThrottle,)
    ...


可选限流类

1) AnonRateThrottle

限制所有匿名未认证用户,使用IP区分用户。

使用DEFAULT_THROTTLE_RATES['anon'] 来设置频次

2)UserRateThrottle

限制认证用户,使用User id 来区分。

使用DEFAULT_THROTTLE_RATES['user'] 来设置频次

3)ScopedRateThrottle

限制用户对于每个视图的访问频次,使用ip或user id。

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

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 BooksView(RetrieveAPIView):
    queryset = BookInfo.objects.all()
    serializer_class = BookInfoSerializer
    authentication_classes = [SessionAuthentication]
    permission_classes = [IsAuthenticated]
    throttle_classes = (UserRateThrottle,)

7.4 过滤Filtering

对于列表数据可能需要根据字段进行过滤,我们可以通过添加django-fitlter扩展来增强支持,实现了ListModelMixin扩展类及子类的视图类才能使用。

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 = BookInfoSerializer
    filter_fields = ('btitle', 'bread')
#视图请求类似如下:
# 127.0.0.1:8000/books/?bread=20


7.5 排序OrderingFilter

对于列表数据,REST framework提供了OrderingFilter过滤器来帮助我们快速指明数据按照指定字段进行排序。同样要实现ListModelMixin扩展类及子类的视图才能使用。

使用

在类视图中设置filter_backends,使用rest_framework.filters.OrderingFilter过滤器,REST framework会在请求的查询字符串参数中检查是否包含了ordering参数,如果包含了ordering参数,则按照ordering参数指明的排序字段对数据集进行排序。

前端可以传递的ordering参数的可选字段值需要在ordering_fields中指明。

class BookListView(ListAPIView):
    queryset = BookInfo.objects.all()
    serializer_class = BookInfoSerializer
    filter_backends = [OrderingFilter]
    ordering_fields = ('id', 'bread', 'bpub_date')

# 127.0.0.1:8000/books/?ordering=-bread # 按阅读量降序查询

7.6 分页Pagination

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

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

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

from rest_framework.pagination import PageNumberPagination
class LargeResultsSetPagination(PageNumberPagination):
    page_size = 5
    page_size_query_param = 'page_size'
    max_page_size = 10
class BookDetailView(RetrieveAPIView):
    queryset = BookInfo.objects.all().orderby('id')
    serializer_class = BookInfoSerializer
    pagination_class = LargeResultsSetPagination

注意:如果在视图内关闭分页功能,只需在视图内设置

pagination_class = None

可选分页器

1) PageNumberPagination

前端访问网址形式:

GET  http://api.example.org/books/?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_query_param = 'page_size'
    max_page_size = 10

class BookListView(ListAPIView):
    queryset = BookInfo.objects.all().order_by('id')
    serializer_class = BookInfoSerializer
    pagination_class = StandardPageNumberPagination

# 127.0.0.1/books/?page=1&page_size=5  #请求每页会返回5条数据


2)LimitOffsetPagination

前端访问网址形式:

GET http://api.example.org/books/?limit=5&offset=10

可以在子类中定义的属性:

  • 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 BookListView(ListAPIView):
    queryset = BookInfo.objects.all().order_by('id')
    serializer_class = BookInfoSerializer
    pagination_class = LimitOffsetPagination

# 127.0.0.1:8000/books/?offset=3&limit=2

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

    return response

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

REST_FRAMEWORK = {
    'EXCEPTION_HANDLER': 'my_project.my_app.utils.custom_exception_handler'#定义处理异常的路径,以项目实际为准
}

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

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):
            print('[%s]: %s' % (view, exc))
            response = Response({'detail': '服务器内部错误'}, status=status.HTTP_507_INSUFFICIENT_STORAGE)

    return response

REST framework定义的异常

  • APIException 所有异常的父类

  • ParseError 解析错误

  • AuthenticationFailed 认证失败

  • NotAuthenticated 尚未认证

  • PermissionDenied 权限决绝

  • NotFound 未找到

  • MethodNotAllowed 请求方式不支持

  • NotAcceptable 要获取的数据格式不支持

  • Throttled 超过限流次数

  • ValidationError 校验失败