Django REST framework API 指南（9）：序列化

Django REST framework API 指南（1）：請求
Django REST framework API 指南（2）：響應
Django REST framework API 指南（3）：視圖
Django REST framework API 指南（4）：通用視圖
Django REST framework API 指南（5）：視圖集
Django REST framework API 指南（6）：路由
Django REST framework API 指南（7）：解析
Django REST framework API 指南（8）：渲染
Django REST framework API 指南（9）：序列化

官方原文連接

Serializers

序列化器容許將諸如查詢集和模型實例之類的複雜數據轉換爲原生 Python 數據類型，而後能夠將它們輕鬆地呈現爲 JSON，XML 或其餘內容類型。序列化器還提供反序列化，在首次驗證傳入數據以後，能夠將解析的數據轉換回複雜類型。

REST framework 中的序列化類與 Django 的 Form 和 ModelForm 類很是類似。咱們提供了一個 Serializer 類，它提供了一種強大的通用方法來控制響應的輸出，以及一個 ModelSerializer 類，它爲建立處理模型實例和查詢集的序列化提供了有效的快捷方式。

申明序列化類

首先建立一個簡單的對象用於示例：

from datetime import datetime

class Comment(object):
    def __init__(self, email, content, created=None):
        self.email = email
        self.content = content
        self.created = created or datetime.now()

comment = Comment(email='leila@example.com', content='foo bar')
複製代碼

聲明一個序列化類，使用它來序列化和反序列化與 Comment 對象相對應的數據。

聲明一個序列化類看起來很是相似於聲明一個表單：

from rest_framework import serializers

class CommentSerializer(serializers.Serializer):
    email = serializers.EmailField()
    content = serializers.CharField(max_length=200)
    created = serializers.DateTimeField()
複製代碼

序列化對象

如今可使用 CommentSerializer 來序列化評論或評論列表。一樣，使用 Serializer 類看起來很像使用 Form 類。

serializer = CommentSerializer(comment)
serializer.data
# {'email': 'leila@example.com', 'content': 'foo bar', 'created': '2016-01-27T15:17:10.375877'}
複製代碼

此時已經將模型實例轉換爲 Python 原生數據類型。爲了完成序列化過程，將數據渲染爲 json。

from rest_framework.renderers import JSONRenderer

json = JSONRenderer().render(serializer.data)
json
# b'{"email":"leila@example.com","content":"foo bar","created":"2016-01-27T15:17:10.375877"}'
複製代碼

反序列化對象

反序列化是類似的。首先咱們將一個流解析爲 Python 原生數據類型...

from django.utils.six import BytesIO
from rest_framework.parsers import JSONParser

stream = BytesIO(json)
data = JSONParser().parse(stream)
複製代碼

...而後咱們將這些原生數據類型恢復成經過驗證的數據字典。

serializer = CommentSerializer(data=data)
serializer.is_valid()
# True
serializer.validated_data
# {'content': 'foo bar', 'email': 'leila@example.com', 'created': datetime.datetime(2012, 08, 22, 16, 20, 09, 822243)}
複製代碼

保存實例

若是但願可以基於驗證的數據返回完整的對象實例，則須要實現 .create() 和 .update() 方法中的一個或兩個。例如：

class CommentSerializer(serializers.Serializer):
    email = serializers.EmailField()
    content = serializers.CharField(max_length=200)
    created = serializers.DateTimeField()

    def create(self, validated_data):
        return Comment(**validated_data)

    def update(self, instance, validated_data):
        instance.email = validated_data.get('email', instance.email)
        instance.content = validated_data.get('content', instance.content)
        instance.created = validated_data.get('created', instance.created)
        return instance
複製代碼

若是對象實例與 Django 模型相對應，還須要確保這些方法將對象保存到數據庫。若是 Comment 是一個 Django 模型，這些方法可能以下所示：

def create(self, validated_data):
        return Comment.objects.create(**validated_data)

    def update(self, instance, validated_data):
        instance.email = validated_data.get('email', instance.email)
        instance.content = validated_data.get('content', instance.content)
        instance.created = validated_data.get('created', instance.created)
        instance.save()
        return instance
複製代碼

如今，當反序列化數據時，咱們能夠調用 .save() 根據驗證的數據返回一個對象實例。

comment = serializer.save()
複製代碼

調用 .save() 將建立一個新實例或更新現有實例，具體取決於在實例化序列化類時是否傳遞了現有實例：

# .save() will create a new instance.
serializer = CommentSerializer(data=data)

# .save() will update the existing `comment` instance.
serializer = CommentSerializer(comment, data=data)
複製代碼

.create() 和 .update() 方法都是可選的。您能夠都不實現，或者實現其中的一個或兩個，具體取決於你的序列化類的用例。

將附加屬性傳遞給 .save()

有時你會但願你的視圖代碼可以在保存實例的時候注入額外的數據。這些附加數據可能包含當前用戶，當前時間或其餘任何不屬於請求數據的信息。

serializer.save(owner=request.user)
複製代碼

調用 .create() 或 .update() 時，任何其餘關鍵字參數都將包含在 validated_data 參數中。

直接覆蓋 .save()。

在某些狀況下，.create() 和 .update() 方法名稱可能沒有意義。例如，在 「聯繫人表單」 中，咱們可能不會建立新實例，而是發送電子郵件或其餘消息。

