day82 序列化器-Serializer

一、序列化器的基本功能

序列化的基本功能：序列化和反序列化

• 序列化
  • 序列化器把通过orm得到的模型对象转化成字典，提供给视图转化成json数据发送给客户端
• 反序列化
  • 把从客户端发送的数据通过视图调用request以后转化成字典，序列化器可以把字典转换成模型对象
  • 反序列化有数据校验功能（类似form组件）和操作数据库

二、定义序列化器

Django REST framework中的Serializer使用类来定义，须继承自rest_framework.serializers.Serializer。

为了方便演示，新创建一个子应用：sers，使用的数据模型还是Student.model内的学生模型

为模型提供序列化器，我们通常为其命名与模型相关，且把序列化器代码保存到当前应用下的serializers.py中

from rest_framework import serializers
# Serializer基础序列化器，
# ModelSerializer 模型类序列化器，是基础序列化器的子类
class StudentSerializer(serializers.Serializer):
    """学生信息序列化器"""
    # 1. 字段声明
    # 注意：
        # 1. 把需要提供给客户端的字段才写进来，或者需要客户端提供的字段才写进
        # 2. =号左边的字段一定要和模型里面的字段名对应
        # 3. 序列化器声明的字段并非一定要在数据库中的，也可以是模型声明的属性方法
    id = serializers.IntegerField()
    name = serializers.CharField()
    age = serializers.IntegerField()
    sex = serializers.BooleanField()
    # description = serializers.CharField() # TextField是数据才有的，前端没有这种说法

    # 2. 如果使用的模型类序列化器，则需要继续的模型信息

    # 3. 验证数据的相关代码

    # 4. 保存数据到数据库中的代码

常用字段类型：

