Skip to main content

序列化Django对象

Django的序列化框架提供了一种将Django模型“翻译”成其他格式的机制。通常这些其他格式将是基于文本的,并用于通过有线发送Django数据,但是序列化器可以处理任何格式(基于文本或不是)。

参见

如果你只是想从表中得到一些序列化形式的数据,你可以使用 dumpdata 管理命令。

序列化数据

在最高级别,串行化数据是一个非常简单的操作:

from django.core import serializers
data = serializers.serialize("xml", SomeModel.objects.all())

serialize 函数的参数是将数据序列化(见 Serialization formats)的格式和要序列化的 QuerySet。 (实际上,第二个参数可以是任何产生Django模型实例的迭代器,但它几乎总是一个QuerySet)。

django.core.serializers.get_serializer(format)

您也可以直接使用序列化对象:

XMLSerializer = serializers.get_serializer("xml")
xml_serializer = XMLSerializer()
xml_serializer.serialize(queryset)
data = xml_serializer.getvalue()

如果要将数据直接序列化为类文件对象(其中包括 HttpResponse),这将非常有用,:

with open("file.xml", "w") as out:
    xml_serializer.serialize(SomeModel.objects.all(), stream=out)

注解

调用具有未知 格式get_serializer() 将引发 django.core.serializers.SerializerDoesNotExist 异常。

字段子集

如果只想要序列化一部分字段,可以为序列化程序指定一个 fields 参数:

from django.core import serializers
data = serializers.serialize('xml', SomeModel.objects.all(), fields=('name','size'))

在这个例子中,只有每个模型的 namesize 属性将被序列化。主键始终序列化为结果输出中的 pk 元素;它从不出现在 fields 部分。

注解

根据您的模型,您可能会发现不能反序列化只序列化其字段子集的模型。如果序列化对象未指定模型所需的所有字段,则解序器将无法保存反序列化的实例。

继承模型

如果您有使用 抽象基类 定义的模型,则不必执行任何特殊操作即可序列化该模型。只需在要序列化的对象(或对象)上调用序列化程序,输出将是序列化对象的完整表示。

然而,如果你有一个使用 多表继承 的模型,你还需要序列化模型的所有基类。这是因为只有在模型上本地定义的字段才会被序列化。例如,考虑以下模型:

class Place(models.Model):
    name = models.CharField(max_length=50)

class Restaurant(Place):
    serves_hot_dogs = models.BooleanField(default=False)

如果你只序列化餐厅模型:

data = serializers.serialize('xml', Restaurant.objects.all())

序列化输出中的字段将只包含 serves_hot_dogs 属性。基类的 name 属性将被忽略。

为了完全序列化您的 Restaurant 实例,您还需要序列化 Place 模型:

all_objects = list(Restaurant.objects.all()) + list(Place.objects.all())
data = serializers.serialize('xml', all_objects)

反序列化数据

反序列化数据也是一个相当简单的操作:

for obj in serializers.deserialize("xml", data):
    do_something_with(obj)

可以看到,deserialize 函数采用与 serialize 相同的格式参数,一个字符串或数据流,并返回一个迭代器。

然而,在这里它有点复杂。 deserialize 迭代器返回的对象是 aren’t 的简单Django对象。相反,它们是包装已创建但未保存的对象和任何关联关系数据的特殊 DeserializedObject 实例。

调用 DeserializedObject.save() 将对象保存到数据库。

注解

如果序列化数据中的 pk 属性不存在或为空,则新实例将保存到数据库。

这确保了反序列化是一种非破坏性操作,即使序列化表示中的数据与数据库中当前的数据不匹配。通常,使用这些 DeserializedObject 实例看起来像:

for deserialized_object in serializers.deserialize("xml", data):
    if object_should_be_saved(deserialized_object):
        deserialized_object.save()

换句话说,通常的用法是检查反序列化的对象,以确保它们是“适当的”用于保存之前这样做。当然,如果你信任你的数据源,你可以保存对象,继续前进。