在這些狀況下，能夠選擇直接覆蓋 .save()，由於它更具可讀性和有意義性。

舉個栗子：

class ContactForm(serializers.Serializer):
    email = serializers.EmailField()
    message = serializers.CharField()

    def save(self):
        email = self.validated_data['email']
        message = self.validated_data['message']
        send_email(from=email, message=message)
複製代碼

請注意，在上面的狀況下，必須直接訪問 serializer .validated_data 屬性。

驗證

在反序列化數據時，你老是須要在嘗試訪問驗證數據以前調用 is_valid()，或者保存對象實例。若是發生任何驗證錯誤，那麼 .errors 屬性將包含一個表明錯誤消息的字典。例如：

serializer = CommentSerializer(data={'email': 'foobar', 'content': 'baz'})
serializer.is_valid()
# False
serializer.errors
# {'email': [u'Enter a valid e-mail address.'], 'created': [u'This field is required.']}
複製代碼

字典中的每一個鍵都是字段名稱，值是與該字段相對應的錯誤消息（字符串列表）。non_field_errors 鍵也可能存在，並會列出任何常規驗證錯誤。可使用 NON_FIELD_ERRORS_KEY （在 settings 文件中設置）來定製 non_field_errors 關鍵字的名稱。

反序列化 item 列表時，錯誤將做爲表明每一個反序列化 item 的字典列表返回。

數據驗證時拋出異常

.is_valid() 方法帶有一個可選的 raise_exception 標誌，若是存在驗證錯誤，將致使它引起 serializers.ValidationError 異常。

這些異常由 REST framework 提供的默認異常處理程序自動處理，而且默認狀況下將返回 HTTP 400 Bad Request。

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

字段級驗證

你能夠經過向 Serializer 子類添加 .validate_<field_name> 方法來指定自定義字段級驗證。這些與 Django 表單上的 .clean_<field_name> 方法相似。

這些方法只有一個參數，就是須要驗證的字段值。

您的 validate_<field_name> 方法應返回驗證值或引起 serializers.ValidationError。

例如：

from rest_framework import serializers

class BlogPostSerializer(serializers.Serializer):
    title = serializers.CharField(max_length=100)
    content = serializers.CharField()

    def validate_title(self, value):
        """ Check that the blog post is about Django. """
        if 'django' not in value.lower():
            raise serializers.ValidationError("Blog post is not about Django")
        return value
複製代碼

注意：若是你的序列化程序中聲明的 <field_name> 參數爲 required = False ，那麼若是未包含該字段，則不會執行此驗證步驟。

對象級驗證

若是要對多個字段進行其餘的驗證，請將一個名爲 .validate() 的方法添加到您的 Serializer 子類中。這個方法只有一個參數，它是一個字段值（field-value）的字典。若是有必要，它應該引起一個 ValidationError，或者只是返回驗證的值。例如：

from rest_framework import serializers

class EventSerializer(serializers.Serializer):
    description = serializers.CharField(max_length=100)
    start = serializers.DateTimeField()
    finish = serializers.DateTimeField()

    def validate(self, data):
        """ Check that the start is before the stop. """
        if data['start'] > data['finish']:
            raise serializers.ValidationError("finish must occur after start")
        return data
複製代碼

驗證器

序列化器上的各個字段能夠包含驗證器，方法是在字段實例上聲明它們，例如：

def multiple_of_ten(value):
    if value % 10 != 0:
        raise serializers.ValidationError('Not a multiple of ten')

class GameRecord(serializers.Serializer):
    score = IntegerField(validators=[multiple_of_ten])
    ...
複製代碼

序列化類還能夠包含應用於整個字段數據集的可重用驗證器。這些驗證器是經過在內部的 Meta 類中聲明它們來包含的，以下所示：

class EventSerializer(serializers.Serializer):
    name = serializers.CharField()
    room_number = serializers.IntegerField(choices=[101, 102, 103, 201])
    date = serializers.DateField()

    class Meta:
        # Each room only has one event per day.
        validators = UniqueTogetherValidator(
            queryset=Event.objects.all(),
            fields=['room_number', 'date']
        )
複製代碼

看不懂不要緊哦，更多關於驗證的內容，之後還會說到。

訪問初始數據和實例

將初始對象或查詢集傳遞給序列化類實例時，該對象將做爲 .instance 提供。若是沒有傳遞初始對象，則 .instance 屬性將爲 None。

將數據傳遞給序列化類實例時，未修改的數據將做爲 .initial_data 提供。若是 data 關鍵字參數未被傳遞，那麼 .initial_data 屬性將不存在。

部分更新

默認狀況下，序列化程序必須爲全部必填字段傳遞值，不然會引起驗證錯誤。您可使用 partial 參數以容許部分更新。

# Update `comment` with partial data
serializer = CommentSerializer(comment, data={'content': u'foo bar'}, partial=True)
複製代碼

處理嵌套對象

前面的例子適用於處理只具備簡單數據類型的對象，但有時還須要可以表示更復雜的對象，其中對象的某些屬性可能不是簡單的數據類型，如字符串，日期或整數。

Serializer 類自己就是一種 Field，能夠用來表示一個對象類型嵌套在另外一個對象類型中的關係。