字段	字段构造方式
BooleanField	BooleanField()
NullBooleanField	NullBooleanField()
CharField	CharField(max_length=None, min_length=None, allow_blank=False, trim_whitespace=True)
EmailField	EmailField(max_length=None, min_length=None, allow_blank=False)
RegexField	RegexField(regex, max_length=None, min_length=None, allow_blank=False)
SlugField	SlugField(maxlength=50, min_length=None, allow_blank=False) 正则字段，验证正则模式 [a-zA-Z0-9-]+
URLField	URLField(max_length=200, min_length=None, allow_blank=False)
UUIDField	UUIDField(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"
IPAddressField	IPAddressField(protocol='both', unpack_ipv4=False, **options)
IntegerField	IntegerField(max_value=None, min_value=None)
FloatField	FloatField(max_value=None, min_value=None)
DecimalField	DecimalField(max_digits, decimal_places, coerce_to_string=None, max_value=None, min_value=None) max_digits: 最多位数 decimal_palces: 小数点位置
DateTimeField	DateTimeField(format=api_settings.DATETIME_FORMAT, input_formats=None)
DateField	DateField(format=api_settings.DATE_FORMAT, input_formats=None)
TimeField	TimeField(format=api_settings.TIME_FORMAT, input_formats=None)
DurationField	DurationField()
ChoiceField	ChoiceField(choices) choices与Django的用法相同
MultipleChoiceField	MultipleChoiceField(choices)
FileField	FileField(max_length=None, allow_empty_file=False, use_url=UPLOADED_FILES_USE_URL)
ImageField	ImageField(max_length=None, allow_empty_file=False, use_url=UPLOADED_FILES_USE_URL)
ListField	ListField(child=, min_length=None, max_length=None)
DictField	DictField(child=)

选项参数：

参数名称	作用
max_length	最大长度[适用于字符串，列表，文件]
min_lenght	最小长度[适用于字符串，列表，文件]
allow_blank	是否允许数据的值为空，如果使用这个选项，则前端传递过来的数据必须有这个属性。
trim_whitespace	是否截断空白字符
max_value	【数值】最小值
min_value	【数值】最大值

通用参数：

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

三、创建Serializers对象

Serializer的构造方法为：

Serializer(instance=None, data=empty, **kwarg)

参数说明：

• 用于序列化时：把通过orm获取的模型对象转给instance参数
• 用于反序列化时：把要反序列化的数据传给data参数
• 除了这两个还可以在实例化对象的时候，通过context参数添加额外数据

serializer = StudentSerializer(student, context={'request': request},many=False)

通过context参数附加的数据，可以通过Serializer对象的self.context属性获取。

1. 使用序列化器的时候一定要注意，序列化器声明了以后，不会自动执行，需要我们在视图中进行调用才可以。
2. 序列化器无法直接接收客户端的请求数据，需要我们在视图中创建序列化器对象时把使用的数据传递过来。
3. 序列化器的字段声明类似于我们前面使用过的表单系统。
4. 开发restful api时，序列化器会帮我们把模型数据转换成字典.
5. drf提供的视图会帮我们把字典转换成json,或者把客户端发送过来的数据转换字典.

四、序列化器的使用

根据序列化器作用分成两个使用阶段

1. 在客户端发送请求的时候，通过序列化器把接受到的数据反序列化
2. 在服务端响应客户端数据的时候，通过序列化器把要发送的数据序列化

1 序列化

1） 先查询出一个学生对象

视图中获取模型对象，代码：

from students.models import Student

student = Student.objects.get(pk=3)

2） 构造序列化器对象

from .serializers import StudentSerializer

serializer = StudentSerializer(instance=student)

3）获取序列化数据

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

serializer.data
# {'id': 4, 'name': '小张', 'age': 18, 'sex': True, 'description': '猴赛雷'}

完整视图代码：

class Student2APIView(View):
    def get(self,request):
        """返回一个学生信息"""
        # 读取模型对象
        student = Student.objects.get(pk=1)
        # 实例化序列化器
        serializer = StudentSerializer(instance=student)
        print( serializer.data )
        """打印效果：
        {'id': 1, 'name': '张三', 'sex': True, 'age': 18}
        """
        return JsonResponse(serializer.data)

4）如果要被序列化的是包含多条数据的查询集QuerySet，可以通过添加many=True参数补充说明

"""
目前我们先学习序列化器，所以我们还是使用原来django内置的视图类和路由。
使用序列化器对数据进行序列化器，一般用于返回数据给客户端。
"""
from django.views import View
from .serializers import StudentSerializer
from students.models import Student
from django.http.response import JsonResponse
class Student1APIView(View):
    def get(self,request):
        """返回所有学生给客户端"""
        """
        序列化器对象初始化有３个参数:
        1. instance，模型对象或者模型对象组成的列表，用于对数据进行序列化，把模型转换成字典
        2. data，字典，用于对数据进行反序列化，把数据进行验证和保存到数据库
        3. context，字典，用于把路由或者视图的自定义参数传递到序列化器里面使用
                 context将来作为序列化器对象的子属性
        4. many，当序列化器进行序列化时，如果模型有多个，则many必须为True
        """
        student_list = Student.objects.all()
        serializer = StudentSerializer(instance=student_list, many=True)

        print('student_list===>',student_list)
        print('serializer===>', serializer)
        print('转换的结果===>', serializer.data)
        """打印效果：
        [
            OrderedDict([('name', '张三'), ('sex', True), ('age', 18), ('class_null', '3011')]), 
            OrderedDict([('name', '张三'), ('sex', True), ('age', 18), ('class_null', '309')]), 
            OrderedDict([('name', '张三'), ('sex', True), ('age', 18), ('class_null', '309')]), 
            ....    
        ]
        
        说明：
        OrderedDict是python内置的高级数据类型，表示有序字典，因为普通数据类型中的字典是无序的.
        有序字典的成员读取方式，和无序字典一样
        导入路径：
        from collections import OrderedDict
        """

        # jsonResponse的第一个参数如果是列表则必须声明safe=False，否则报错如下：
        # In order to allow non-dict objects to be serialized set the safe parameter to False.
        return JsonResponse(serializer.data, safe=False)

2 反序列化

2.1 数据验证（类比forms组件）

在开发过程中，对数据通常有自己的定义规范，用户传来的数据是不一定规范的，所以要在反序列化之前，通过数据验证判断该数据是否可以反序列化。

而数据验证用到的最重要的方法就是序列化器对象的is_valid()方法，内部对数据进行验证判断，返回布尔值。

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

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

在定义序列化器时，指明每个字段的序列化类型和选项参数，本身就是一种验证行为。

为了方便演示，我们这里采用另一个图书模型来完成反序列化的学习。当然也创建一个新的子应用unsers。

这里由于要提交数据，先把csrf关闭。

models.py

from django.db import models

# Create your models here.
class BookInfo(models.Model):
    """图书信息"""
    title = models.CharField(max_length=20, verbose_name='标题')
    pub_date = models.DateField(verbose_name='发布日期')
    image = models.ImageField(verbose_name='图书封面')
    price = models.DecimalField(max_digits=8, decimal_places=2, verbose_name="价格")
    read = models.IntegerField(verbose_name='阅读量')
    comment = models.IntegerField(verbose_name='评论量')
    class Meta:
        # db_table = "表名"
        db_table = "tb_book_info"
        verbose_name = "图书"
        verbose_name_plural = verbose_name

数据迁移后，我们可以增加图书信息的功能，在此之前必须要验证客户端传来的数据，这里的序列化器的主要作用是反序列化，参考之前学生信息的序列化器代码，在该应用下创建serializers.py

from rest_framework import serializers

class BookInfoSerializer(serializers.Serializer):
    # 这里声明的字段用于进行反序列化器
    # 字段名 = serializers.字段类型(验证选项)
    title = serializers.CharField(max_length=20, label="标题", help_text="标题")
    # required=True 当前字段必填
    pub_date = serializers.DateField(required=True,label="发布日期", help_text="发布日期")
    image = serializers.ImageField(max_length=3*1024*1024, label="图书封面", help_text="图书封面")
    price = serializers.DecimalField(max_digits=8, decimal_places=2, required=True, label="价格", help_text="价格")
    read  = serializers.IntegerField(min_value=0, default=0, label="阅读量", help_text="阅读量")
    comment = serializers.IntegerField(min_value=0, default=0, label="评论量", help_text="评论量")

    # 关于继承数据库选项

    # 验证部分的代码

    # 数据库

在views.py中实例化序列化器对象，把需要反序列化的数据传给data，进行验证

# Create your views here.
from django.views import View
from django.http.response import HttpResponse
from .serializers import BookInfoSerializer
class BookInfoView(View):
    def get(self,request):
        """模拟客户端发送过来的数据"""
        data = {
            "title":"西厢记",
            "pub_date":"1980-10-10",
            "price": 19.80,
            "read": 100,
            "comment": -1,
        }

        # 对上面的数据进行反序列化器处理
        # 1. 初始化，填写data属性
        serializer = BookInfoSerializer(data=data)
        # 2. 调用序列化器提供的is_valid方法进行验证
        # raise_exception=True 表示终断程序，直接抛出错误
        ret = serializer.is_valid(raise_exception=True)
        print(ret) # is_valid的方法值就是验证结果，只会是True/False
        if ret:
            # 3.1 验证通过后，可以通过validated_data得到数据
            print("验证成功，ret=%s" % ret)
            print(serializer.validated_data)  # 验证处理后的数据
            """打印结果：
            OrderedDict([('title', '西厢记'), ('pub_date', datetime.date(1980, 10, 10)), ('price', Decimal('19.80')), ('read', 100), ('comment', 15)])
            """
        else:
            print("验证失败，ret=%s" % ret)
            # 3.1 验证没通过，可以通过
            print( serializer.errors )
            """打印结果：
            {'comment': [ErrorDetail(string='Ensure this value is greater than or equal to 0.', code='min_value')]}
            """
        return HttpResponse("ok")

is_valid()方法还可以在验证失败时抛出异常serializers.ValidationError，可以通过传递raise_exception=True参数开启，REST framework接收到此异常，会向前端返回HTTP 400 Bad Request响应。

# Return a 400 response if the data was invalid.
serializer.is_valid(raise_exception=True)

如果觉得上述验证还不够，还可以补充验证方法，有如下三种

1）validate_字段名

类似于forms组件的局部钩子函数

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

    # 单个字段的验证，方法名必须： validate_<字段名>(self,data)    # data 就是当前字段中客户端提交的数据
    # validate_price 会被is_valid调用
    def validate_price(self, data):
        """"""
        if data < 0:
            raise serializers.ValidationError("对不起，价格不能低于0元")
        # 验证通过以后，必须要返回验证的结果数据，否则序列化器的validated_data无法得到当前字段的结果
        return data

2）validate

类似于forms组件的全局钩子

在序列化器中需要同时对多个字段进行比较验证的时候用到

注意：这里拿到的data是以字典的形式存放所有数据，所以要取自己需要的值

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

    # 多个字段的验证，必须方法名叫 "validate"
    # data 表示客户端发送过来的所有数据，字典格式
    def validate(self, data):
        # 判断图书的阅读量不能低于评论量
        read = data.get("read")
        comment = data.get("comment")
        if read < comment:
            raise serializers.ValidationError("对不起，阅读量不能低于评论量")

        return data

3）validators验证器

验证器类通常是独立的方法，验证方法是类内部的，验证器是类外部的，可以供多个序列化器的所有字段使用

def about_django(data):
    if "django" in data:
        raise serializers.ValidationError("对不起，图书标题不能出现关键字django")
    # 返回验证以后的数据
    return data
    
    
  class BookInfoSerializer(serializers.Serializer):
    # 这里声明的字段用于进行反序列化器
    # 字段名 = serializers.字段类型(验证选项)
    # 因为验证器可以有多个，所以是以列表存储
    title = serializers.CharField(max_length=20,validators=[about_django], label="标题", help_text="标题")
    # required=True 当前字段必填
    pub_date = serializers.DateField(required=True, label="发布日期", help_text="发布日期")
    # max_length 文件的大小
    # allow_null=True 允许传递的image数据为None
    image = serializers.ImageField(required=False, allow_null=True, max_length=3*1024*1024, label="图书封面", help_text="图书封面")
    price = serializers.DecimalField(max_digits=8, decimal_places=2, required=True, label="价格", help_text="价格")
    # min_value 数值大小
    # default 设置默认值
    read  = serializers.IntegerField(min_value=0, default=0, label="阅读量", help_text="阅读量")
    comment = serializers.IntegerField(min_value=0, default=0, label="评论量", help_text="评论量")  

is_valid实际上内部执行了三种不同的验证方式：

1. 先执行了字段内置的验证选项
2. 在执行了validators自定义选项
3. 最后执行了validate自定义验证方法[包含了validate_<字段>, validate]

2.2 数据保存

通过序列化器来完成对数据的新增和更新，可以把原本放在视图函数中的代码移除视图放到序列化器中。

可以通过实现create()和update()两个方法来实现。

class BookInfoSerializer(serializers.Serializer):
	...
        # 数据库操作
    def create(self, validated_data): # 这里会在调用时，由序列化器补充验证成功以后的数据进来
        """完成添加操作"""
        print(validated_data) # 字典
        # 导入模型
        from .models import BookInfo
        # 添加数据
        book = BookInfo.objects.create(
            title=validated_data.get("title"),
            price=validated_data.get("price"),
            pub_date=validated_data.get("pub_date"),
            read=validated_data.get("read"),
            comment=validated_data.get("comment"),
        )

        return book

    # instance就是要修改的模型，系统会自动从对象初始化时的instance提取过来
    # validated_data 就是经过验证以后的客户端提交的数据
    def update(self, instance, validated_data):
        """更新操作"""
        instance.title = validated_data.get('title')
        instance.pub_date = validated_data.get('pub_date')
        instance.comment = validated_data.get('comment')
        instance.price = validated_data.get('price')
        instance.read = validated_data.get('read')
        instance.save()

        return instance

views.py

# Create your views here.
from django.views import View
from django.http.response import HttpResponse
from .serializers import BookInfoSerializer
class BookInfoView(View):
    # ...
    def get(self,request):
        """保存数据[更新]"""
        # 客户端提交数据过来
        id = 2
        data = { # 模拟客户端发送过来的数据
            "title": "东游记",
            "pub_date": "1998-10-01",
            "price": 19.98,
            "read": 330,
            "comment": 100,
        }
        from .models import BookInfo
        book = BookInfo.objects.get(pk=id)

        # 使用序列化器验证数据[如果是更新操作，需要传入2个参数，分别是instance和data]
        serializer = BookInfoSerializer(instance=book,data=data)
        serializer.is_valid()
        book = serializer.save() # 此时，我们必须在序列化器中预先声明update方法
        """
        serailzier对象调用的save方法是什么？怎么做到自动调用update和create?
        1. 这里的save不是数据库ORM模型对象的save，是BaseSerializer定义的。
        2. save方法中根据实例化serializer时是否传入instance参数来判断执行update还是create的
           当传入instance时，则instance.save调用的就是update方法
           没有传入instance，则instance.save调用的就是create方法
        3. serializer.save使用前提是必须在序列化器中声明create或者update方法，否则报错！！！
        """
        print(book)
        """打印结果：
        BookInfo object (2)
        """
        return HttpResponse("ok")

附加参数说明

1） 在对序列化器进行save()保存时，可以额外传递数据，这些数据可以在create()和update()中的validated_data参数获取到

# 可以传递任意参数到数据保存方法中
# 例如：request.user 是django中记录当前登录用户的模型对象
serializer.save(owner=request.user)

2）默认序列化器必须传递所有必填字段[required=True]，否则会抛出验证异常。但是我们可以使用partial参数来允许部分字段更新

# Update `BookInfo` with partial data
# partial=True 设置序列化器只是针对客户端提交的字段进行验证，没有提交的字段，即便有验证选项或方法也不进行验证。
serializer = BookInfoSerializer(book, data=data, partial=True)