寫Django接口沒(méi)碰過(guò)DRF的序列化器幾乎不可能。ModelSerializer是我在DRF里面用得最多的一個(gè)類沒(méi)有之一。它解決的問(wèn)題很直接你手上已經(jīng)有一個(gè)跟數(shù)據(jù)庫(kù)表強(qiáng)相關(guān)的數(shù)據(jù)結(jié)構(gòu)要把它安全地進(jìn)出接口如果是手寫Serializer不僅要把字段聲明重復(fù)一遍還得自己實(shí)現(xiàn)create、update字段一多就全是樣板代碼。ModelSerializer就是干這個(gè)的——通過(guò)一個(gè)Meta類聲明把模型定義直接翻譯成序列化字段。今天這篇文章不打算做成官方文檔的翻譯而是按我自己的理解把ModelSerializer從原理、配置、嵌套、校驗(yàn)到實(shí)戰(zhàn)改造整個(gè)鏈路拆開(kāi)講一遍。無(wú)論你是剛接觸DRF的新手還是已經(jīng)在用但老覺(jué)得某些行為“反直覺(jué)”的老手這篇文章應(yīng)該都能給你一些參考。1. ModelSerializer是什么先搞懂它解決什么問(wèn)題1.1 序列化器在DRF里的角色先理清一個(gè)概念。DRF里的Serializer干的其實(shí)是兩件事把Python對(duì)象變成JSON返回給前端這是序列化把前端傳上來(lái)的JSON校驗(yàn)之后變成Python對(duì)象再落庫(kù)這是反序列化?？此坪?jiǎn)單但圍繞這兩個(gè)動(dòng)作會(huì)牽扯出字段校驗(yàn)、嵌套關(guān)系、只讀只寫、自定義邏輯等一系列問(wèn)題。ModelSerializer是Serializer的子類但它額外做了一件關(guān)鍵的事讀取你定義的模型字段自動(dòng)生成對(duì)應(yīng)的序列化字段。也就是說(shuō)模型的CharField會(huì)變成序列化器的CharField模型的DateTimeField會(huì)變成DateTimeField外鍵會(huì)變成PrimaryKeyRelatedField多對(duì)多字段會(huì)變成帶manyTrue的關(guān)系字段。你不再需要手動(dòng)聲明每個(gè)字段而是告訴它“這個(gè)序列化器針對(duì)哪個(gè)模型”就夠了。1.2 ModelSerializer相比Serializer到底省了什么我用一個(gè)最簡(jiǎn)單的用戶模型舉例。from django.db import models class User(models.Model): username models.CharField(max_length50, uniqueTrue) email models.EmailField(uniqueTrue) password models.CharField(max_length128) avatar models.URLField(blankTrue) is_active models.BooleanField(defaultTrue) created_at models.DateTimeField(auto_now_addTrue)如果手寫Serializer大概是這個(gè)樣子class UserSerializer(serializers.Serializer): id serializers.IntegerField(read_onlyTrue) username serializers.CharField(max_length50) email serializers.EmailField() password serializers.CharField(max_length128, write_onlyTrue) avatar serializers.URLField(requiredFalse) is_active serializers.BooleanField(defaultTrue) created_at serializers.DateTimeField(read_onlyTrue) def create(self, validated_data): return User.objects.create(**validated_data) def update(self, instance, validated_data): instance.username validated_data.get(username, instance.username) instance.email validated_data.get(email, instance.email) instance.password validated_data.get(password, instance.password) instance.avatar validated_data.get(avatar, instance.avatar) instance.is_active validated_data.get(is_active, instance.is_active) instance.save() return instance再看ModelSerializer的寫法class UserSerializer(serializers.ModelSerializer): class Meta: model User fields __all__看見(jiàn)區(qū)別了嗎手寫版本里create、update是必須自己實(shí)現(xiàn)的字段聲明也一個(gè)都不能少模型里加一個(gè)字段Serializer就要同步加一行。ModelSerializer把這些全部自動(dòng)化了默認(rèn)的create就是Model.objects.create(**validated_data)默認(rèn)的update就是逐個(gè)字段更新并save。不過(guò)“自動(dòng)”不總是“正確”后面我會(huì)專門講什么時(shí)候需要覆蓋這兩個(gè)方法。這里只是想說(shuō)明ModelSerializer給你的并不是什么“魔法”而是把常規(guī)邏輯做了默認(rèn)實(shí)現(xiàn)讓你可以把精力放在真正需要定制的地方。對(duì)比項(xiàng)手寫SerializerModelSerializer字段聲明每個(gè)字段手動(dòng)寫從模型自動(dòng)映射create/update手動(dòng)實(shí)現(xiàn)默認(rèn)實(shí)現(xiàn)字段校驗(yàn)規(guī)則手動(dòng)聲明繼承模型約束代碼量多易出錯(cuò)少直觀定制靈活性高高但需要知道覆蓋點(diǎn)1.3 自動(dòng)映射背后的機(jī)制ModelSerializer之所以能自動(dòng)生成字段核心在于它的Metaclass會(huì)遍歷Meta.model的_meta.fields然后通過(guò)一張映射表把模型的Field類型轉(zhuǎn)成序列化器Field類型。比如模型字段序列化器字段CharField / TextFieldCharFieldIntegerFieldIntegerFieldBooleanFieldBooleanFieldDateTimeField / DateFieldDateTimeField / DateFieldForeignKeyPrimaryKeyRelatedFieldManyToManyFieldPrimaryKeyRelatedField(manyTrue)FileField / ImageFieldFileField / ImageField這個(gè)映射不是死板的。模型字段上如果有blankTrue序列化字段的required會(huì)被設(shè)成False如果模型字段有default序列化字段也會(huì)拿到對(duì)應(yīng)的默認(rèn)邏輯如果模型字段有uniqueTrue序列化器還會(huì)在validators里自動(dòng)加上UniqueValidator。換句話說(shuō)模型的約束會(huì)盡可能傳導(dǎo)到序列化層。注意模型的nullTrue主要影響數(shù)據(jù)庫(kù)列是否允許為空序列化器的requiredFalse影響的是輸入校驗(yàn)時(shí)是否必須傳。這倆容易混很多新手在這里踩坑。比如模型中nullTrue是讓你能存NULL但序列化器若不寫requiredFalse前端少傳這個(gè)字段照樣報(bào)錯(cuò)。2. 用對(duì)基礎(chǔ)配置才能少踩坑2.1 fields、exclude和__all__怎么選Meta里的fields是必填的或者用exclude替代再或者用__all__。我見(jiàn)過(guò)不少代碼把fields漏了一啟動(dòng)就報(bào)AssertionError提示你沒(méi)有定義字段。三種寫法的區(qū)別說(shuō)白了一句話你要顯式告訴ModelSerializer哪些字段需要暴露。# 全部暴露省事但不一定安全 class UserSerializer(serializers.ModelSerializer): class Meta: model User fields __all__# 排除敏感字段剩余全要 class UserSerializer(serializers.ModelSerializer): class Meta: model User exclude [password]# 顯式列出字段我最推薦的做法 class UserSerializer(serializers.ModelSerializer): class Meta: model User fields [id, username, email, avatar, is_active, created_at]為什么不推薦無(wú)腦用__all__因?yàn)樗鼤?huì)把所有模型字段都暴露出去password這種字段一旦出現(xiàn)在序列化輸出里就相當(dāng)于把用戶密碼哈希直接丟給前端。就算哈希了也不該出現(xiàn)在接口返回里更別說(shuō)有些模型里還有內(nèi)部狀態(tài)字段、軟刪除標(biāo)記之類的東西。用exclude雖然能排除但它要求你先知道所有需要排除的字段對(duì)后來(lái)接手的人來(lái)說(shuō)可讀性也差。顯式列出字段還有一個(gè)額外的好處字段列表本身就是接口文檔的一部分。別人看你代碼一眼就知道這個(gè)接口返回什么、接收什么不用去模型里數(shù)一遍字段。維護(hù)起來(lái)也直接新增字段需要明確決定“我要不要把它加進(jìn)序列化器”而不是模型一加字段接口就自動(dòng)多出個(gè)返回項(xiàng)。2.2 read_only_fields的邊界在哪里只讀字段在序列化器里是高頻需求。id、created_at這類由系統(tǒng)生成的字段前端不該傳也不能傳就算傳了也應(yīng)當(dāng)被忽略。在ModelSerializer里最省事的寫法是在Meta里指定read_only_fieldsclass UserSerializer(serializers.ModelSerializer): class Meta: model User fields [id, username, email, password, avatar, is_active, created_at] read_only_fields [id, created_at, is_active]這里有個(gè)容易被忽略的細(xì)節(jié)read_only_fields只有在ModelSerializer里才支持手寫Serializer根本不吃這個(gè)配置只能在字段聲明里一個(gè)個(gè)加read_onlyTrue。這個(gè)限制其實(shí)挺合理的因?yàn)镸odelSerializer知道模型字段和序列化字段的對(duì)應(yīng)關(guān)系才能把名字翻譯過(guò)去手寫Serializer的字段聲明是獨(dú)立體系沒(méi)法按模型字段名去匹配。那read_onlyTrue和requiredFalse有什么區(qū)別一個(gè)只讀字段進(jìn)入反序列化流程時(shí)前端就算傳了值也會(huì)被忽略掉所以它天然就是“不必填”的狀態(tài)你不需要再給它加requiredFalse。而requiredFalse只是不強(qiáng)制傳但前端一旦傳了值它就會(huì)參與校驗(yàn)和賦值。提示判斷一個(gè)字段該不該設(shè)只讀我的習(xí)慣是問(wèn)一個(gè)問(wèn)題——這個(gè)值是由服務(wù)端決定還是由客戶端決定由服務(wù)端決定的主鍵、創(chuàng)建時(shí)間、當(dāng)前登錄用戶、后端計(jì)算出來(lái)的狀態(tài)一律read_only。由客戶端決定的標(biāo)題、內(nèi)容、用戶名、郵箱那就在輸入校驗(yàn)里管好。還有一個(gè)不太容易察覺(jué)的坑read_only_fields對(duì)關(guān)聯(lián)字段的名稱解析依賴模型字段名。假如你的模型外鍵叫author但序列化器里有一個(gè)自定義字段叫author_info你把a(bǔ)uthor_info寫進(jìn)read_only_fields是不生效的因?yàn)閍uthor_info不是模型的直接字段。這種自定義字段只能在聲明時(shí)手動(dòng)加read_onlyTrue。2.3 extra_kwargs把約束寫進(jìn)序列化器模型字段的約束會(huì)自動(dòng)映射到序列化字段但這個(gè)映射往往不夠用。比如模型里密碼字段max_length128那是為了兼容哈希結(jié)果的長(zhǎng)度而不是告訴你密碼明文最長(zhǎng)允許128字節(jié)比如某個(gè)字段模型里允許為空但接口上你要求必填再比如你想給某個(gè)字段定制錯(cuò)誤提示文案。這些都需要extra_kwargs出場(chǎng)。class UserSerializer(serializers.ModelSerializer): class Meta: model User fields [id, username, email, password, avatar, is_active, created_at] extra_kwargs { password: { write_only: True, min_length: 8, error_messages: { min_length: 密碼至少需要8位, required: 密碼不能為空, }, }, email: { required: True, error_messages: { required: 郵箱地址不能為空, }, }, }extra_kwargs的鍵是模型字段名值是一個(gè)字典里面可以放任何序列化器Field支持的參數(shù)。write_onlyTrue就是讓這個(gè)字段只在寫入時(shí)校驗(yàn)序列化輸出時(shí)不出現(xiàn)密碼這種字段一定要這樣處理。validators也能通過(guò)extra_kwargs傳進(jìn)去但我得提醒一句validators的用法和min_length這種參數(shù)不太一樣。validators接收的是一個(gè)可調(diào)用對(duì)象的列表它會(huì)追加到序列化字段已有的validators里。如果你傳的是UniqueValidator它還會(huì)因?yàn)樽侄蔚膓ueryset上下文而產(chǎn)生額外的行為這時(shí)候要特別小心queryset是不是被正確傳遞了。extra_kwargs { username: { validators: [ validators.UniqueValidator(querysetUser.objects.all()) ], }, }上面這種寫法容易出問(wèn)題如果你在ModelSerializer里用了這個(gè)DRF會(huì)自動(dòng)檢測(cè)到字段已經(jīng)有唯一性校驗(yàn)并且它自己也會(huì)基于模型生成一個(gè)。結(jié)果就是同一個(gè)字段在接口層被校驗(yàn)兩次第二次數(shù)據(jù)庫(kù)查詢白白多出來(lái)。我的建議是模型上已有的uniqueTrue約束序列化器層不需要你再手動(dòng)加UniqueValidator除非你有特殊的自定義邏輯。2.4 核心配置速查表拿我常用的幾個(gè)配置項(xiàng)整理成一張表方便你寫代碼前對(duì)照。配置項(xiàng)作用使用場(chǎng)景fields指定序列化字段推薦顯式列出exclude排除字段字段多時(shí)用來(lái)快速剔除敏感字段read_only_fields設(shè)置只讀字段主鍵、時(shí)間戳、服務(wù)端生成值extra_kwargs為字段傳額外參數(shù)隱藏密碼、設(shè)置min/max、定制錯(cuò)誤文案depth自動(dòng)展開(kāi)嵌套關(guān)聯(lián)讀取場(chǎng)景下簡(jiǎn)化嵌套序列化model綁定的模型必填項(xiàng)ordering / ordering_fields排序支持列表接口配合filter后端使用3. 嵌套關(guān)聯(lián)字段的幾種正確寫法3.1 默認(rèn)的外鍵映射方式PrimaryKeyRelatedField模型里一旦出現(xiàn)ForeignKey、ManyToManyFieldModelSerializer默認(rèn)映射成PrimaryKeyRelatedField。表現(xiàn)就是序列化輸出時(shí)返回關(guān)聯(lián)對(duì)象的主鍵ID反序列化輸入時(shí)接收一個(gè)主鍵ID。比如下面這個(gè)文章模型class Article(models.Model): title models.CharField(max_length200) content models.TextField() author models.ForeignKey(User, on_deletemodels.CASCADE, related_namearticles) created_at models.DateTimeField(auto_now_addTrue)默認(rèn)的序列化器輸出是這樣的{ id: 1, title: DRF實(shí)戰(zhàn)筆記, content: 正文內(nèi)容, author: 3, created_at: 2024-01-15T10:30:00Z }前端拿到的author只是一個(gè)數(shù)字3。大多數(shù)場(chǎng)景下前端想知道作者叫什么名、頭像是什么還得拿著id再調(diào)一次用戶接口。這就是N1問(wèn)題的接口層版本不僅多一次請(qǐng)求代碼也啰嗦。所以在真實(shí)項(xiàng)目里我很少直接用默認(rèn)外鍵映射作為輸出。常見(jiàn)做法是下面幾種按需求選用。3.2 用SlugRelatedField輸出人類可讀的值如果你希望外鍵在輸出和輸入時(shí)都用某個(gè)業(yè)務(wù)字段代替ID比如用戶名、訂單號(hào)、手機(jī)號(hào)SlugRelatedField是最好的選擇。這里的slug不是說(shuō)URL里的slug而是“作為標(biāo)識(shí)符的某個(gè)字段”。class ArticleSerializer(serializers.ModelSerializer): author serializers.SlugRelatedField( slug_fieldusername, querysetUser.objects.all(), read_onlyTrue, ) class Meta: model Article fields [id, title, content, author, created_at]這樣輸出的author就是用戶名前端拿到直接就能展示。如果還需要read_onlyTrue可以去掉queryset參數(shù)因?yàn)橹蛔x不需要校驗(yàn)輸入的關(guān)聯(lián)是否存在。另一種寫法是用StringRelatedField它直接調(diào)用關(guān)聯(lián)模型__str__的返回值連slug_field都不用指定。缺點(diǎn)是可控性弱__str__一旦改接口輸出就跟著變多個(gè)接口如果對(duì)同一關(guān)聯(lián)字段的展示要求不同這玩意就不太好使。我一般在調(diào)試階段或者對(duì)輸出要求較粗的場(chǎng)景用正式接口更傾向SlugRelatedField或自定義SerializerMethodField。3.3 用嵌套序列化器做完整對(duì)象輸出如果你需要輸出的是關(guān)聯(lián)對(duì)象的完整信息而不是某一個(gè)字段那就直接在當(dāng)前序列化器里引用另一個(gè)序列化器。DRF支持這種嵌套。class UserBriefSerializer(serializers.ModelSerializer): class Meta: model User fields [id, username, avatar] class ArticleSerializer(serializers.ModelSerializer): author UserBriefSerializer(read_onlyTrue) class Meta: model Article fields [id, title, content, author, created_at]注意這里author字段的聲明方式它沒(méi)有被包在Meta里而是作為Serializer的屬性直接定義一個(gè)類變量。此時(shí)ModelSerializer的自動(dòng)映射邏輯會(huì)優(yōu)先使用這個(gè)顯式聲明的字段不會(huì)再把它當(dāng)成PrimaryKeyRelatedField。read_onlyTrue是指這個(gè)嵌套對(duì)象在后端側(cè)生成前端不傳如果前端要傳作者ID來(lái)創(chuàng)建文章這個(gè)字段就要改成PrimaryKeyRelatedField而不是嵌套Serializer。嵌套序列化有個(gè)天然的雙向問(wèn)題如果UserSerializer里又嵌套了ArticleSerializer而ArticleSerializer里又嵌套了UserSerializer就會(huì)形成循環(huán)引用Python直接報(bào)NameError。解決辦法有三個(gè)其中一個(gè)方向不嵌套、使用depth避開(kāi)手寫循環(huán)、或者把其中一個(gè)序列化器定義到另一個(gè)的SerializerMethodField內(nèi)部。我推薦最簡(jiǎn)單的是只做單向嵌套文章看作者、作者詳情里不嵌文章列表接口設(shè)計(jì)本身也更清晰。3.4 depth最省事的嵌套利器也是性能陷阱ModelSerializer支持depth配置比如depth 1它會(huì)自動(dòng)把外鍵展開(kāi)成嵌套對(duì)象不需要你手寫任何嵌套序列化器。class ArticleSerializer(serializers.ModelSerializer): class Meta: model Article fields [id, title, content, author, created_at] depth 1輸出就變成了{(lán) id: 1, title: DRF實(shí)戰(zhàn)筆記, content: 正文內(nèi)容, author: { id: 3, username: 張三, email: zhangsanexample.com }, created_at: 2024-01-15T10:30:00Z }depth默認(rèn)的值是0表示不展開(kāi)。越大展開(kāi)層級(jí)越深。聽(tīng)起來(lái)很省事但有兩個(gè)問(wèn)題必須記住。一是字段不可控。depth1展開(kāi)用戶對(duì)象時(shí)會(huì)把它所有字段都帶出來(lái)包括你可能不想暴露的字段。二是性能隱患。展開(kāi)關(guān)聯(lián)對(duì)象意味著DRF要去查詢關(guān)聯(lián)表數(shù)據(jù)如果沒(méi)有正確的select_related數(shù)據(jù)庫(kù)會(huì)被打爆出現(xiàn)典型的N1查詢。提示我在實(shí)際項(xiàng)目中很少用depth寧可手寫UserBriefSerializer做嵌套。原因很簡(jiǎn)單嵌套序列化器可以精確控制輸出字段、可以按不同接口定制不同的展示層depth雖然快但不好控制。3.5 SerializerMethodField最靈活的展示方式有些字段既不是模型字段也不是普通關(guān)聯(lián)展示而是經(jīng)過(guò)計(jì)算的統(tǒng)計(jì)數(shù)量、拼接字符串、從關(guān)聯(lián)表里取最新一條數(shù)據(jù)。這時(shí)候用SerializerMethodField。class ArticleListSerializer(serializers.ModelSerializer): comment_count serializers.IntegerField(sourcecomments.count, read_onlyTrue) author_name serializers.SerializerMethodField() class Meta: model Article fields [id, title, author_name, comment_count, created_at] def get_author_name(self, obj): return obj.author.username if obj.author else 這里的SerialzerMethodField要和get_字段名方法一一對(duì)應(yīng)。方法接收一個(gè)obj參數(shù)obj是當(dāng)前序列化的模型實(shí)例你在這個(gè)方法里可以任意讀取關(guān)聯(lián)數(shù)據(jù)、做計(jì)算、甚至再讀一次數(shù)據(jù)庫(kù)。用source參數(shù)直接指定字段來(lái)源也是很常見(jiàn)的技巧比如上面的comment_count我直接用sourcecomments.countDRF會(huì)去調(diào)用obj.comments.count()比SerializerMethodField寫起來(lái)還少幾行。但要留意sourcecomments.count每次都會(huì)執(zhí)行一次COUNT查詢?nèi)绻恼铝斜碛?00篇就是100次COUNT性能上要配合查詢優(yōu)化考慮。4. 校驗(yàn)邏輯防止臟數(shù)據(jù)混進(jìn)系統(tǒng)4.1 模型校驗(yàn)與序列化器校驗(yàn)的分工Django模型自帶full_clean校驗(yàn)但DRF默認(rèn)不會(huì)調(diào)用模型的full_clean。這意味著模型層的一些自定義約束例如某個(gè)字段不能等于另一個(gè)字段或者某個(gè)字段需要滿足自定義的條件在序列化器里不會(huì)自動(dòng)生效。理解這個(gè)分工很重要模型校驗(yàn)負(fù)責(zé)數(shù)據(jù)庫(kù)層的合法性序列化器校驗(yàn)負(fù)責(zé)接口層的合法性。你的接口如果只依賴模型校驗(yàn)很多情況下等于沒(méi)有校驗(yàn)。ModelSerializer會(huì)自動(dòng)把模型字段的max_length、null、unique這些聲明映射成序列化器的內(nèi)置校驗(yàn)所以這些約束不用你重復(fù)寫。但是模型里如果用validators寫了自定義校驗(yàn)函數(shù)DRF默認(rèn)也會(huì)把它納入序列化器的validators里。這塊行為在不同版本有些差異所以我建議自定義的復(fù)雜校驗(yàn)不要依賴模型自動(dòng)傳導(dǎo)直接在序列化器里顯式寫行為可控。4.2 單字段校驗(yàn)validate_字段名最簡(jiǎn)單的自定義校驗(yàn)是定義validate_字段名(self, value)方法。它接收一個(gè)參數(shù)就是當(dāng)前字段的值返回校驗(yàn)后的值如果校驗(yàn)不過(guò)就拋serializers.ValidationError。class RegisterSerializer(serializers.ModelSerializer): confirm_password serializers.CharField(write_onlyTrue) class Meta: model User fields [id, username, email, password, confirm_password, created_at] extra_kwargs { password: {write_only: True, min_length: 8}, } def validate_username(self, value): if in value: raise serializers.ValidationError(用戶名不能包含空格) return value這里定義了一個(gè)用戶注冊(cè)場(chǎng)景。confirm_password是額外的寫字段它不屬于模型所以在fields里顯式列出來(lái)ModelSerializer會(huì)自動(dòng)把它聲明為普通CharField。注意這個(gè)字段不會(huì)映射到模型因此創(chuàng)建時(shí)它會(huì)被單獨(dú)提取不進(jìn)入create的validated_data。單字段校驗(yàn)的執(zhí)行順序早于反序列化的整體校驗(yàn)所以在這個(gè)階段你能拿到的是單獨(dú)字段的值不能依賴其他字段。如果你要根據(jù)多個(gè)字段聯(lián)合判斷就要走到下一步。4.3 多字段聯(lián)合校驗(yàn)validate()validate(self, attrs)方法接收的是整個(gè)校驗(yàn)后的字段字典。這里你可以同時(shí)拿到多個(gè)字段的值適合做“兩次密碼一致”、“開(kāi)始時(shí)間早于結(jié)束時(shí)間”這類邏輯。def validate(self, attrs): password attrs.get(password) confirm_password attrs.pop(confirm_password, None) if password ! confirm_password: raise serializers.ValidationError({confirm_password: 兩次輸入的密碼不一致}) return attrs這個(gè)例子演示了一個(gè)重要技巧confirm_password這種校驗(yàn)完就該丟掉的字段在validate里直接pop掉避免它進(jìn)入后面的create流程。如果不pop默認(rèn)的create會(huì)嘗試把它當(dāng)成User模型的字段創(chuàng)建直接報(bào)TypeError。ValidationError可以傳字符串也可以傳字典。傳字典時(shí)錯(cuò)誤信息會(huì)掛到對(duì)應(yīng)字段上前端可以拿到字段級(jí)別的報(bào)錯(cuò)提示傳字符串時(shí)錯(cuò)誤掛在非字段錯(cuò)誤non_field_errors里。我一般建議用字典前端處理起來(lái)更直觀。4.4 validators可復(fù)用的校驗(yàn)函數(shù)如果同一套校驗(yàn)邏輯在多個(gè)序列化器里都要用那就提取成一個(gè)獨(dú)立的函數(shù)或類。def validate_password_strength(value): if not any(char.isdigit() for char in value): raise serializers.ValidationError(密碼必須包含數(shù)字) if not any(char.isalpha() for char in value): raise serializers.ValidationError(密碼必須包含字母) return value class UserSerializer(serializers.ModelSerializer): password serializers.CharField( write_onlyTrue, validators[validate_password_strength], ) class Meta: model User fields [id, username, email, password, created_at]注意這里validators是加在顯式聲明的字段上的。如果你只想通過(guò)extra_kwargs傳也不沖突但可讀性差一些。函數(shù)校驗(yàn)的好處是容易被單元測(cè)試覆蓋而且多個(gè)接口復(fù)用起來(lái)非常順手。實(shí)操心得校驗(yàn)邏輯放序列化器而不是View里。我剛用DRF時(shí)喜歡在View里寫一堆if判斷后來(lái)發(fā)現(xiàn)序列化器報(bào)錯(cuò)信息根本傳不到前端只有400狀態(tài)碼。把校驗(yàn)下沉到序列化器之后錯(cuò)誤數(shù)據(jù)結(jié)構(gòu)統(tǒng)一了、代碼也瘦身了。記住View只負(fù)責(zé)拿數(shù)據(jù)、調(diào)序列化器、返回響應(yīng)業(yè)務(wù)校驗(yàn)一律進(jìn)序列化器。5. 實(shí)戰(zhàn)改造從默認(rèn)序列化器到可用的業(yè)務(wù)代碼5.1 最經(jīng)典的場(chǎng)景注冊(cè)接口的序列化器改造默認(rèn)的ModelSerializer在創(chuàng)建用戶時(shí)存在一個(gè)大坑它會(huì)把明文密碼直接存進(jìn)數(shù)據(jù)庫(kù)而且不經(jīng)過(guò)哈希。這是初學(xué)者非常容易犯的錯(cuò)誤也是實(shí)戰(zhàn)中必須覆蓋create方法的典型場(chǎng)景。import hashlib class RegisterSerializer(serializers.ModelSerializer): confirm_password serializers.CharField(write_onlyTrue) class Meta: model User fields [id, username, email, password, confirm_password, created_at] extra_kwargs { password: {write_only: True, min_length: 8}, } def validate(self, attrs): confirm_password attrs.pop(confirm_password, None) if attrs.get(password) ! confirm_password: raise serializers.ValidationError({confirm_password: 兩次輸入的密碼不一致}) return attrs def create(self, validated_data): password validated_data.pop(password) user User(**validated_data) user.set_password(password) user.save() return user這里create方法做的是從校驗(yàn)后的數(shù)據(jù)里取出密碼用Django自帶的set_password做哈希再創(chuàng)建用戶。這樣User表中的password字段存的是哈希值而不是明文。覆蓋create之后序列化器返回的對(duì)象就是創(chuàng)建好的user實(shí)例。在View里這樣用from rest_framework.views import APIView from rest_framework.response import Response from rest_framework import status from .serializers import RegisterSerializer class RegisterView(APIView): def post(self, request): serializer RegisterSerializer(datarequest.data) serializer.is_valid(raise_exceptionTrue) serializer.save() return Response( {id: serializer.instance.id, username: serializer.instance.username}, statusstatus.HTTP_201_CREATED, )is_valid(raise_exceptionTrue)是DRF里很推薦的一種寫法校驗(yàn)失敗直接拋出異常由DRF的異常處理器統(tǒng)一返回400響應(yīng)錯(cuò)誤信息自動(dòng)帶上每個(gè)字段的報(bào)錯(cuò)。這樣你就不用在自己的View里手寫錯(cuò)誤響應(yīng)了。5.2 覆蓋update方法處理需要特殊邏輯的更新默認(rèn)的update實(shí)現(xiàn)是遍歷validated_data逐個(gè)setattr然后save。多數(shù)情況下夠用但遇到外鍵關(guān)聯(lián)的創(chuàng)建、多對(duì)多關(guān)系維護(hù)就得自己動(dòng)手了?？催@個(gè)評(píng)論發(fā)布場(chǎng)景class Comment(models.Model): article models.ForeignKey(Article, on_deletemodels.CASCADE, related_namecomments) user models.ForeignKey(User, on_deletemodels.CASCADE) content models.TextField() created_at models.DateTimeField(auto_now_addTrue)如果接口希望前端傳article_id來(lái)發(fā)布評(píng)論而當(dāng)前登錄用戶從request.user取可以這么寫class CommentCreateSerializer(serializers.ModelSerializer): article serializers.PrimaryKeyRelatedField(querysetArticle.objects.all()) class Meta: model Comment fields [id, article, content, created_at] def validate_article(self, value): if not value.is_published: raise serializers.ValidationError(文章未發(fā)布不能評(píng)論) return value def create(self, validated_data): user self.context[request].user return Comment.objects.create(useruser, **validated_data)這里有一個(gè)重點(diǎn)create方法里通過(guò)self.context[request]拿到了當(dāng)前請(qǐng)求的用戶。context是序列化器內(nèi)部的一個(gè)字典View在實(shí)例化序列化器時(shí)會(huì)自動(dòng)注入request、view、format等鍵。你不需要自己傳只要在View里用CommentCreateSerializer(datarequest.data)這種正常實(shí)例化方式context就天然包含request。校驗(yàn)和創(chuàng)建的鏈路已經(jīng)很清晰了前端傳article_id和content序列化器校驗(yàn)文章是否存在和可評(píng)論創(chuàng)建時(shí)自動(dòng)綁定登錄用戶。這個(gè)模式在寫“當(dāng)前用戶創(chuàng)建自己的資源”類接口時(shí)非常常見(jiàn)。5.3 控制序列化輸出的字段視圖很多時(shí)候同一個(gè)模型在不同接口里要展示不同的字段集合。列表頁(yè)只要標(biāo)題和作者名詳情頁(yè)要完整正文和創(chuàng)建時(shí)間用戶自己的資料接口要郵箱和頭像別人看他資料時(shí)郵箱要隱藏。ModelSerializer允許你為同一個(gè)模型定義多個(gè)序列化器每個(gè)序列化器專注一種輸出視圖。我最常用的做法是一個(gè)基礎(chǔ)序列化器幾個(gè)繼承它的子序列化器子類只修改Meta.fields和追加字段。class ArticleBaseSerializer(serializers.ModelSerializer): class Meta: model Article fields [id, title, content, created_at] class ArticleListSerializer(ArticleBaseSerializer): author_name serializers.CharField(sourceauthor.username, read_onlyTrue) comment_count serializers.IntegerField(sourcecomments.count, read_onlyTrue) class Meta(ArticleBaseSerializer.Meta): fields [id, title, author_name, comment_count, created_at] class ArticleDetailSerializer(ArticleBaseSerializer): author UserBriefSerializer(read_onlyTrue) class Meta(ArticleBaseSerializer.Meta): fields [id, title, content, author, created_at]這樣做的好處不用多說(shuō)列表接口輕量詳情接口完整每個(gè)接口返回的數(shù)據(jù)都是明確的。不需要一個(gè)序列化器里堆一堆SerializerMethodField然后靠View里刪字段來(lái)控制輸出。5.4 在序列化器里判斷請(qǐng)求類型動(dòng)態(tài)調(diào)整字段還有一類場(chǎng)景同一個(gè)序列化器在創(chuàng)建和更新時(shí)行為不同。比如用戶名創(chuàng)建時(shí)必填更新時(shí)可選密碼創(chuàng)建時(shí)必填更新時(shí)可選。實(shí)現(xiàn)這個(gè)效果有個(gè)經(jīng)典手法在初始化時(shí)根據(jù)self.context或者操作類型調(diào)整字段的required屬性。class UserUpdateSerializer(UserSerializer): def __init__(self, *args, **kwargs): super().__init__(*args, **kwargs) if self.instance is None: # 創(chuàng)建場(chǎng)景username 必填password 必填 self.fields[username].required True self.fields[password].required True else: # 更新場(chǎng)景兩個(gè)字段都選填 self.fields[username].required False self.fields[password].required False判斷self.instance是否為None就能區(qū)分是創(chuàng)建還是更新創(chuàng)建時(shí)instance為None更新時(shí)instance是已有的模型實(shí)例。當(dāng)然如果邏輯更復(fù)雜我還是建議直接拆成兩個(gè)序列化器畢竟一個(gè)序列化器里塞太多分支時(shí)間長(zhǎng)了連自己都會(huì)看暈。5.5 性能優(yōu)化別讓序列化器引發(fā)N1ModelSerializer在輸出嵌套字段時(shí)不會(huì)自動(dòng)幫你優(yōu)化數(shù)據(jù)庫(kù)查詢。如果一個(gè)列表返回50篇文章每篇文章都要查一次作者那就是51條SQL。對(duì)比一下這個(gè)數(shù)字如果你不做優(yōu)化這個(gè)接口的數(shù)據(jù)庫(kù)壓力是非常難看的。解決方案不是改序列化器而是在View的查詢集里做預(yù)加載。DRF的ListAPIView允許重寫get_querysetclass ArticleListView(ListAPIView): serializer_class ArticleListSerializer def get_queryset(self): return Article.objects.select_related(author).prefetch_related(comments)select_related適用于外鍵這種單值關(guān)聯(lián)prefetch_related適用于多對(duì)多、反向外鍵這種集合關(guān)聯(lián)。配合前面的sourcecomments.countprefetch_related(comments)可以把COUNT查詢也合并優(yōu)化但要注意count()在prefetch之后依然會(huì)對(duì)每個(gè)對(duì)象執(zhí)行聚合并不會(huì)自動(dòng)緩存。如果需要極致優(yōu)化可以用annotate在QuerySet層面一次性把數(shù)量算好。from django.db.models import Count class ArticleListView(ListAPIView): serializer_class ArticleListSerializer def get_queryset(self): return Article.objects.select_related(author).annotate(comment_countCount(comments))然后用IntegerField(read_onlyTrue)接收這個(gè)注解字段接口的SQL數(shù)量直接從幾十條降到兩三條。序列化器本身不背性能的鍋但理解序列化器怎么消耗查詢才能真正優(yōu)化到位。6. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄6.1 使用ModelSerializer時(shí)最容易踩的坑先說(shuō)一個(gè)新人必踩的創(chuàng)建帶外鍵的嵌套數(shù)據(jù)時(shí)默認(rèn)的create只支持扁平數(shù)據(jù)。如果你前端傳的是嵌套JSON希望一次性創(chuàng)建主表和關(guān)聯(lián)表默認(rèn)實(shí)現(xiàn)做不到。DRF會(huì)直接報(bào)錯(cuò)或者只創(chuàng)建主表數(shù)據(jù)。解決辦法就是在create里手動(dòng)處理嵌套結(jié)構(gòu)先pop出嵌套字段創(chuàng)建主表再逐一創(chuàng)建或更新關(guān)聯(lián)數(shù)據(jù)。再說(shuō)一個(gè)看起來(lái)很冤的報(bào)錯(cuò)TypeError: Field object is not callable。class UserSerializer(serializers.ModelSerializer): class Meta: model User fields [id, username, email, password, created_at] read_only_fields [created_at]這代碼看著沒(méi)問(wèn)題吧但如果你的模型里恰好有個(gè)字段叫created_at而你在Meta的read_only_fields里把它列為只讀某些版本下DRF會(huì)嘗試對(duì)created_at字段本身調(diào)用__call__引發(fā)上面的錯(cuò)。這類問(wèn)題的排查思路就是檢查有沒(méi)有字段名和模型元信息重復(fù)尤其是Meta類里的配置鍵寫錯(cuò)。還有個(gè)很典型的AssertionError: The model is not valid。這個(gè)一般是你把Meta.model寫成了字符串而不是模型類或者模型類沒(méi)有被正確導(dǎo)入。模型類必須是類對(duì)象不能是字符串。AttributeError也常見(jiàn)。定義了一個(gè)SerializerMethodField的get_xxx方法但方法名和字段名對(duì)不上DRF會(huì)報(bào)找不到對(duì)應(yīng)方法。或者source參數(shù)指向的模型字段不存在也會(huì)AttributeError。6.2 實(shí)戰(zhàn)中遇到的調(diào)試思路序列化器出問(wèn)題第一個(gè)動(dòng)作永遠(yuǎn)是看data和errors。is_valid()返回False時(shí)別急著改代碼先在errors里看具體報(bào)錯(cuò)字段。serializer UserSerializer(datarequest.data) if not serializer.is_valid(): print(serializer.errors)很多時(shí)候你會(huì)發(fā)現(xiàn)報(bào)錯(cuò)并不是邏輯問(wèn)題而是字段的required、write_only配置不對(duì)。比如前端傳了password但你沒(méi)設(shè)write_onlyTrue校驗(yàn)通過(guò)后密碼又會(huì)出現(xiàn)在序列化輸出這屬于配置層面問(wèn)題而不是模型問(wèn)題。如果接口返回了500常見(jiàn)原因是序列化器輸出時(shí)某個(gè)字段訪問(wèn)了不存在的屬性。例如嵌套序列化器里的source寫成了author.username但查詢集沒(méi)有被select_relatedDRF照樣能查出來(lái)但如果你在SerializerMethodField里寫了obj.author.username必須保證obj.author已經(jīng)加載。沒(méi)加載時(shí)Django會(huì)額外查詢一次不算報(bào)錯(cuò)但卻是N1的起點(diǎn)。6.3 容易忽略的小經(jīng)驗(yàn)經(jīng)驗(yàn)一永遠(yuǎn)不要拿默認(rèn)的ModelSerializer直接做創(chuàng)建類接口。至少過(guò)一遍字段列表看看有沒(méi)有不該暴露的字段、有沒(méi)有需要隱藏的字段。我見(jiàn)過(guò)生產(chǎn)環(huán)境接口直接把用戶密碼哈希返回給前端的案例就是因?yàn)殚_(kāi)發(fā)省事用了fields __all__。經(jīng)驗(yàn)二ModelSerializer的Meta.fields里寫不存在的字段會(huì)直接報(bào)ImproperlyConfigured這其實(shí)是好事能幫你盡早發(fā)現(xiàn)模型和序列化器不同步的問(wèn)題。別用__all__繞過(guò)這種檢查。經(jīng)驗(yàn)三requiredFalse和default不要寫重。如果字段配置了默認(rèn)值前端不傳時(shí)就用默認(rèn)值兩個(gè)同時(shí)出現(xiàn)有時(shí)會(huì)產(chǎn)生預(yù)期外的行為。建議二選一。經(jīng)驗(yàn)四序列化器的create和update方法與模型表單的save殊途同歸都是把校驗(yàn)后的數(shù)據(jù)落到庫(kù)里。因此但凡你需要在落庫(kù)前“加工”數(shù)據(jù)都放在這里干別放在View里。把數(shù)據(jù)加工邏輯留在View會(huì)導(dǎo)致其他接口要復(fù)用同一套序列化器時(shí)還得把那套加工邏輯再?gòu)?fù)制一遍。經(jīng)驗(yàn)五多序列化器協(xié)同輸出時(shí)注意給每個(gè)序列化器單獨(dú)命名別都用Serializer結(jié)尾。項(xiàng)目大了以后ArticleSerializer和ArticleCreateSerializer混在一起看代碼真的會(huì)暈。我在項(xiàng)目里統(tǒng)一用ArticleDetailSerializer、ArticleCreateSerializer、UserBriefSerializer這種命名一眼就知道用途。經(jīng)驗(yàn)六調(diào)試嵌套序列化器輸出時(shí)直接在Python shell里手動(dòng)實(shí)例化看結(jié)果比發(fā)請(qǐng)求調(diào)接口快得多from myapp.serializers import ArticleListSerializer from myapp.models import Article article Article.objects.select_related(author).first() serializer ArticleListSerializer(article) print(serializer.data)這個(gè)方法能快速驗(yàn)證字段配置是否生效而且不依賴前端。ModelSerializer最難的地方從來(lái)不是語(yǔ)法而是搞清楚每個(gè)字段在這個(gè)接口里的定位。是輸入、輸出還是校驗(yàn)邊界是只讀、必填還是選填是自己手寫的字段還是從模型自動(dòng)映射出來(lái)的字段。把這幾個(gè)維度想清楚用起來(lái)基本上就順了。我自己最常用的節(jié)奏是先按接口需求列出字段清單再定義Meta里的fields和extra_kwargs然后補(bǔ)充校驗(yàn)和create/update覆蓋最后用shell驗(yàn)證輸出。這套流程走下來(lái)ModelSerializer基本不會(huì)出什么幺蛾子希望這篇內(nèi)容也能讓你的DRF開(kāi)發(fā)少走點(diǎn)彎路。