class UserSerializer(serializers.Serializer):
    email = serializers.EmailField()
    username = serializers.CharField(max_length=100)

class CommentSerializer(serializers.Serializer):
    user = UserSerializer()
    content = serializers.CharField(max_length=200)
    created = serializers.DateTimeField()
複製代碼

若是嵌套對象能夠是 None 值，則應將 required = False 標誌傳遞給嵌套的序列化類。

class CommentSerializer(serializers.Serializer):
    user = UserSerializer(required=False)  # May be an anonymous user.
    content = serializers.CharField(max_length=200)
    created = serializers.DateTimeField()
複製代碼

一樣，若是嵌套對象是一個列表，則應將 many = True 標誌傳遞給嵌套的序列化類。

class CommentSerializer(serializers.Serializer):
    user = UserSerializer(required=False)
    edits = EditItemSerializer(many=True)  # A nested list of 'edit' items.
    content = serializers.CharField(max_length=200)
    created = serializers.DateTimeField()
複製代碼

可寫嵌套表示

在處理支持反序列化數據的嵌套表示時，嵌套對象的任何錯誤都將嵌套在嵌套對象的字段名稱下。

serializer = CommentSerializer(data={'user': {'email': 'foobar', 'username': 'doe'}, 'content': 'baz'})
serializer.is_valid()
# False
serializer.errors
# {'user': {'email': [u'Enter a valid e-mail address.']}, 'created': [u'This field is required.']}
複製代碼

一樣，.validated_data 屬性將包含嵌套的數據結構。

爲嵌套表示書寫 .create() 方法

若是你支持可寫嵌套表示，則須要編寫處理保存多個對象的 .create() 或 .update() 方法。

如下示例演示如何處理使用嵌套配置文件對象建立用戶。

class UserSerializer(serializers.ModelSerializer):
    profile = ProfileSerializer()

    class Meta:
        model = User
        fields = ('username', 'email', 'profile')

    def create(self, validated_data):
        profile_data = validated_data.pop('profile')
        user = User.objects.create(**validated_data)
        Profile.objects.create(user=user, **profile_data)
        return user
複製代碼

爲嵌套表示書寫 .update() 方法

對於更新，您須要仔細考慮如何處理關係更新。例如，若是關係的數據是 None 或沒有提供，則應發生如下哪一種狀況？

• 在數據庫中將關係設置爲 NULL。
• 刪除關聯的實例。
• 忽略數據並保持原樣。
• 引起驗證錯誤。

如下是咱們之前的 UserSerializer 類中的 .update() 方法的示例。

def update(self, instance, validated_data):
        profile_data = validated_data.pop('profile')
        # Unless the application properly enforces that this field is
        # always set, the follow could raise a `DoesNotExist`, which
        # would need to be handled.
        profile = instance.profile

        instance.username = validated_data.get('username', instance.username)
        instance.email = validated_data.get('email', instance.email)
        instance.save()

        profile.is_premium_member = profile_data.get(
            'is_premium_member',
            profile.is_premium_member
        )
        profile.has_support_contract = profile_data.get(
            'has_support_contract',
            profile.has_support_contract
         )
        profile.save()

        return instance
複製代碼

由於嵌套建立和更新的行爲可能不明確，而且可能須要相關模型之間的複雜依賴關係，因此 REST framework 3 要求你始終明確寫入這些方法。默認的 ModelSerializer 的 .create()和 .update() 方法不包括對可寫嵌套表示的支持。

不過，有第三方軟件包可用，如支持自動可寫嵌套表示的 DRF Writable Nested。

在模型管理器類中保存相關的實例

在序列化類中保存多個相關實例的另外一種方法是編寫自定義模型管理器類。

例如，假設咱們但願確保 User 實例和 Profile 實例始終做爲一對建立。咱們可能會編寫一個相似下面的自定義管理器類：

class UserManager(models.Manager):
    ...

    def create(self, username, email, is_premium_member=False, has_support_contract=False):
        user = User(username=username, email=email)
        user.save()
        profile = Profile(
            user=user,
            is_premium_member=is_premium_member,
            has_support_contract=has_support_contract
        )
        profile.save()
        return user
複製代碼

此管理器類如今更好地封裝了用戶實例和配置文件實例始終在同一時間建立。如今能夠從新編寫序列化類上的 .create()方法，以使用新的管理類方法。

def create(self, validated_data):
    return User.objects.create(
        username=validated_data['username'],
        email=validated_data['email']
        is_premium_member=validated_data['profile']['is_premium_member']
        has_support_contract=validated_data['profile']['has_support_contract']
    )
複製代碼

處理多個對象

Serializer 類還能夠處理序列化或反序列化對象列表。

序列化多個對象

要序列化查詢集或對象列表而不是單個對象實例，在實例化序列化類時，應該傳遞 many=True 標誌。而後，您能夠傳遞要序列化的查詢集或對象列表。

queryset = Book.objects.all()
serializer = BookSerializer(queryset, many=True)
serializer.data
# [
# {'id': 0, 'title': 'The electric kool-aid acid test', 'author': 'Tom Wolfe'},
# {'id': 1, 'title': 'If this is a man', 'author': 'Primo Levi'},
# {'id': 2, 'title': 'The wind-up bird chronicle', 'author': 'Haruki Murakami'}
# ]
複製代碼