Django对象本身可以被检查为 deserialized_object.object。如果序列化数据中的字段不存在于模型上,将会产生 DeserializationError,除非将 ignorenonexistent 参数作为 True 传递:

serializers.deserialize("xml", data, ignorenonexistent=True)

序列化格式

Django支持多种序列化格式,其中一些格式要求您安装第三方Python模块:

标识符

信息

xml

序列化到和从一个简单的XML方言。

json

序列化到和从 JSON

yaml

序列化为YAML(YAML不是标记语言)。此序列化程序仅在安装了 PyYAML 时可用。

XML

基本的XML序列化格式很简单:

<?xml version="1.0" encoding="utf-8"?>
<django-objects version="1.0">
    <object pk="123" model="sessions.session">
        <field type="DateTimeField" name="expire_date">2013-01-16T08:16:59.844560+00:00</field>
        <!-- ... -->
    </object>
</django-objects>

序列化或反序列化的对象的整个集合由包含多个 <object> 元素的 <django-objects> 标签表示。每个这样的对象有两个属性:“pk”和“model”,后者由应用程序的名称(“sessions”)和模型的小写名称(“会话”)以点分隔。

对象的每个字段被序列化为运动字段“type”和“name”的 <field> 元素。元素的文本内容表示应存储的值。

外键和其他关系字段的处理有点不同:

<object pk="27" model="auth.permission">
    <!-- ... -->
    <field to="contenttypes.contenttype" name="content_type" rel="ManyToOneRel">9</field>
    <!-- ... -->
</object>

在本示例中,我们指定具有PK 27的auth.Permission对象具有带有PK 9的contenttypes.ContentType实例的外键。

为绑定它们的模型导出ManyToMany关系。例如,auth.User模型与auth.Permission模型有这样的关系:

<object pk="1" model="auth.user">
    <!-- ... -->
    <field to="auth.permission" name="user_permissions" rel="ManyToManyRel">
        <object pk="46"></object>
        <object pk="47"></object>
    </field>
</object>

此示例将给定用户与具有PK 46和47的权限模型链接。

控制字符

Changed in Django 1.9.

如果要序列化的内容包含XML 1.0标准中不接受的控制字符,则序列化将失败,并出现 ValueError 异常。还请阅读W3C对 HTML,XHTML,XML和控制代码 的解释。

JSON

当保持与之前相同的示例数据时,将以下列方式序列化为JSON:

[
    {
        "pk": "4b678b301dfd8a4e0dad910de3ae245b",
        "model": "sessions.session",
        "fields": {
            "expire_date": "2013-01-16T08:16:59.844Z",
            ...
        }
    }
]

这里的格式比使用XML简单一点。整个集合仅表示为数组,对象由具有三个属性的JSON对象表示:“pk”,“model”和“fields”。 “fields”又是一个包含每个字段的名称和值的对象分别作为property和property-value。

外键只是将链接对象的PK作为属性值。 ManyToMany关系被序列化为定义它们的模型,并被表示为PK列表。

请注意,并非所有Django输出都可以未修改地传递给 json。例如,如果在要序列化的对象中有某种自定义类型,则必须为其编写自定义 json 编码器。这样的东西会工作:

from django.utils.encoding import force_text
from django.core.serializers.json import DjangoJSONEncoder

class LazyEncoder(DjangoJSONEncoder):
    def default(self, obj):
        if isinstance(obj, YourCustomType):
            return force_text(obj)
        return super(LazyEncoder, self).default(obj)

还要注意,GeoDjango提供了 定制GeoJSON序列化器

DjangoJSONEncoder

class django.core.serializers.json.DjangoJSONEncoder

JSON序列化程序使用 DjangoJSONEncoder 进行编码。作为 JSONEncoder 的子类,它处理这些附加类型:

datetime

