详解 DRF 序列化器

一套 RESTful Web API,最基本的要求就是能为调用该 API 的客户端提供符合要求的数据类型,而能否提供符合要求的数据类型,序列化器是关键。上一节中,我们通过短短 6 行代码,构建了一个序列化器,那么序列化器是如何工作的呢?这一节,我们就带领大家手动构建一个序列化器,并深入介绍序列化器的详细使用方法。

1. 构建序列化器

我们在已有的一个数据库模型类 StudentsInfo:

# models.py

class StudentsInfo(models.Model):
		'''
		学生信息模型
		'''
    s_name = models.CharField(max_length=8, verbose_name='学生姓名') 
    s_age = models.IntegerField(verbose_name='学生年龄')
    s_number = models.CharField(max_length=16, verbose_name='学号')

构建此模型的序列化器,可按如下操作构建:

# serializers.py

from rest_framework import serializers

class StudentsSerializer(serializers.Serializer):
		'''
		学生信息序列化器
		'''
    id = serializers.IntegerField(label='ID', read_only=True)
    s_name = serializers.CharField(label='姓名', max_length=8)
    s_age = serializers.IntegerField(label='年龄', required=True)
    s_number = serializers.CharField(label='学号', max_length=16)

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

2. 常用字段类型与约束参数

常用字段类型