反序列化多個對象

反序列化多個對象的默認行爲是支持多個對象建立，但不支持多個對象更新。

包含額外的上下文

除了被序列化的對象外，還有一些狀況須要爲序列化類提供額外的上下文。一種常見的狀況是，若是你使用的是包含超連接關係的序列化類，則須要序列化類訪問當前請求，以便它能夠正確生成徹底限定的URL。

在實例化序列化對象時，你能夠經過傳遞上下文參數來提供任意附加上下文。例如：

serializer = AccountSerializer(account, context={'request': request})
serializer.data
# {'id': 6, 'owner': u'denvercoder9', 'created': datetime.datetime(2013, 2, 12, 09, 44, 56, 678870), 'details': 'http://example.com/accounts/6/details'}
複製代碼

經過訪問 self.context 屬性，能夠在任何序列化對象字段邏輯中使用上下文字典，例如自定義的 .to_representation() 方法。

ModelSerializer

一般你會想要序列化類緊密地映射到 Django 模型定義上。

ModelSerializer 類提供了一個快捷方式，可以讓你自動建立一個 Serializer 類，其中的字段與模型類字段對應。

ModelSerializer 類與常規 Serializer 類相同，不一樣之處在於：

• 它會根據模型自動生成一組字段。
• 它會自動爲序列化類生成驗證器，例如 unique_together 驗證器。
• 它包含 .create() 和 .update() 的簡單默認實現。

聲明ModelSerializer以下所示：

class AccountSerializer(serializers.ModelSerializer):
    class Meta:
        model = Account
        fields = ('id', 'account_name', 'users', 'created')
複製代碼

默認狀況下，該類中的全部模型類字段將被映射爲相應的序列化類字段。

任何關係（如模型上的外鍵）都將映射到 PrimaryKeyRelatedField 。除非在序列化關係文檔中指定，不然默認不包括反向關係。

檢查 ModelSerializer

序列化類可以生成一個表示字符串，可讓你充分檢查其字段的狀態。在使用 ModelSerializer 進行工做時，這是特別有用的，你須要肯定它爲你自動建立了哪些字段和驗證器。

爲此，使用 python manage.py shell 進入 Django shell，而後導入序列化類，實例化它並打印對象表示形式...

>>> from myapp.serializers import AccountSerializer
>>> serializer = AccountSerializer()
>>> print(repr(serializer))
AccountSerializer():
    id = IntegerField(label='ID', read_only=True)
    name = CharField(allow_blank=True, max_length=100, required=False)
    owner = PrimaryKeyRelatedField(queryset=User.objects.all())
複製代碼

指定要包含的字段

若是你只但願在模型序列化程序中使用默認字段的子集，則可使用 fields 或 exclude 選項來完成此操做，就像使用 ModelForm 同樣。強烈建議你顯式使用 fields 屬性序列化的全部字段。這將使你不太可能在模型更改時無心中暴露數據。

舉個栗子：

class AccountSerializer(serializers.ModelSerializer):
    class Meta:
        model = Account
        fields = ('id', 'account_name', 'users', 'created')
複製代碼

你還能夠將 fields 屬性設置爲特殊值 '__all__'，以指示應該使用模型中的全部字段。

class AccountSerializer(serializers.ModelSerializer):
    class Meta:
        model = Account
        fields = '__all__'
複製代碼

你能夠將 exclude 屬性設置爲從序列化程序中排除的字段列表。

class AccountSerializer(serializers.ModelSerializer):
    class Meta:
        model = Account
        exclude = ('users',)
複製代碼

在上面的示例中，若是 Account 模型有3個字段 account_name，users 和 created，則會致使字段 account_name 和 created 被序列化。

fields 和 exclude 屬性中的名稱一般映射到模型類的模型字段。

或者fields選項中的名稱能夠映射成屬性或方法。而不會變成模型類中的參數。

從版本 3.3.0 開始，必須提供其中一個屬性 fields 或 exclude。

指定嵌套序列化

默認的 ModelSerializer 使用主鍵進行關聯，但你也可使用 depth 選項輕鬆生成嵌套表示（自關聯）：

class AccountSerializer(serializers.ModelSerializer):
    class Meta:
        model = Account
        fields = ('id', 'account_name', 'users', 'created')
        depth = 1
複製代碼

depth 選項應設置爲一個整數值，該值指示在還原爲平面表示以前應該遍歷的關聯的深度。

若是你想自定義序列化的方式，你須要本身定義字段。

顯式指定字段

你能夠將額外的字段添加到 ModelSerializer，或者經過在類上聲明字段來覆蓋默認字段，就像你對 Serializer 類所作的那樣。

class AccountSerializer(serializers.ModelSerializer):
    url = serializers.CharField(source='get_absolute_url', read_only=True)
    groups = serializers.PrimaryKeyRelatedField(many=True)

    class Meta:
        model = Account
複製代碼

額外的字段能夠對應於模型上的任何屬性或可調用的字段。

指定只讀字段

你可能但願將多個字段指定爲只讀。不要顯式給每一個字段添加 read_only = True屬性，你可使用快捷方式 Meta 選項 read_only_fields 。