ECMA-262 中定义的 YYYY-MM-DDTHH:mm:ss.sssZYYYY-MM-DDTHH:mm:ss.sss+HH:MM 形式的字符串。

date

ECMA-262 中定义的 YYYY-MM-DD 形式的字符串。

time

ECMA-262 中定义的 HH:MM:ss.sss 形式的字符串。

DecimalPromisedjango.utils.functional.lazy() 对象),UUID

对象的字符串表示形式。

Changed in Django 1.10:

增加了对 Promise 的支持。

YAML

YAML序列化看起来非常类似于JSON。对象列表被序列化为具有键“pk”,“model”和“fields”的序列映射。每个字段再次是一个映射,其中键是字段的名称和值的值:

-   fields: {expire_date: !!timestamp '2013-01-16 08:16:59.844560+00:00'}
    model: sessions.session
    pk: 4b678b301dfd8a4e0dad910de3ae245b

参考字段再次仅由PK或PK序列表示。

自然钥匙

外键和多对多关系的默认序列化策略是序列化关系中对象的主键的值。这个策略适用于大多数对象,但在某些情况下可能会导致困难。

考虑具有引用 ContentType 的外键的对象的列表的情况。如果你要序列化一个引用内容类型的对象,那么你需要有一种方法来引用该内容类型。由于 ContentType 对象在数据库同步过程期间由Django自动创建,所以给定内容类型的主键不容易预测;它将取决于如何和何时执行 migrate。这适用于所有自动生成对象的模型,特别包括 PermissionGroupUser

警告

您不应该在夹具或其他序列化数据中包括自动生成的对象。偶尔,夹具中的主键可能与数据库中的主键匹配,加载夹具将没有效果。在更可能的情况下,它们不匹配,夹具加载将与 IntegrityError 失败。

还有方便的事情。整数id并不总是最方便的引用对象的方法;有时,更自然的参考将是有帮助的。

正是由于这些原因,Django提供了 自然钥匙。自然键是可用于唯一地标识对象实例而不使用主键值的值的元组。

自然键的反序列化

考虑以下两个模型:

from django.db import models

class Person(models.Model):
    first_name = models.CharField(max_length=100)
    last_name = models.CharField(max_length=100)

    birthdate = models.DateField()

    class Meta:
        unique_together = (('first_name', 'last_name'),)

class Book(models.Model):
    name = models.CharField(max_length=100)
    author = models.ForeignKey(Person, on_delete=models.CASCADE)

通常,Book 的序列化数据将使用整数来引用作者。例如,在JSON中,一本书可能被序列化为:

...
{
    "pk": 1,
    "model": "store.book",
    "fields": {
        "name": "Mostly Harmless",
        "author": 42
    }
}
...

这不是一个特别自然的方式来引用作者。它要求你知道作者的主键值;它还要求这个主键值是稳定和可预测的。

然而,如果我们添加自然键处理到人,灯具变得更加人性化。要添加自然密钥处理,请使用 get_by_natural_key() 方法为人定义默认管理器。在Person的情况下,良好的自然键可能是名和姓:

from django.db import models

class PersonManager(models.Manager):
    def get_by_natural_key(self, first_name, last_name):
        return self.get(first_name=first_name, last_name=last_name)

class Person(models.Model):
    objects = PersonManager()

    first_name = models.CharField(max_length=100)
    last_name = models.CharField(max_length=100)

    birthdate = models.DateField()

    class Meta:
        unique_together = (('first_name', 'last_name'),)

现在书可以使用那个自然键来引用 Person 对象:

...
{
    "pk": 1,
    "model": "store.book",
    "fields": {
        "name": "Mostly Harmless",
        "author": ["Douglas", "Adams"]
    }
}
...

当您尝试加载此序列化数据时,Django将使用 get_by_natural_key() 方法将 ["Douglas", "Adams"] 解析为实际 Person 对象的主键。

注解

