DRF 框架總結 - serializer 序列化器
serializer 序列化器
序列化:前端到後端,前端傳送的資料比如說 json 資料,後端轉換成 python 資料型別,才能進行進一步操作;
反序列化:後端到前端,後端要傳給前端的 python 資料要轉換成 json 資料,在進行傳送,這樣前端才能對資料進行識別和操作
前端和後端資料的互相傳輸都可能出現問題,所有對每個資料都有進行驗證,如果向 Flask 中那樣自己寫驗證,會顯得很麻煩,所以 Django 中就會有了序列化器,將資料轉換和校驗一併完成。
定義 serializer
定義方法
DRF 中的 serializer 使用類來定義,必須繼承自 rest_framework.serializers.Serializer
例如,我們已有了一個數據庫模型類BookInfo
class BookInfo(models.Model):
btitle = models.CharField(max_length=20, verbose_name='名稱')
bpub_date = models.DateField(verbose_name='釋出日期', null=True)
bread = models.IntegerField(default=0, verbose_name='閱讀量')
bcomment = models.IntegerField(default=0, verbose_name= '評論量')
image = models.ImageField(upload_to='booktest', verbose_name='圖片', null=True)
我們想為這個模型類提供一個序列化器,可以定義如下:
class BookInfoSerializer(serializers.Serializer):
"""圖書資料序列化器"""
id = serializers.IntegerField(label='ID', read_only=True)
btitle = serializers.CharField(label='名稱', max_length= 20)
bpub_date = serializers.DateField(label='釋出日期', required=False)
bread = serializers.IntegerField(label='閱讀量', required=False)
bcomment = serializers.IntegerField(label='評論量', required=False)
image = serializers.ImageField(label='圖片', required=False)
在這裡感覺序列化器好麻煩,一樣的欄位要寫兩遍,很浪費。
不過在專案中就可以體會到序列化器的好處。
欄位與選項
常用欄位型別:
欄位 | 欄位構造方式 |
---|---|
BooleanField | BooleanField() |
NullBooleanField | NullBooleanField() |
CharField | CharField(max_length=None, min_length=None, allow_blank=False, trim_whitespace=True) |
EmailField | EmailField(max_length=None, min_length=None, allow_blank=False) |
RegexField | RegexField(regex, max_length=None, min_length=None, allow_blank=False) |
SlugField | SlugField(maxlength=50, min_length=None, allow_blank=False) 正則欄位,驗證正則模式 [a-zA-Z0-9-]+ |
URLField | URLField(max_length=200, min_length=None, allow_blank=False) |
UUIDField | UUIDField(format=‘hex_verbose’) format: 1) 'hex_verbose' 如"5ce0e9a5-5ffa-654b-cee0-1238041fb31a" 2) 'hex' 如 "5ce0e9a55ffa654bcee01238041fb31a" 3)'int' - 如: "123456789012312313134124512351145145114" 4)'urn' 如: "urn:uuid:5ce0e9a5-5ffa-654b-cee0-1238041fb31a" |
IPAddressField | IPAddressField(protocol=‘both’, unpack_ipv4=False, **options) |
IntegerField | IntegerField(max_value=None, min_value=None) |
FloatField | FloatField(max_value=None, min_value=None) |
DecimalField | DecimalField(max_digits, decimal_places, coerce_to_string=None, max_value=None, min_value=None) max_digits: 最多位數 decimal_palces: 小數點位置 |
DateTimeField | DateTimeField(format=api_settings.DATETIME_FORMAT, input_formats=None) |
DateField | DateField(format=api_settings.DATE_FORMAT, input_formats=None) |
TimeField | TimeField(format=api_settings.TIME_FORMAT, input_formats=None) |
DurationField | DurationField() |
ChoiceField | ChoiceField(choices) choices與Django的用法相同 |
MultipleChoiceField | MultipleChoiceField(choices) |
FileField | FileField(max_length=None, allow_empty_file=False, use_url=UPLOADED_FILES_USE_URL) |
ImageField | ImageField(max_length=None, allow_empty_file=False, use_url=UPLOADED_FILES_USE_URL) |
ListField | ListField(child=, min_length=None, max_length=None) |
DictField | DictField(child=) |
選項引數:**
引數名稱 | 作用 |
---|---|
max_length | 最大長度 |
min_lenght | 最小長度 |
allow_blank | 是否允許為空 |
trim_whitespace | 是否截斷空白字元 |
max_value | 最小值 |
min_value | 最大值 |
通用引數:
引數名稱 | 說明 |
---|---|
read_only | 表明該欄位僅用於序列化輸出,預設False |
write_only | 表明該欄位僅用於反序列化輸入,預設False |
required | 表明該欄位在反序列化時必須輸入,預設True |
default | 反序列化時使用的預設值 |
allow_null | 表明該欄位是否允許傳入None,預設False |
validators | 該欄位使用的驗證器 |
error_messages | 包含錯誤編號與錯誤資訊的字典 |
label | 用於HTML展示API頁面時,顯示的欄位名稱 |
help_text | 用於HTML展示API頁面時,顯示的欄位幫助提示資訊 |
建立 serializer 物件
定義好Serializer類後,就可以建立Serializer物件了。
Serializer的構造方法為:
Serializer(instance=None, data=empty, **kwarg)
說明:
-
用於序列化時,將模型類物件傳入 instance 引數
-
用於反序列化時,將要被反序列化的資料傳入 data 引數
-
除了 instance 和 data 引數外,在構造 Serializer 物件時,還可通過 context 引數額外新增資料,如
serializer = AccountSerializer(account, context={"request": request})
通過 context 引數附加的資料,可以通過 Serializer 物件的 context 屬性獲取
序列化使用
在 django shell 中來學習序列化器的使用。
python manage.py shell
基本使用
1) 先查詢出一個圖書物件
from booktest.models import BookInfo
book = BookInfo.objects.get(id=2)
2) 構造序列化器物件
from booktest.serializers import BookInfoSerializer
serializer = BookInfoSerializer(book)
3)獲取序列化資料
通過data屬性可以獲取序列化後的資料
serializer.data
# {'id': 2, 'btitle': '天龍八部', 'bpub_date': '1986-07-24', 'bread': 36, 'bcomment': 40, 'image': None}
4)如果要被序列化的是包含多條資料的查詢集QuerySet,可以通過新增many=True引數補充說明
book_qs = BookInfo.objects.all()
serializer = BookInfoSerializer(book_qs, many=True)
serializer.data
關聯欄位,可以採用以下幾種方式:
PrimaryKeyRelatedField
此欄位將被序列化為關聯物件的主鍵。
hbook = serializers.PrimaryKeyRelatedField(label='圖書', read_only=True)
或
hbook = serializers.PrimaryKeyRelatedField(label='圖書', queryset=BookInfo.objects.all())
指明欄位時需要包含read_only=True或者queryset引數:
- 包含read_only=True引數時,該欄位將不能用作反序列化使用
- 包含queryset引數時,將被用作反序列化時引數校驗使用
使用效果:
from booktest.serializers import HeroInfoSerializer
from booktest.models import HeroInfo
hero = HeroInfo.objects.get(id=6)
serializer = HeroInfoSerializer(hero)
serializer.data
# {'id': 6, 'hname': '喬峰', 'hgender': 1, 'hcomment': '降龍十八掌', 'hbook': 2}
StringRelatedField
此欄位將被序列化為關聯物件的字串表示方式(即__str__方法的返回值)
hbook = serializers.StringRelatedField(label='圖書')
HyperlinkedRelatedField
此欄位將被序列化為獲取關聯物件資料的介面連結
hbook = serializers.HyperlinkedRelatedField(label='圖書', read_only=True, view_name='books-detail')
必須指明view_name引數,以便DRF根據檢視名稱尋找路由,進而拼接成完整URL。
SlugRelatedField
此欄位將被序列化為關聯物件的指定欄位資料
hbook = serializers.SlugRelatedField(label='圖書', read_only=True, slug_field='bpub_date')
slug_field指明使用關聯物件的哪個欄位
使用關聯物件的序列化器
這個後面使用比較多
hbook = BookInfoSerializer()
重寫to_representation方法
序列化器的每個欄位實際都是由該欄位型別的to_representation方法決定格式的,可以通過重寫該方法來決定格式。
注意,to_representations方法不僅侷限在控制關聯物件格式上,適用於各個序列化器欄位型別。
自定義一個新的關聯欄位:
class BookRelateField(serializers.RelatedField):
"""自定義用於處理圖書的欄位"""
def to_representation(self, value):
return 'Book: %d %s' % (value.id, value.btitle)
指明hbook為BookRelateField型別
hbook = BookRelateField(read_only=True)
many 引數
如果關聯的物件資料不是隻有一個,而是包含多個數據,此時關聯欄位型別的指明仍可使用上述 幾種方式,只是在宣告關聯欄位時,多補充一個 many=True 引數即可
反序列化使用
驗證
使用序列化器進行反序列化時,需要對資料進行驗證後,才能獲取驗證成功的資料或儲存成模型類物件。
在獲取反序列化的資料前,必須呼叫 is_valid()
放進行驗證,驗證成功返回 True,否則返回 False。
驗證失敗,可以通過序列化器物件的 errors
屬性獲取錯誤資訊,返回字典,包含了欄位和欄位的錯誤。如果是非欄位錯誤,可以通過修改 REST framework
配置中的 NON_FIELD_ERRORE_KEY
來控制錯誤字典中的鍵名。
驗證成功,可以通過序列化器物件的 validated_data
屬性獲取資料。
在定義序列號器時,指明每個欄位的序列化型別和選項引數,本身就是一種驗證行為。
is_valid()
方法還可以在驗證失敗時丟擲異常 serializers.ValidationError
,可以通過傳遞 raise_exception=True
引數開啟,REST framework
接收到此異常,會向前端返回 HTTP 400 Bad Request
響應。
自定義驗證行為,可以使用一下三個方法
驗證單個欄位 validate_<field_name>
可以對指定的 <field_name>
欄位進行單獨驗證
驗證多個欄位 validate
在序列化器中需要同時對多個欄位進行比較驗證時,可以定義 validate
方法來驗證。
在欄位中補充驗證行為 validators
在欄位中新增 validators
選項引數,也可以補充驗證行為:
btitle = serializers.CharField(label='名稱', max_length=20, validators=[about_django])
REST framework提供的validators:
- UniqueValidator 單欄位唯一
- UniqueTogetherValidation 聯合唯一
儲存
如果在驗證成功後,想要基於 validated_data
完成資料物件的建立,可以通過實現 create()
和 update()
兩個方法實現。
實現了上述兩個方法後,在反序列化資料的時候,就可以通過save()方法返回一個數據物件例項了
book = serializer.save()
如果建立序列化器物件的時候,沒有傳遞instance例項,則呼叫save()方法的時候,create()被呼叫,相反,如果傳遞了instance例項,則呼叫save()方法的時候,update()被呼叫。
兩點說明
-
在對序列化器進行 save() 儲存時,可以額外傳遞資料,這個資料可以在 create() 和 update() 的 validated_data 引數獲取到
serializer.save(owner=request.user)
-
預設序列化器必須傳遞所有的 required 的欄位,否則會丟擲驗證異常。但是我們可以使用 partial 引數來執行部分欄位更新
# update comment with partial date serializer = CommentSerializer(comment, data={"content": u'foo bar'}, partial=True)
模型類序列化器 ModelSerializer
如果我們想要使用序列化器對應的是 Django 的模型類,DRF 為我們提供了 ModelSerializer 模型類序列化器來幫助我們快速建立一個 Serailizer 類。
ModelSerializer 與常規的 Serializer 相同,但提供了:
- 基於 模型類自動生成一系列欄位
- 基於模型類自動為 Serializer 生成 validators
- 包含預設的 create() 和 update() 的實現
定義
- model 指明參照哪個模型類
- fields 指明為模型類的哪些欄位生成
指定欄位
- 使用 fields 來明確欄位,
__all__
表名包含所有欄位,也可以寫明具體哪些欄位 - 使用 exclude 可以明確排除掉哪些欄位
- 預設 ModelSerializer 使用主鍵作為關聯欄位,但是我們可以使用 depth 來簡單的生成巢狀表示,depth 應該是整數,表名巢狀的層級數量
- depth 的作用:會自己去通過主鍵找下一級的關聯欄位,可以指定向下找的層級
- 可以通過
read_only_fields
指明只讀欄位,即僅用於序列化輸出的欄位
新增額外引數
我們可以使用 extra_kwargs
引數為 ModelSerializer 新增或修改原有的選項引數
extra_kwargs = {
'bread': {'min_value': 0, 'required': True}},
'bcomment': {'max_value': 0, 'required': True}},
}