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