无论用于自然键的任何字段都必须能够唯一地标识对象。这通常意味着您的模型将有一个唯一性子句(单个字段上的unique = True,或多个字段上的 unique_together)用于自然键中的字段。但是,不需要在数据库级别实施唯一性。如果您确定一组字段将有效地唯一,您仍然可以使用这些字段作为自然键。

没有主键的对象的反序列化将始终检查模型的管理器是否具有 get_by_natural_key() 方法,如果是,则使用它来填充反序列化的对象的主键。

自然键的序列化

那么如何在序列化对象时如何让Django发射一个自然的键呢?首先,你需要添加另一个方法 - 这一次到模型本身:

class Person(models.Model):
    objects = PersonManager()

    first_name = models.CharField(max_length=100)
    last_name = models.CharField(max_length=100)

    birthdate = models.DateField()

    def natural_key(self):
        return (self.first_name, self.last_name)

    class Meta:
        unique_together = (('first_name', 'last_name'),)

该方法应该总是返回一个自然键元组 - 在这个例子中,(first name, last name)。然后,当您调用 serializers.serialize() 时,您提供 use_natural_foreign_keys=Trueuse_natural_primary_keys=True 参数:

>>> serializers.serialize('json', [book1, book2], indent=2,
...      use_natural_foreign_keys=True, use_natural_primary_keys=True)

当指定 use_natural_foreign_keys=True 时,Django将使用 natural_key() 方法将任何外键引用序列化为定义该方法的类型的对象。

当指定 use_natural_primary_keys=True 时,Django不会在此对象的序列化数据中提供主键,因为它可以在反序列化期间计算:

...
{
    "model": "store.person",
    "fields": {
        "first_name": "Douglas",
        "last_name": "Adams",
        "birth_date": "1952-03-11",
    }
}
...

当需要将序列化数据加载到现有数据库中时,这可能非常有用,并且不能保证序列化主键值尚未使用,也不需要确保反序列化对象保留相同的主键。

如果使用 dumpdata 来生成序列化数据,请使用 dumpdata --natural-foreigndumpdata --natural-primary 命令行标志来生成自然密钥。

注解

您不需要同时定义 natural_key()get_by_natural_key()。如果您不希望Django在序列化过程中输出自然键,但是您希望保留加载自然键的能力,那么您可以选择不实现 natural_key() 方法。

相反,如果(由于某种奇怪的原因)你希望Django在序列化期间输出自然键,但 not 能够加载这些键值,只是不要定义 get_by_natural_key() 方法。

序列化期间的依赖关系

由于自然键依赖于数据库查找来解析引用,因此重要的是数据在引用之前存在。您不能使用自然键创建“前向引用” - 您引用的数据必须存在,然后才能包含该数据的自然键引用。

为了适应此限制,使用 dumpdata --natural-foreign 选项的 dumpdata 调用将在序列化标准主键对象之前使用 natural_key() 方法序列化任何模型。

然而,这可能并不总是足够。如果你的自然键引用另一个对象(通过使用外键或自然键对另一个对象作为自然键的一部分),那么你需要能够确保自然键所依赖的对象出现在序列化数据中在自然键之前需要它们。

要控制此排序,您可以定义对 natural_key() 方法的依赖关系。您可以通过在 natural_key() 方法本身上设置 dependencies 属性来实现。

例如,让我们从上面的例子中添加一个自然键到 Book 模型:

class Book(models.Model):
    name = models.CharField(max_length=100)
    author = models.ForeignKey(Person, on_delete=models.CASCADE)

    def natural_key(self):
        return (self.name,) + self.author.natural_key()

Book 的自然键是它的名字和作者的组合。这意味着 Person 必须在 Book 之前序列化。要定义此依赖性,我们添加一行:

def natural_key(self):
    return (self.name,) + self.author.natural_key()
natural_key.dependencies = ['example_app.person']

此定义确保所有 Person 对象在任何 Book 对象之前序列化。反过来,引用 Book 的任何对象将在 PersonBook 已被序列化之后被序列化。