該選項應該是字段名稱的列表或元組，聲明以下：

class AccountSerializer(serializers.ModelSerializer):
    class Meta:
        model = Account
        fields = ('id', 'account_name', 'users', 'created')
        read_only_fields = ('account_name',)
複製代碼

含有 editable = False的模型字段，AutoField 字段默認設置爲只讀，而且不須要添加到 read_only_fields 選項。

注意： 有一種特殊狀況，只讀字段是模型級別的 unique_together 約束的一部分。在這種狀況下，序列化類須要驗證約束該字段，但也不能由用戶編輯。

處理這個問題的正確方法是在序列化類中明確指定字段，同時提供 read_only = True 和 default = ... 關鍵字參數。

其中一個例子是與當前認證 User 的只讀關係，它與另外一個標識符是 unique_together 。在這種狀況下，你會像這樣聲明用戶字段：

user = serializers.PrimaryKeyRelatedField(read_only=True, default=serializers.CurrentUserDefault())
複製代碼

關於驗證之後還會再說

其餘關鍵字參數

還有一個快捷方式容許你使用 extra_kwargs 選項在字段上指定任意附加關鍵字參數。與 read_only_fields 的狀況同樣，這意味着你不須要在序列化類中顯式聲明該字段。

該選項是一個字典，將字段名稱映射到關鍵字參數字典。例如：

class CreateUserSerializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = ('email', 'username', 'password')
        extra_kwargs = {'password': {'write_only': True}}

    def create(self, validated_data):
        user = User(
            email=validated_data['email'],
            username=validated_data['username']
        )
        user.set_password(validated_data['password'])
        user.save()
        return user
複製代碼

關係字段

序列化模型實例時，能夠選擇多種不一樣的方式來表示關係。ModelSerializer 的默認表示是使用相關實例的主鍵。

其餘表示形式包括使用超連接序列化，序列化完整嵌套表示形式或使用自定義表示形式序列化。

自定義字段映射

ModelSerializer 類還公開了一個能夠覆蓋的 API，以便在實例化序列化對象時更改序列化對象的字段。

一般，若是 ModelSerializer 沒辦法生成默認須要的字段，那麼你應該將它們明確地添加到類中，或者直接使用常規的Serializer 類。可是，在某些狀況下，你可能須要建立一個新的基類，以定義如何爲給定模型建立序列化對象的字段。

.serializer_field_mapping

Django 模型類到 REST framework 序列化類的映射。你能夠重寫此映射來更改應該用於每一個模型類的默認序列化類。

.serializer_related_field

該屬性應該是序列化器字段類，默認狀況下用於關係字段。

對於 ModelSerializer，它默認爲 PrimaryKeyRelatedField。

對於 HyperlinkedModelSerializer，它默認爲 serializers.HyperlinkedRelatedField。

serializer_url_field

序列化器字段類，應該用於序列化類中的任何 url 字段。

默認是 serializers.HyperlinkedIdentityField 。

serializer_choice_field

序列化器字段類，應該用於序列化程序中的任何選擇字段。

默認是 serializers.ChoiceField。

field_class 和 field_kwargs API

調用如下方法來肯定應該自動包含在序列化程序中的每一個字段的類和關鍵字參數。這些方法都應返回兩個元組 (field_class, field_kwargs)。

.build_standard_field(self, field_name, model_field)

調用以生成映射到標準模型字段的序列化器字段。

默認實現基於 serializer_field_mapping 屬性返回序列化類。

.build_relational_field(self, field_name, relation_info)

調用以生成映射到關係模型字段的序列化器字段。

默認實現基於 serializer_relational_field 屬性返回一個序列化類。

relation_info 參數是一個命名元組，它包含 model_field，related_model，to_many和 has_through_model 屬性。

.build_nested_field(self, field_name, relation_info, nested_depth)

當 depth 選項已設置時，調用以生成映射到關係模型字段的序列化程序字段。

默認實現動態建立一個基於 ModelSerializer 或 HyperlinkedModelSerializer 的嵌套序列化類。

nested_depth 將是 depth 選項的值減 1。

relation_info 參數是一個命名元組，它包含 model_field，related_model，to_many和 has_through_model 屬性。

.build_property_field(self, field_name, model_class)

調用以生成映射到模型類上的屬性或零參數方法的序列化器字段。

默認實現返回一個 ReadOnlyField 類。

.build_url_field(self, field_name, model_class)

被調用來爲序列化器本身的 url 字段生成一個序列化器字段。

默認實現返回一個 HyperlinkedIdentityField 類。

.build_unknown_field(self, field_name, model_class)

當字段名稱未映射到任何模型字段或模型屬性時調用。默認實現會引起錯誤。可是子類能夠自定義這種行爲。

HyperlinkedModelSerializer

HyperlinkedModelSerializer 類與 ModelSerializer 類類似，只不過它使用超連接來表示關係而不是主鍵。

默認狀況下，序列化器將包含一個 url 字段而不是主鍵字段。

url 字段將使用 HyperlinkedIdentityField 序列化器字段來表示，而且模型上的任何關係都將使用 HyperlinkedRelatedField 序列化器字段來表示。

你能夠經過將主鍵添加到 fields 選項來明確包含主鍵，例如：

class AccountSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = Account
        fields = ('url', 'id', 'account_name', 'users', 'created')
複製代碼

絕對和相對 URL

在實例化 HyperlinkedModelSerializer 時，必須在序列化上下文中包含當前請求，例如：

serializer = AccountSerializer(queryset, context={'request': request})
複製代碼

這樣作將確保超連接能夠包含適當的主機名，以便生成徹底限定的 URL，例如：

http://api.example.com/accounts/1/
複製代碼

而不是相對的 URL，例如：

/accounts/1/
複製代碼

若是你確實想要使用相對 URL，則應該在序列化上下文中顯式傳遞 {'request'：None}。

如何肯定超連接視圖

須要肯定哪些視圖應該用於超連接到模型實例。

默認狀況下，超連接預期對應於與樣式 '{model_name}-detail' 匹配的視圖名稱，並經過 pk 關鍵字參數查找實例。

您可使用 extra_kwargs 設置中的 view_name 和 lookup_field 選項覆蓋 URL 字段視圖名稱和查找字段，以下所示：

class AccountSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = Account
        fields = ('account_url', 'account_name', 'users', 'created')
        extra_kwargs = {
            'url': {'view_name': 'accounts', 'lookup_field': 'account_name'},
            'users': {'lookup_field': 'username'}
        }
複製代碼

或者，能夠顯式設置序列化類中的字段。例如：

class AccountSerializer(serializers.HyperlinkedModelSerializer):
    url = serializers.HyperlinkedIdentityField(
        view_name='accounts',
        lookup_field='slug'
    )
    users = serializers.HyperlinkedRelatedField(
        view_name='user-detail',
        lookup_field='username',
        many=True,
        read_only=True
    )

    class Meta:
        model = Account
        fields = ('url', 'account_name', 'users', 'created')
複製代碼

提示：正確地匹配超連接和 URL conf 有時可能有點困難。打印 HyperlinkedModelSerializer 實例的 repr 是一種特別有用的方法，能夠準確檢查這些關係預期映射的 view name 和 lookup field。

更改 URL 字段名稱

URL 字段的名稱默認爲 'url'。可使用 URL_FIELD_NAME （在 settings 文件）全局覆蓋此設置。

ListSerializer

ListSerializer 類提供了一次序列化和驗證多個對象的行爲。你一般不須要直接使用 ListSerializer，而應該在實例化序列化類時簡單地傳遞 many=True。

當一個序列化類被實例化而且 many = True 被傳遞時，一個 ListSerializer 實例將被建立。序列化類成爲父級 ListSerializer 的子級

如下參數也能夠傳遞給 ListSerializer 字段或傳遞了 many = True 的序列化類：

allow_empty

默認狀況下爲 True，但若是要禁止將空列表做爲有效輸入，則可將其設置爲 False。

自定義 ListSerializer 行爲

有幾種狀況可能須要自定義 ListSerializer 行爲。例如：

• 但願提供對列表的特定驗證，例如檢查一個元素是否與列表中的另外一個元素不衝突。
• 想要自定義多個對象的建立或更新行爲。

對於這些狀況，能夠經過使用序列化類的 Meta 類中的 list_serializer_class 選項來修改傳遞了 many=True 時使用的類。

class CustomListSerializer(serializers.ListSerializer):
    ...

class CustomSerializer(serializers.Serializer):
    ...
    class Meta:
        list_serializer_class = CustomListSerializer
複製代碼

自定義多個對象的建立

建立多個對象的默認實現是簡單地爲列表中的每一個 item 調用 .create()。若是要自定義此行爲，則須要在傳遞 many=True時自定義 ListSerializer 類上的 .create()方法。

class BookListSerializer(serializers.ListSerializer):
    def create(self, validated_data):
        books = [Book(**item) for item in validated_data]
        return Book.objects.bulk_create(books)

class BookSerializer(serializers.Serializer):
    ...
    class Meta:
        list_serializer_class = BookListSerializer
複製代碼

自定義多個對象的更新

默認狀況下，ListSerializer 類不支持多對象更新。這是由於插入和刪除預期的行爲是不明確的。

爲了支持多對象更新，你須要重寫 update 方法。在編寫你的多對象更新代碼時，必定要記住如下幾點：

• 如何肯定應該爲數據列表中的每一個 item 更新哪一個實例？
• 插入應該如何處理？它們是無效的，仍是建立新對象？
• 應該如何處理刪除？它們是否暗示了對象刪除，或者刪除了一段關係？它們應該被忽略，仍是無效？
• 如何處理排序？改變兩個 item 的位置是否意味着狀態的改變或者被忽略？

你須要爲實例序列化類添加一個顯式 id 字段。默認的隱式生成的 id 字段被標記爲 read_only。這會致使它在更新時被刪除。一旦你明確聲明它，它將在列表序列化類的更新方法中可用。

下面是你如何選擇實現多對象更新的示例：

class BookListSerializer(serializers.ListSerializer):
    def update(self, instance, validated_data):
        # Maps for id->instance and id->data item.
        book_mapping = {book.id: book for book in instance}
        data_mapping = {item['id']: item for item in validated_data}

        # Perform creations and updates.
        ret = []
        for book_id, data in data_mapping.items():
            book = book_mapping.get(book_id, None)
            if book is None:
                ret.append(self.child.create(data))
            else:
                ret.append(self.child.update(book, data))

        # Perform deletions.
        for book_id, book in book_mapping.items():
            if book_id not in data_mapping:
                book.delete()

        return ret