字段 字段构造方式
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(max_length=50, minlength=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页面时,显示的字段帮助提示信息

3. Serializer对象

定义好 Serializer 类后,就可以创建 Serializer 对象了。Serializer 的构造方法为:

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

说明

  • 用于序列化时,将模型类对象传入 instance 参数;

  • 用于反序列化时,将要被反序列化的数据传入 data 参数;

  • 除了 instance 和 data 参数外,在构造 Serializer 对象时,还可通过 context 参数额外添加数据,如:

serializer = AccountSerializer(account, context={'request': request})

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

4. 序列化器使用流程

为了更好理解序列化器的原理,我们通过终端来演示序列化器的使用:

python manage.py shell
  1. 通过查询获取需要序列化的学生对象:
from AppDemo.models import StudentsModel

student = StudentsModel.objects.get(pk=2)
  1. 实例化序列化器,构造序列化器对象:
from AppDemo.serializers import StudentsSerializer

serializer = StudentsSerializer(student)
  1. 获取序列化数据,通过序列化器对象的 data 属性,可以获取序列化后的数据:
serializer.data
# {'id': 1, 's_name': '小明', 's_age': 12, 's_number': '001'}
  1. 如果要被序列化的是包含多条数据的查询集 QuerySet,可以通过添加 many=True 参数实现序列化
student_qs = StudentsModel.objects.all()
serializer = StudentsSerializer(student_qs, many=True)
serializer.data
# [OrderedDict([('id', 1), ('s_name', '小明'), ('s_age', 12), ('s_number', '001')]), OrderedDict([('id', 3), ('s_name', '小王'), ('s_age', 11), ('s_number', '003')]), OrderedDict([('id', 4), ('s_name', '小白'), ('s_age', 10), ('s_number', '004')])]

5.反序列化使用

5.1 数据验证

序列化是将数据库中的数据进行解析,返回前端需要的数据形式(如 json),而前端发来的数据,经过验证和处理,变为数据库需要的数据形式,这个过程称为反序列化。

为了保证数据符合数据模型的要求,对前端发来的数据,根据字段类别、字段限制首先进行验证。在序列化器中,可以调用 is_valid() 方法进行验证,验证成功返回 True,否则返回 False。

# serializers.py

from rest_framework import serializers

class StudentsSerializer(serializers.Serializer):

    id = serializers.IntegerField(label='ID', read_only=True)
    s_name = serializers.CharField(label='姓名', max_length=8)
    s_age = serializers.IntegerField(label='年龄', required=True)
    s_number = serializers.CharField(label='学号', max_length=16)

通过构造序列化器对象,并将要反序列化的数据传递给 data 构造参数,进而进行验证:

from AppDemo.serializers import StudentsSerializer
data = {'s_name': '小黄', 's_age': 15, 's_number': '004'}
serializer = StudentsSerializer(data=data)
serializer.is_valid()  
# 返回True
serializer.errors
# {}
serializer.validated_data  # 验证通过的数据
# OrderedDict([('s_name', '小黄'), ('s_age', 15), ('s_number', '004')])

5.2 数据保存

数据验证通过后,如果需要将验证通过的数据(validated_data)进行存储或更新,需要对序列化器进行改造,增加 create() 和 update() 两个方法来实现:

from rest_framework import serializers
from AppDemo.models import StudentsModel

class StudentsSerializer(serializers.Serializer):

    id = serializers.IntegerField(label='ID', read_only=True)
    s_name = serializers.CharField(label='姓名', max_length=8)
    s_age = serializers.IntegerField(label='年龄', required=True)
    s_number = serializers.CharField(label='学号', max_length=16)

    def create(self, validated_data):
        """存储新数据"""
        return StudentsModel.objects.create(**validated_data)

    def update(self, instance, validated_data):
        """更新,instance为要更新的对象实例"""
        instance.s_name = validated_data.get('s_name', instance.s_name)
        instance.s_age = validated_data.get('s_age', instance.s_age)
        instance.s_number = validated_data.get('s_number', instance.s_number)
        instance.save()
        return instance

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

student = serializer.save()

说明:

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

serializer.save(owner=request.user)

默认序列化器必须传递所有 required 的字段,否则会抛出验证异常。但是我们可以使用 partial 参数来允许部分字段更新:

serializer = CommentSerializer(comment, data={'content': u'foo bar'}, partial=True)

6. 模型类序列化器 ModelSerializer

在上述案例中,我们手动实现了序列化器。在实现的过程中,每一个字段都需要指定,如果模型类中字段很多,那将是一个极其繁琐的过程。能否通过模型中已声明的字段,自动创建序列化器,从而简化操作呢?幸运的是,Django REST framework 为我们提供了 ModelSerializer 模型类序列化器。

ModelSerializer 与常规的 Serializer 相同,不再需要声明每一个字段,它提供了:

  • 基于模型类自动生成一系列字段
  • 包含默认的 create() 和 update() 的实现

6.1 构建模型类序列化器(ModelSerializer)

将上述序列化器改造为模型类序列化器 StudentsSerializer:

# serializers.py

from rest_framework import serializers
from AppDemo.models import StudentsModel

class StudentsSerializer(serializers.ModelSerializer):

    class Meta:
        model = StudentsModel
        fields = '__all__'
  • model 指明与序列化器相对应的数据模型;

  • fields 指明为模型类中要序列化(反序列化)的字段。

我们在终端中可以查看我们构建的模型类序列化器:

python manage.py shell

可以看到,模型类序列化器与我们手动实现的序列化器并无差别,简化的工作,只是 Django REST framework 帮助我们实现了。

from AppDemo.serializers import StudentsSerializer
serializer = StudentsSerializer()
serializer
# StudentsSerializer():
    id = IntegerField(label='ID', read_only=True)
    s_name = CharField(label='学生姓名', max_length=8)
    s_age = IntegerField(label='学生年龄')
    s_number = CharField(label='学号', max_length=16)

6.2 指定字段

  1. 在构建序列化器时,fields 除了可以指定 __all__ 外,还可以选择性地指定需要序列化的字段。
# serializers.py

from rest_framework import serializers
from AppDemo.models import StudentsModel

class StudentsSerializer(serializers.ModelSerializer):

    class Meta:
        model = StudentsModel
        fields = ('id', 's_name', 's_age', 's_number')
  1. 另外,也可以使用 exclude 用来指定哪些字段不需要进行序列化。
class BookInfoSerializer(serializers.ModelSerializer):
    """图书数据序列化器"""
    class Meta:
        model = BookInfo
        exclude = ('image',)
  1. 指明只读字段,有些字段仅需序列化时输出,此时可以通过read_only_fields指明只读字段:
# serializers.py

from rest_framework import serializers
from AppDemo.models import StudentsModel

class StudentsSerializer(serializers.ModelSerializer):

    class Meta:
        model = StudentsModel
        fields = ('id', 's_name', 's_age', 's_number')
        read_only_fields = ('id')

7.小结

本节小节通过手动构建序列化器的方式,带领大家详细了解了序列化器的构建过程和使用流程,并带领大家认识了更为简洁的模型类序列化器。在实际工作中,90% 以上的场景可以直接使用模型类序列化器实现,使用模型类序列化器能够大大减少代码量,让程序更加简洁,同时提高开发效率。