Django-RESTful Api之序列化
这篇讲什么
- 序列化器是 DRF 的门面:往外把模型对象变成 JSON,往里把前端传来的 JSON 校验后变成对象。
- 这篇按「对象 → 数据 → JSON」和「JSON → 数据 → 对象」两个方向各跑一遍,含安装配置、字段怎么写、校验与
create/update、以及在视图里的用法。实测环境 Django 5.2.19 + DRF 3.18.3。
前后端分离与 API
- 前台和后台分开开发,中间靠 API(编程接口) 通信:后端提供数据,前端负责展示。
- 后端要能把数据库里的对象变成 JSON 发出去,也要能把前端传来的 JSON 变成对象存进库——这两个方向就是序列化与反序列化。
- 本篇实测环境:Django 5.2.19 + DRF 3.18.3 )。
安装与配置
1 | pip install djangorestframework |
1 | INSTALLED_APPS = [ |
- 装完实测版本:
rest_framework.VERSION是3.18.3;django-filter 26.2、drf-spectacular 0.30.0是配套要用的(见《Django-RESTful-Api设计风格》《Django-常用插件》)。 - 只装包不写
INSTALLED_APPS也能用序列化器,但可浏览 API 页面和rest_framework.urls的登录入口会缺东西。
序列化器怎么写
-
ModelSerializer:对着模型生成字段school/serializers.py 1
2
3
4
5
6
7
8
9from rest_framework import serializers
from school.models import Student
class StudentSerializer(serializers.ModelSerializer):
class Meta:
model = Student
fields = ("id", "name", "sex", "age", "content", "grade", "owner")-
print(serializer)会把声明出来的字段打一遍,这是最快的自检手段(实测输出):1
2
3
4
5
6StudentSerializer():
id = BigIntegerField(label='ID', read_only=True)
name = CharField(max_length=20)
sex = BooleanField(required=False)
age = IntegerField(max_value=2147483647, min_value=-2147483648, required=False)
content = CharField(allow_blank=True, required=False, ...)- 模型上的
max_length、choices、null/blank都被翻译成了序列化器字段参数;id自动read_only。 required=False来自模型的default/blank,所以「前端必须传哪些字段」不用自己数。
- 模型上的
-
fields也可以写成__all__;不想要的用exclude = ("owner",)。
-
-
Serializer:完全手写的字段serializers.py 1
2
3
4class PlainSerializer(serializers.Serializer):
name = serializers.CharField(max_length=20)
age = serializers.IntegerField(min_value=0)
grade_name = serializers.CharField()-
实测校验消息:
1
2
3类型不对: False {"b": ["A valid integer is required."]}
超长: True {} # 手写的 CharField 不给 max_length 就不限长度(500 字也过)
有 default 的字段可以不给: True {'a': 'hello'}- 两个容易忽略的点:手写的
CharField默认不限长度(max_length要自己写);default=的字段可以缺省。
- 两个容易忽略的点:手写的
-
-
嵌套与计算字段
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16class StudentTinySerializer(serializers.ModelSerializer):
class Meta:
model = Student
fields = ("id", "name")
class GradeNestedSerializer(serializers.ModelSerializer):
students = StudentTinySerializer(many=True, read_only=True)
brief = serializers.SerializerMethodField()
class Meta:
model = Grade
fields = ("id", "name", "students", "brief")
def get_brief(self, obj):
return "班里有 %d 人" % obj.students.count()1
2嵌套输出: {"id": 1, "name": "python01", "students": [{"id": 2, "name": "主人改"}, ...],
"brief": "班里有 26 人"}- 嵌套只读用
many=True, read_only=True;要能写就得自己实现create()/update()。 SerializerMethodField永远只读,方法名必须是get_<字段名>。
- 嵌套只读用
-
运行时改字段(实测)
1
2构造时传 fields: TypeError Field.__init__() got an unexpected keyword argument 'fields'
运行时 pop 掉字段: {"id": 1, "name": "python01", "brief": "班里有 26 人"}fields只能写在Meta里,不能像某些教程写的那样Serializer(obj, fields=(...)),实测直接TypeError。- 想临时去掉字段,实例化之后
serializer.fields.pop("students")。
序列化:对象 → 数据 → JSON
-
在 shell 里逐步跑(实测输出):
1
2
3
4
5serializer.data: {'id': 1, 'name': 'liudehua', 'sex': True, 'age': 50,
'content': 'liudehua shuai', 'grade': 1, 'owner': None}
类型: ReturnDict
JSONRenderer: b'{"id":1,"name":"liudehua","sex":true,"age":50,"content":"liudehua shuai","grade":1,"owner":null}'
many=True: ListSerializer | 长度: 2serializer.data不是普通 dict,而是ReturnDict(DRF 的子类,行为跟 dict 一样);many=True时序列化器实例是ListSerializer,.data是ReturnList。- 外键字段序列化出来是主键数字(
'grade': 1),不是对象;要对象就用嵌套序列化器。
-
老笔记里
Student.create("liudehua", True, 50, ...)这种写法是错的:Student模型上没有create,那是管理器(Student.objects.create(...))的方法。
反序列化:JSON → 数据 → 对象
-
老笔记用
from django.utils.six import BytesIO,这个模块早没了(实测):1
django.utils.six 还在: False | No module named 'django.utils.six'
- 用标准库
io.BytesIO就行。
- 用标准库
-
解析与校验(实测):
1
2
3
4
5
6
7import io
from rest_framework.parsers import JSONParser
from rest_framework.renderers import JSONRenderer
content = JSONRenderer().render(serializer.data)
data = JSONParser().parse(io.BytesIO(content)) # 变回 dict1
2JSONParser().parse: {'id': 1, 'name': 'liudehua', 'sex': True, 'age': 50, ...}
JSONParser 签名: (stream, media_type=None, parser_context=None) -
dict不能.save()(老笔记踩过):1
stu2.save() -> AttributeError: 'dict' object has no attribute 'save'
-
正确做法是把数据交给序列化器再校验保存:
1
2
3serializer = StudentSerializer(data=data)
serializer.is_valid() # False 时看 serializer.errors
serializer.save() # 返回模型对象实测:
1
2is_valid: True | validated_data 类型: dict | grade 是对象吗: True
save 返回: <Student: zhangxueyou> | 库里: Truevalidated_data在 3.18 上是普通dict(老笔记写的是OrderedDict,那是 Python 2 时代的输出);外键已经被还原成模型对象。
-
-
校验失败的原文(实测):
1
2
3
4非法数据 is_valid: False
errors: {"name": ["This field may not be blank."],
"grade": ["Invalid pk \"999999\" - object does not exist."]}
缺必填字段: False {"name": ["This field is required."], "grade": ["This field is required."]}-
没调
is_valid()就读.errors会直接断言失败:1
AssertionError You must call `.is_valid()` before accessing `.errors`.
-
想一步到位用
is_valid(raise_exception=True),它会抛ValidationError,DRF 自动转成 400 响应。
-
-
部分更新与唯一校验(实测):
1
2
3partial 只给 age: True | 保存后 age: 60 | name 还在: zhangxueyou
模型上 unique 的字段重名: False | {"name": ["grade with this name already exists."]}
Student.name 没 unique, 重名照样过: Truepartial=True让必填字段可以缺省,PATCH 就靠它。- 唯一性由模型上的
unique=True决定:ModelSerializer会自动挂UniqueValidator,消息形如「<模型名> with this <字段名> already exists.」;模型没写unique的字段不会帮你查重。
-
超链接序列化器要 context(实测两条报错原文见《Django-RESTful-Api设计风格》):
AssertionError ... requires the request in the serializer context,以及带app_name时的ImproperlyConfigured Could not resolve URL ... "student-detail"。
视图里的用法
1 | from rest_framework import status |
-
实测这条链路的返回:
1
2
3JSON POST: 201 | {'id': 10, 'name': 'putai', 'sex': True, 'age': 20, 'content': '', 'grade': 1, 'owner': None}
PUT JSON: 200 | {'id': 8, 'name': '改名', ...}
表单 POST: 201 -
老笔记用
JsonResponse(serializer.data)返回,能跑,但有两个问题:不能协商表现层(永远 JSON),也用不上 DRF 的异常处理。要么用Response,要么至少写JsonResponse(..., safe=False)(实测直接传列表会TypeError: In order to allow non-dict objects to be serialized set the safe parameter to False.,见《Django-视图》)。 -
老笔记那段
JSONRenderer().render(request.POST)再JSONParser().parse(...)的绕圈是多余的:request.data已经是解析好的字典。
新手卡点清单
-
都是实测踩过的:
卡点 症状(实测原文) 正确做法 from django.utils.six import BytesIOModuleNotFoundError: No module named 'django.utils.six'用 io.BytesIOStudent.create(...)AttributeErrorStudent.objects.create(...)对解析出来的 dict 调 .save()AttributeError: 'dict' object has no attribute 'save'Serializer(data=...).save()没 is_valid()就读.errorsAssertionError: You must call .is_valid() before accessing .errors.先 is_valid(),或用raise_exception=True构造时传 fields=(...)TypeError: Field.__init__() got an unexpected keyword argument 'fields'写在 Meta里,或运行时serializer.fields.pop(...)手写 CharField以为限长500 字照样通过 显式 max_length=20以为 DRF 会帮你查重 模型没 unique的字段照插模型加 unique或UniqueConstraintMeta.fields写了不存在的名字ImproperlyConfigured: Field name 'student_count' is not valid for model 'Grade'动态字段用 SerializerMethodField声明出来超链接序列化器不带 context AssertionError ... requires the request in the serializer contextSerializer(obj, context={"request": request})用 JsonResponse返回 listTypeError: ... set the safe parameter to False用 Response,或JsonResponse(..., safe=False)
参考
- Django REST framework:Serializers:
ModelSerializer/Serializer/SerializerMethodField与Meta选项。 - Django REST framework:Fields:字段参数(
max_length、default、required、read_only)。 - Django REST framework:Parsers:
JSONParser等请求体解析器。 - Django REST framework:Renderers:
JSONRenderer与可浏览 API。 - Django REST framework:Validation:
UniqueValidator与自动校验来源。