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'}