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
settings.py
1
2
3
4
5
6
7
8
9
10
INSTALLED_APPS = [
"django.contrib.admin",
"django.contrib.auth",
"django.contrib.contenttypes",
"django.contrib.sessions",
"django.contrib.messages",
"django.contrib.staticfiles",
"school", # 自己的应用,PEP8 全小写
"rest_framework",
]
  • 装完实测版本: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
    9
    from 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
      6
      StudentSerializer():
      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
    4
    class 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
    16
    class 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
    5
    serializer.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 | 长度: 2
    • serializer.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
    7
    import io

    from rest_framework.parsers import JSONParser
    from rest_framework.renderers import JSONRenderer

    content = JSONRenderer().render(serializer.data)
    data = JSONParser().parse(io.BytesIO(content)) # 变回 dict
    1
    2
    JSONParser().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
      3
      serializer = StudentSerializer(data=data)
      serializer.is_valid() # False 时看 serializer.errors
      serializer.save() # 返回模型对象

      实测:

      1
      2
      is_valid: True | validated_data 类型: dict | grade 是对象吗: True
      save 返回: <Student: zhangxueyou> | 库里: True
      • validated_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
    3
    partial 只给 age: True | 保存后 age: 60 | name 还在: zhangxueyou
    模型上 unique 的字段重名: False | {"name": ["grade with this name already exists."]}
    Student.name 没 unique, 重名照样过: True
    • partial=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"。

视图里的用法

school/views.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
from rest_framework import status
from rest_framework.decorators import api_view
from rest_framework.response import Response

from school.models import Student
from school.serializers import StudentSerializer


@api_view(["GET", "POST"])
def students_list(request, format=None):
if request.method == "GET":
serializer = StudentSerializer(Student.objects.all(), many=True)
return Response(serializer.data)
serializer = StudentSerializer(data=request.data)
if serializer.is_valid():
serializer.save()
return Response(serializer.data, status=status.HTTP_201_CREATED)
return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)
  • 实测这条链路的返回:

    1
    2
    3
    JSON 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 BytesIO ModuleNotFoundError: No module named 'django.utils.six' 用 io.BytesIO
    Student.create(...) AttributeError Student.objects.create(...)
    对解析出来的 dict 调 .save() AttributeError: 'dict' object has no attribute 'save' Serializer(data=...).save()
    没 is_valid() 就读 .errors AssertionError: 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 或 UniqueConstraint
    Meta.fields 写了不存在的名字 ImproperlyConfigured: Field name 'student_count' is not valid for model 'Grade' 动态字段用 SerializerMethodField 声明出来
    超链接序列化器不带 context AssertionError ... requires the request in the serializer context Serializer(obj, context={"request": request})
    用 JsonResponse 返回 list TypeError: ... set the safe parameter to False 用 Response,或 JsonResponse(..., safe=False)

参考

本文结束 感谢您的阅读
正在加载今日诗词....