class BookSerializer(serializers.Serializer):
    # We need to identify elements in the list using their primary key,
    # so use a writable field here, rather than the default which would be read-only.
    id = serializers.IntegerField()
    ...

    class Meta:
        list_serializer_class = BookListSerializer
複製代碼

自定義 ListSerializer 初始化

當具備 many=True的序列化類實例化時，咱們須要肯定哪些參數和關鍵字參數應該傳遞給子級 Serializer類和父級 ListSerializer 類的 .__ init __() 方法。

默認的實現是將全部參數傳遞給兩個類，除了 validators 和任何自定義關鍵字參數，這兩個參數都假定用於子序列化類。

有時你可能須要明確指定在傳遞 many=True 時如何實例化子類和父類。您可使用 many_init 類方法來完成此操做。

 @classmethod
    def many_init(cls, *args, **kwargs):
        # Instantiate the child serializer.
        kwargs['child'] = cls()
        # Instantiate the parent list serializer.
        return CustomListSerializer(*args, **kwargs)
複製代碼

BaseSerializer

BaseSerializer 類能夠用來方便地支持其餘序列化和反序列化風格。

這個類實現了與 Serializer 類相同的基本 API：

• .data - 返回傳出的原始表示。
• .is_valid() - 反序列化並驗證傳入的數據。
• .validated_data - 返回驗證的傳入數據。
• .errors - 在驗證期間返回錯誤。
• .save() - 將驗證的數據保存到對象實例中。

有四種方法能夠被覆蓋，這取決於你但願序列化類支持的功能：

• .to_representation() - 重寫此操做以支持序列化，用於讀取操做。
• .to_internal_value() - 重寫此操做以支持反序列化，以用於寫入操做。
• .create() 和 .update() - 覆蓋其中一個或兩個以支持保存實例。

由於這個類提供了與 Serializer 類相同的接口，因此你能夠像現有的常規 Serializer或 ModelSerializer 同樣，將它與基於類的通用視圖一塊兒使用。

惟一不一樣的是，BaseSerializer 類不會在可瀏覽的 API 中生成 HTML 表單。這是由於它們返回的數據不包含全部的字段信息，這些字段信息容許將每一個字段渲染爲合適的 HTML 輸入。

Read-only BaseSerializer 類

要使用 BaseSerializer 類實現只讀序列化類，咱們只需重寫 .to_representation() 方法。讓咱們來看一個使用簡單的 Django 模型的示例：

class HighScore(models.Model):
    created = models.DateTimeField(auto_now_add=True)
    player_name = models.CharField(max_length=10)
    score = models.IntegerField()
複製代碼

建立用於將 HighScore 實例轉換爲基本數據類型的只讀序列化類很是簡單。

class HighScoreSerializer(serializers.BaseSerializer):
    def to_representation(self, obj):
        return {
            'score': obj.score,
            'player_name': obj.player_name
        }
複製代碼

咱們如今可使用這個類來序列化單個 HighScore 實例：

@api_view(['GET'])
def high_score(request, pk):
    instance = HighScore.objects.get(pk=pk)
    serializer = HighScoreSerializer(instance)
    return Response(serializer.data)
複製代碼

或者用它來序列化多個實例：

@api_view(['GET'])
def all_high_scores(request):
    queryset = HighScore.objects.order_by('-score')
    serializer = HighScoreSerializer(queryset, many=True)
    return Response(serializer.data)
複製代碼

Read-write BaseSerializer 類

要建立一個可讀寫的序列化類，咱們首先須要實現一個 .to_internal_value() 方法。此方法返回將用於構造對象實例的驗證值，而且若是提供的數據格式不正確，則可能引起 ValidationError 。

一旦實現 .to_internal_value()，基本驗證 API 將在序列化器中可用，而且你將可以使用 .is_valid()，.validated_data 和 .errors。

若是你還想支持 .save()，則還須要實現 .create() 和 .update()方法中的一個或兩個。

如下是咱們以前的 HighScoreSerializer 的一個完整示例，該示例已更新爲支持讀取和寫入操做。

class HighScoreSerializer(serializers.BaseSerializer):
    def to_internal_value(self, data):
        score = data.get('score')
        player_name = data.get('player_name')

        # Perform the data validation.
        if not score:
            raise ValidationError({
                'score': 'This field is required.'
            })
        if not player_name:
            raise ValidationError({
                'player_name': 'This field is required.'
            })
        if len(player_name) > 10:
            raise ValidationError({
                'player_name': 'May not be more than 10 characters.'
            })

        # Return the validated values. This will be available as
        # the `.validated_data` property.
        return {
            'score': int(score),
            'player_name': player_name
        }

    def to_representation(self, obj):
        return {
            'score': obj.score,
            'player_name': obj.player_name
        }

    def create(self, validated_data):
        return HighScore.objects.create(**validated_data)
複製代碼

建立新的基類

若是你但願實現新的泛型序列化類來處理特定的序列化風格，或者與可選的存儲後端進行集成，那麼 BaseSerializer 類也頗有用。

如下類是能夠處理將任意對象強制轉換爲基本表示形式的泛型序列化類的示例。

class ObjectSerializer(serializers.BaseSerializer):
    """ A read-only serializer that coerces arbitrary complex objects into primitive representations. """
    def to_representation(self, obj):
        for attribute_name in dir(obj):
            attribute = getattr(obj, attribute_name)
            if attribute_name('_'):
                # Ignore private attributes.
                pass
            elif hasattr(attribute, '__call__'):
                # Ignore methods and other callables.
                pass
            elif isinstance(attribute, (str, int, bool, float, type(None))):
                # Primitive types can be passed through unmodified.
                output[attribute_name] = attribute
            elif isinstance(attribute, list):
                # Recursively deal with items in lists.
                output[attribute_name] = [
                    self.to_representation(item) for item in attribute
                ]
            elif isinstance(attribute, dict):
                # Recursively deal with items in dictionaries.
                output[attribute_name] = {
                    str(key): self.to_representation(value)
                    for key, value in attribute.items()
                }
            else:
                # Force anything else to its string representation.
                output[attribute_name] = str(attribute)
複製代碼

Serializer 使用進階

重寫序列化和反序列化行爲

若是你須要更改序列化類的序列化或反序列化行爲，能夠經過覆蓋 .to_representation() 或 .to_internal_value() 方法來實現。

如下緣由可能須要重寫這兩個方法...

• 爲新的序列化基類添加新行爲。
• 稍微修改現有類的行爲。
• 提升常常訪問的 API 端點的序列化性能，以便返回大量數據。

這些方法的簽名以下：

.to_representation(self, obj)

接受須要序列化的對象實例，並返回一個原始表示。一般這意味着返回一個內置 Python 數據類型的結構。能夠處理的確切類型取決於您爲 API 配置的渲染類。

可能會被重寫以便修改表示風格。例如：

def to_representation(self, instance):
    """Convert `username` to lowercase."""
    ret = super().to_representation(instance)
    ret['username'] = ret['username'].lower()
    return ret
複製代碼

.to_internal_value(self, data)

將未驗證的傳入數據做爲輸入，並應返回將做爲 serializer.validated_data 提供的驗證數據。若是在序列化類上調用了 .save() ，則返回值也將傳遞給 .create() 或 .update() 方法。

若是驗證失敗，則該方法會引起 serializers.ValidationError(errors)。errors 參數應該是一個由字段名稱（或 settings.NON_FIELD_ERRORS_KEY）映射到錯誤消息列表的字典。若是不須要改變反序列化行爲，而是想提供對象級驗證，則建議改成覆蓋 .validate()方法。

傳遞給此方法的 data 參數一般是 request.data 的值，所以它提供的數據類型將取決於你爲 API 配置的解析器類。

繼承序列化類

與 Django 表單相似，你能夠經過繼承來擴展和重用序列化類。這使你能夠在父類上聲明一組通用的字段或方法，而後能夠在多個序列化類中使用它們。例如，

class MyBaseSerializer(Serializer):
    my_field = serializers.CharField()

    def validate_my_field(self):
        ...

class MySerializer(MyBaseSerializer):
    ...
複製代碼

與 Django 的 Model 和 ModelForm 類同樣，序列化類中的內部 Meta 類不會從其父類的內部 Meta 類中隱式繼承。若是你想讓 Meta 類繼承父類，必須明確的指出。例如：

class AccountSerializer(MyBaseSerializer):
    class Meta(MyBaseSerializer.Meta):
        model = Account
複製代碼

一般咱們建議不要在內部的 Meta 類中使用繼承，而是顯式聲明全部選項。

動態修改字段

一旦序列化類初始化完畢，就可使用 .fields 屬性訪問在序列化類中設置的字段字典。經過訪問和修改這個屬性能夠達到動態地修改序列化類的目的。

直接修改 fields 參數容許你作一些有趣的事情，好比在運行時改變序列化字段的參數，而不是在聲明序列化類的時候。

舉個栗子：

例如，若是你但願可以設置序列化類在初始化時應使用哪些字段，你能夠建立這樣一個序列化類，以下所示：

class DynamicFieldsModelSerializer(serializers.ModelSerializer):
    """ A ModelSerializer that takes an additional `fields` argument that controls which fields should be displayed. """

    def __init__(self, *args, **kwargs):
        # Don't pass the 'fields' arg up to the superclass
        fields = kwargs.pop('fields', None)

        # Instantiate the superclass normally
        super(DynamicFieldsModelSerializer, self).__init__(*args, **kwargs)

        if fields is not None:
            # Drop any fields that are not specified in the `fields` argument.
            allowed = set(fields)
            existing = set(self.fields)
            for field_name in existing - allowed:
                self.fields.pop(field_name)
複製代碼

這將容許你執行如下操做：

>>> class UserSerializer(DynamicFieldsModelSerializer):
>>>     class Meta:
>>>         model = User
>>>         fields = ('id', 'username', 'email')
>>>
>>> print UserSerializer(user)
{'id': 2, 'username': 'jonwatts', 'email': 'jon@example.com'}
>>>
>>> print UserSerializer(user, fields=('id', 'email'))
{'id': 2, 'email': 'jon@example.com'}
複製代碼