寫了 5 年 Python從一個(gè)只會(huì)寫腳本的“調(diào)包俠”到能在生產(chǎn)環(huán)境里扛住流量、排查線上事故的工程師中間真的踩過(guò)不少坑。有些坑是文檔里查不到的有些坑只有你被 on-call 電話叫醒、盯著日志翻到天亮才會(huì)真正記住。今天不分享框架源碼也不講算法優(yōu)化就聊聊我這 5 年下來(lái)最終留下的 7 條 Python 工程習(xí)慣。這些習(xí)慣不是從哪本書里抄的而是被線上事故、代碼評(píng)審、團(tuán)隊(duì)協(xié)作逼出來(lái)的。如果你正在寫 Python或者你團(tuán)隊(duì)里的 Python 代碼總出幺蛾子這篇內(nèi)容應(yīng)該能給你一些參考。1. 先定牢“類型邊界”再談代碼復(fù)用1.1 從一次接口事故說(shuō)起先講個(gè)真實(shí)經(jīng)歷。早年在某公司維護(hù)一個(gè)支付回調(diào)模塊上游傳來(lái)一個(gè) JSON里面有個(gè)amount字段。當(dāng)時(shí)圖省事代碼里直接if data[amount] 100判斷也沒(méi)做類型轉(zhuǎn)換。某天上游改了字段格式把數(shù)字字符串100.00傳了進(jìn)來(lái)比較結(jié)果完全正常但后面做金額計(jì)算時(shí)字符串和浮點(diǎn)數(shù)混在一起出現(xiàn)了小數(shù)點(diǎn)精度問(wèn)題直接導(dǎo)致一筆訂單對(duì)賬差了 1 分錢。排查了整整兩個(gè)晚上最后發(fā)現(xiàn)是類型邊界沒(méi)管好。這件事給我的教訓(xùn)是Python 是動(dòng)態(tài)語(yǔ)言但不代表你可以在工程代碼里“放飛自我”。動(dòng)態(tài)類型給你靈活也把責(zé)任推給了調(diào)用方和未來(lái)的維護(hù)者。你寫函數(shù)時(shí)自己知道參數(shù)是什么類型但三個(gè)月后的你跟現(xiàn)在的你完全是兩個(gè)人更別說(shuō)團(tuán)隊(duì)里還有其他人。1.2 我最終留下的類型標(biāo)注習(xí)慣我現(xiàn)在寫任何新模塊都會(huì)遵循這幾條所有函數(shù)參數(shù)和返回值都加類型標(biāo)注type hints即使只是def foo(x: int) - str這樣的基礎(chǔ)標(biāo)注。數(shù)據(jù)類用dataclass定義而不是只靠 dict 傳遞結(jié)構(gòu)。這樣字段名、默認(rèn)值、類型都一目了然也方便 IDE 補(bǔ)全和靜態(tài)檢查。涉及外部接口的數(shù)據(jù)結(jié)構(gòu)用pydantic或dataclass做一層顯式校驗(yàn)和轉(zhuǎn)換絕不讓“裸 dict”穿過(guò)服務(wù)邊界。在 CI 里跑mypy把它當(dāng)成強(qiáng)制檢查項(xiàng)而不是可選的錦上添花。有人說(shuō) Python 加類型標(biāo)注麻煩但我算過(guò)一筆賬寫標(biāo)注的時(shí)間大概是寫函數(shù)體時(shí)間的五分之一但能省掉排查類型 bug 的時(shí)間可能是十倍。尤其是服務(wù)多了之后調(diào)用鏈一長(zhǎng)類型標(biāo)注就是一張隱性的接口文檔。1.3 動(dòng)態(tài)語(yǔ)言的邊界在哪里當(dāng)然不是所有代碼都要上類型。臨時(shí)腳本、一次性數(shù)據(jù)處理我從來(lái)不用mypy因?yàn)椴恢档?。我的判斷?biāo)準(zhǔn)是這段代碼的生命周期是否超過(guò)一周是否需要被其他人調(diào)用是否要跟外部系統(tǒng)交互如果三個(gè)問(wèn)題里有一個(gè)“是”就值得加類型標(biāo)注和校驗(yàn)。另外還要注意類型標(biāo)注不等于運(yùn)行時(shí)校驗(yàn)。def foo(x: int)并不會(huì)在傳字符串時(shí)自動(dòng)報(bào)錯(cuò)。如果你需要嚴(yán)格校驗(yàn)必須靠pydantic或者在函數(shù)入口手動(dòng)isinstance。我之前就用pydantic統(tǒng)一管理所有 HTTP 請(qǐng)求和響應(yīng)的模型既做了類型約束又自動(dòng)生成了文檔還順便處理了反序列化一舉三得。提示如果你還在用裸 dict 傳遞業(yè)務(wù)數(shù)據(jù)趁早換成 dataclass 或 pydantic。這個(gè)習(xí)慣越早養(yǎng)成后面重構(gòu)的痛越少。2. 配置不進(jìn)代碼環(huán)境與依賴嚴(yán)格分離2.1 那段被配置文件支配的歲月我見(jiàn)過(guò)最離譜的代碼是把數(shù)據(jù)庫(kù)密碼直接寫在 Python 文件里硬編碼成全局變量然后整個(gè)團(tuán)隊(duì)共享。更離譜的是這個(gè)代碼還被提交到了代碼倉(cāng)庫(kù)最后因?yàn)橐粋€(gè)內(nèi)部工具掃描泄露了生產(chǎn)環(huán)境的連接信息不得不緊急改密碼、重建實(shí)例。那是我第一次意識(shí)到配置管理不是“以后再說(shuō)”的事而是工程底線。后來(lái)我接手過(guò)一套老系統(tǒng)配置全部堆在一個(gè)settings.py里里面寫了開(kāi)發(fā)、測(cè)試、預(yù)發(fā)、生產(chǎn)四套配置通過(guò)一個(gè)ENV環(huán)境變量來(lái)切換?？粗孟駴](méi)問(wèn)題但每次上線都心驚膽戰(zhàn)因?yàn)橹灰腥烁牧艘恍锌赡芫蜁?huì)影響所有環(huán)境。某次預(yù)發(fā)環(huán)境連了生產(chǎn)庫(kù)還跑了一次數(shù)據(jù)遷移差點(diǎn)釀成大事故。2.2 環(huán)境管理與依賴鎖定的利器現(xiàn)在我的習(xí)慣是代碼庫(kù)里不出現(xiàn)任何環(huán)境相關(guān)的配置值只出現(xiàn)配置引用。環(huán)境變量來(lái)了填進(jìn)去配置中心來(lái)了從遠(yuǎn)端拉代碼本身永遠(yuǎn)不知道自己是跑在哪套環(huán)境。具體做法分三層12-factor 風(fēng)格配置所有配置項(xiàng)從環(huán)境變量讀取代碼里只有os.getenv(DB_HOST)這類調(diào)用。本地開(kāi)發(fā)用.env文件統(tǒng)一管理用python-dotenv加載但這個(gè)文件不提交到 git。依賴環(huán)境也要隔離用venv或poetry管理虛擬環(huán)境用requirements.txt或poetry.lock鎖定精確版本。所有新依賴必須通過(guò)鎖文件變更不能直接 pip install 到全局。我偏好poetry因?yàn)樗岩蕾嚬芾?、虛擬環(huán)境、打包發(fā)布統(tǒng)一起來(lái)了pyproject.toml 里直接寫清依賴范圍和 Python 版本比純 requirements 文件更清晰。團(tuán)隊(duì)新人來(lái)了一條命令poetry install就能把環(huán)境拉起來(lái)省得互相問(wèn)“你裝的什么版本”。2.3 環(huán)境變量、配置中心怎么選小團(tuán)隊(duì)、單體服務(wù)環(huán)境變量完全夠用。但服務(wù)多了以后環(huán)境變量管理會(huì)變得混亂——幾十個(gè)服務(wù)每套環(huán)境幾十個(gè)變量靠人工維護(hù)很容易出錯(cuò)。這時(shí)候就需要配置中心了比如 etcd、consul、或云廠商的配置管理服務(wù)。我的選擇邏輯很簡(jiǎn)單服務(wù)數(shù)少于 5 個(gè)環(huán)境變量 .env 文件夠用。服務(wù)數(shù)多于 5 個(gè)但配置量不大用配置中心拉取啟動(dòng)時(shí)拿不到配置就直接失敗避免帶病啟動(dòng)。配置變更頻繁需要?jiǎng)討B(tài)刷新選帶推送能力的配置中心而不是重啟服務(wù)。配置中心雖然好用但也會(huì)引入新依賴。我們?cè)谀硞€(gè)項(xiàng)目里跑了 consul但忘了處理它掛掉的情況結(jié)果配置拉不到服務(wù)全部起不來(lái)。后來(lái)加了本地緩存作為兜底即使配置中心掛了也用上一次的緩存啟動(dòng)再配合告警提醒人工介入。注意代碼里盡量不要用try/except吞掉配置加載異常。配置缺失時(shí)要及時(shí)暴露出來(lái)最好在啟動(dòng)階段就 fail fast否則線上服務(wù)可能半死不活看似在運(yùn)行實(shí)際功能全壞。3. 日志不是打出來(lái)就完事要能“撈得回來(lái)”3.1 線上排障時(shí)日志的救命場(chǎng)景有一回線上告警說(shuō)某個(gè)接口成功率驟降。我打開(kāi)日志平臺(tái)輸入服務(wù)名和關(guān)鍵字結(jié)果刷出來(lái)的全是格式不一的文本有的行是print打出來(lái)的有的行是logger.info寫的還有的日志里根本沒(méi)帶請(qǐng)求 ID完全沒(méi)法把一次用戶請(qǐng)求的完整鏈路串起來(lái)。最后只能靠猜先看 Nginx 日志找到出錯(cuò)的請(qǐng)求再根據(jù)時(shí)間戳去翻應(yīng)用日志效率極低。那次之后我才明白日志不是“有就行”而是要有“可查詢性”。所謂可查詢性就是你能在短時(shí)間內(nèi)通過(guò)一組固定維度把某一次請(qǐng)求的所有相關(guān)日志全部撈出來(lái)。3.2 結(jié)構(gòu)化日志與日志追蹤ID我現(xiàn)在打日志只用一個(gè)標(biāo)準(zhǔn)結(jié)構(gòu)化 JSON 日志。每一條日志包含時(shí)間、級(jí)別、logger 名稱、消息、上下文數(shù)據(jù)用 json.dumps 統(tǒng)一序列化或者直接用python-json-logger這類庫(kù)。為什么用 JSON因?yàn)槿罩鞠到y(tǒng)里可以按字段索引不用寫正則去摳文本。最關(guān)鍵的是追蹤 ID。每個(gè)請(qǐng)求入口生成一個(gè)trace_id或者叫 request_id通過(guò)中間件注入到 context 里然后所有業(yè)務(wù)日志都帶著這個(gè) ID。這樣排查問(wèn)題時(shí)只需要按 trace_id 搜索就能把一次請(qǐng)求的訪問(wèn)日志、業(yè)務(wù)日志、異常堆棧全部串在一起。Python 里實(shí)現(xiàn)這個(gè)有很多方式老項(xiàng)目我會(huì)用contextvars加一個(gè)日志過(guò)濾器在日志格式化時(shí)自動(dòng)把 trace_id 塞進(jìn)記錄里業(yè)務(wù)代碼根本不用手動(dòng)傳參。新項(xiàng)目直接上 OpenTelemetry 這類鏈路追蹤框架一步到位。3.3 日志級(jí)別的工程約定級(jí)別這件事團(tuán)隊(duì)里必須有共同語(yǔ)言。我踩過(guò)最典型的一個(gè)坑是有人把重要業(yè)務(wù)操作放在logger.debug結(jié)果生產(chǎn)環(huán)境日志級(jí)別是 INFO關(guān)鍵信息全丟了也有人用logger.error打普通業(yè)務(wù)流程導(dǎo)致告警刷屏真正的故障被淹沒(méi)。我現(xiàn)在定的約定是DEBUG開(kāi)發(fā)調(diào)試線上默認(rèn)關(guān)閉。INFO記錄業(yè)務(wù)節(jié)點(diǎn)的關(guān)鍵事件比如下單、支付、狀態(tài)變更帶有可追蹤的 trace_id。WARNING可能有風(fēng)險(xiǎn)但不影響主流程比如重試、降級(jí)、稍后處理。ERROR發(fā)生了會(huì)影響單次請(qǐng)求或功能的問(wèn)題需要記錄異常堆棧和上下文數(shù)據(jù)。CRITICAL系統(tǒng)級(jí)故障必須觸發(fā)立即告警。這條清單我寫了放在團(tuán)隊(duì) wiki 里新人來(lái)了先讀一遍。告警規(guī)則只匹配 WARNING 和 ERROR且必須有對(duì)應(yīng)的 trace_id否則視為無(wú)效日志。心得日志里不要搜集身份證號(hào)、密碼、token 這類敏感信息但可以把脫敏后的值放進(jìn)去。我見(jiàn)過(guò)有人把完整手機(jī)號(hào)打進(jìn)日志最后數(shù)據(jù)庫(kù)被脫敏日志卻沒(méi)脫敏成了新的泄露出口。4. 單元測(cè)試是給未來(lái)合作者的“安全網(wǎng)”4.1 為什么寫測(cè)試是對(duì)別人的負(fù)責(zé)很多人覺(jué)得“這段代碼我自己跑通了不用寫測(cè)試”但工程代碼的目標(biāo)不是“在我電腦上能跑”而是“在任何環(huán)境里、任何時(shí)間、任何人都能安全地改動(dòng)”。有測(cè)試兜底你才敢重構(gòu)沒(méi)測(cè)試兜底每一次改動(dòng)都是高空踩鋼絲。我印象最深的一次某同事改了一個(gè)工具函數(shù)把默認(rèn)參數(shù)從None改成了空列表結(jié)果下層模塊直接復(fù)用了這個(gè)函數(shù)導(dǎo)致所有請(qǐng)求共享同一個(gè)列表內(nèi)存越積越多最后服務(wù) OOM。如果那個(gè)工具函數(shù)有一個(gè)簡(jiǎn)單的單元測(cè)試測(cè)試?yán)锒鄠饕粋€(gè)值再斷言兩次調(diào)用互不影響這種問(wèn)題根本走不到線上。4.2 測(cè)試金字塔與常用工具我現(xiàn)在寫測(cè)試遵循金字塔原則底層單元測(cè)試最多覆蓋純函數(shù)和業(yè)務(wù)邏輯中間層集成測(cè)試驗(yàn)證模塊間的交互頂層端到端測(cè)試只覆蓋關(guān)鍵核心鏈路數(shù)量很少。Python 里我最常用的組合是pytest功能強(qiáng)大、fixture 靈活能跑參數(shù)化用例。pytest-cov統(tǒng)計(jì)覆蓋率但我不追求 100%只要求核心模塊 90% 以上。responses或respxmock HTTP 請(qǐng)求測(cè)服務(wù)調(diào)用。factory-boy生成測(cè)試數(shù)據(jù)比手寫 fixture 清晰。fixture 的使用有個(gè)要點(diǎn)不要把 fixture 寫成“一個(gè)函數(shù)造一個(gè)對(duì)象”而是盡量小而可組合。比如我定義一個(gè)userfixture一個(gè)orderfixtureorder 依賴 user。這樣測(cè)試用例里可以自由組合不用的數(shù)據(jù)不會(huì)白造跑起來(lái)也快。4.3 如何讓測(cè)試不拖累開(kāi)發(fā)速度很多人拒絕寫測(cè)試是覺(jué)得“寫測(cè)試?yán)速M(fèi)時(shí)間”。但我發(fā)現(xiàn)只要把測(cè)試放進(jìn)常規(guī)開(kāi)發(fā)流程反而能省時(shí)間。我的做法是寫完一個(gè)功能先寫這個(gè)功能的最小測(cè)試用例然后跑一遍確認(rèn)測(cè)試能不能抓住 bug。不需要一次寫全先把主干覆蓋了后面再迭代補(bǔ)充邊界測(cè)試。測(cè)試能跑多快單元測(cè)試應(yīng)該控制在幾秒以內(nèi)。如果測(cè)試超過(guò)幾十秒團(tuán)隊(duì)就會(huì)不喜歡跑最終淪為“沒(méi)人跑的擺設(shè)”。我有個(gè)原則所有單元測(cè)試全部?jī)?nèi)存化用 SQLite 或 mock 替代外部服務(wù)不依賴真實(shí)數(shù)據(jù)庫(kù)和網(wǎng)絡(luò)。集成測(cè)試單獨(dú)用一個(gè) marker 標(biāo)記只在 CI 的特定 job 里運(yùn)行。這樣可以保證日常開(kāi)發(fā)pytest -m unit在一分鐘內(nèi)跑完。CI 里面再加一道強(qiáng)制門檻覆蓋率下降不能超過(guò) 1%新增代碼的行覆蓋率要高于 80%。一開(kāi)始會(huì)覺(jué)得苛刻但跑一段時(shí)間后團(tuán)隊(duì)寫代碼時(shí)就會(huì)本能地思考“這段邏輯怎么測(cè)”反而促使他們寫得更容易測(cè)試。提醒mock 要節(jié)制。過(guò)度 mock 會(huì)讓測(cè)試變成“自嗨”根本測(cè)不到真實(shí)邏輯。比如把一個(gè)外部 HTTP 調(diào)用 mock 成返回值卻忘了真實(shí)接口是異步還是同步這種測(cè)試毫無(wú)意義。寧可少寫幾個(gè)偽測(cè)試也要保證每個(gè)測(cè)試真的能代表一段真實(shí)行為。5. 異常與錯(cuò)誤處理讓失敗也成為接口的一部分5.1 裸except的慘痛教訓(xùn)Python 的except特別容易濫用。我見(jiàn)過(guò)無(wú)數(shù)代碼try: do_something() except: pass這個(gè)寫法相當(dāng)于告訴計(jì)算機(jī)“不管出了什么錯(cuò)你都別吭聲?！苯Y(jié)果就是錯(cuò)誤被吞掉服務(wù)繼續(xù)跑但狀態(tài)已經(jīng)錯(cuò)了。我處理過(guò)最慘的一個(gè) case某定時(shí)任務(wù)里裸捕獲了所有異常導(dǎo)致數(shù)據(jù)庫(kù)寫入失敗也沒(méi)人發(fā)現(xiàn)連續(xù)跑了三天產(chǎn)生了大量臟數(shù)據(jù)最后只能人工清洗。所以我的第一條鐵律是永遠(yuǎn)不要用裸except。至少要寫except Exception因?yàn)閑xcept:連KeyboardInterrupt和SystemExit也會(huì)捕獲容易讓程序無(wú)法退出。更合理的是按具體異常類型捕獲比如except ValueError、except KeyError讓錯(cuò)誤處理有針對(duì)性。5.2 自定義異常體系與錯(cuò)誤碼為什么需要自定義異常因?yàn)閮?nèi)置異常只能表達(dá)“什么類型錯(cuò)了”不能表達(dá)“業(yè)務(wù)哪里錯(cuò)了”。我給你看一個(gè)反例某個(gè)服務(wù)里到處raise ValueError(用戶不存在)然后調(diào)用方統(tǒng)一except ValueError結(jié)果參數(shù)校驗(yàn)錯(cuò)誤也被當(dāng)成用戶不存在處理返回給前端的是完全錯(cuò)誤的信息?，F(xiàn)在我習(xí)慣為每個(gè)模塊定義異?；惐热鏲lass ServiceError(Exception): 業(yè)務(wù)服務(wù)基礎(chǔ)異常 class UserNotFoundError(ServiceError): code USER_NOT_FOUND message 用戶不存在 class PaymentFailedError(ServiceError): code PAYMENT_FAILED message 支付失敗上層捕獲ServiceError然后根據(jù)code映射 HTTP 狀態(tài)碼和錯(cuò)誤提示。不同模塊的異?；ハ喔綦x即使同名也不會(huì)混淆。同時(shí)針對(duì)網(wǎng)絡(luò)調(diào)用、數(shù)據(jù)庫(kù)操作這類可能臨時(shí)失敗的場(chǎng)景我會(huì)定義重試策略。常用的庫(kù)有tenacity可以配置重試次數(shù)、間隔、哪些異?？芍卦?。重試只針對(duì)瞬時(shí)故障比如連接超時(shí)、數(shù)據(jù)庫(kù)鎖沖突業(yè)務(wù)邏輯錯(cuò)誤比如余額不足不能重試否則會(huì)造成重復(fù)扣款。5.3 防御式編程與Fail Fast防御式編程不是到處加if判斷而是在“邊界入口”上做防御。我的習(xí)慣是外部輸入、配置值、依賴服務(wù)的返回值這三個(gè)地方必須做校驗(yàn)。內(nèi)部函數(shù)之間相信類型標(biāo)注和測(cè)試不做多余檢查。校驗(yàn)不通過(guò)時(shí)越早暴露越好。我寧可啟動(dòng)時(shí)因?yàn)榕渲脼榭斩罎⒁膊幌胱尫?wù)跑著跑著才在某個(gè)角落報(bào)錯(cuò)。這就是 fail fast 的原則錯(cuò)誤發(fā)生的位置越接近發(fā)生點(diǎn)排查成本越低。再分享一個(gè)細(xì)節(jié)不要用assert做數(shù)據(jù)校驗(yàn)。Python 的assert在運(yùn)行python -O時(shí)會(huì)被禁用線上環(huán)境如果開(kāi)啟了優(yōu)化所有斷言都會(huì)失效。我在老項(xiàng)目里見(jiàn)過(guò)一堆a(bǔ)ssert校驗(yàn)前端傳參結(jié)果某人加了優(yōu)化選項(xiàng)發(fā)布線上直接失去了校驗(yàn)?zāi)芰髁朔欠▍?shù)也沒(méi)人攔。所以只有開(kāi)發(fā)者自測(cè)時(shí)可以用 assert對(duì)外輸入校驗(yàn)必須用顯式的 if raise。6. 函數(shù)式抽象與依賴注入解耦的思維練習(xí)6.1 全局變量和隱式依賴的壞味道我見(jiàn)過(guò)最讓人頭疼的代碼是函數(shù)內(nèi)部直接引用全局變量比如config load_config() def process(): timezone config[timezone] return ...如果哪天config變了或者沒(méi)有全局定義這個(gè)函數(shù)就會(huì)莫名其妙地失敗。更麻煩的是測(cè)試要為這個(gè)函數(shù)準(zhǔn)備環(huán)境得先設(shè)置全局變量但pytest里全局變量的作用域很容易互相污染一組用例跑完另一組拿到的是殘留狀態(tài)。我后來(lái)學(xué)會(huì)一個(gè)判斷標(biāo)準(zhǔn)如果函數(shù)離開(kāi)“全局環(huán)境”就跑不起來(lái)說(shuō)明它有隱式依賴。隱式依賴越多代碼就越難理解、越難測(cè)試、越難復(fù)用。6.2 依賴注入的輕量實(shí)現(xiàn)依賴注入聽(tīng)起來(lái)很高大上但 Python 里根本不需要框架。最簡(jiǎn)單的做法就是通過(guò)函數(shù)參數(shù)傳依賴def fetch_user(user_id: int, db: Database) - User: ...測(cè)試的時(shí)候傳一個(gè) mock 的db就行。不需要 singleton不需要 global不需要魔法。這個(gè)簡(jiǎn)單習(xí)慣能解決 90% 的耦合問(wèn)題。有人會(huì)說(shuō)“每個(gè)調(diào)用點(diǎn)都要傳 db太麻煩。”我的回應(yīng)是麻煩一點(diǎn)換來(lái)的是清晰的調(diào)用鏈和可測(cè)試性。如果參數(shù)傳遞過(guò)多可以用一個(gè)Context對(duì)象把這些依賴打包但不建議用一個(gè)萬(wàn)能參數(shù)到處傳。對(duì)于類對(duì)象我通常使用構(gòu)造函數(shù)注入class OrderService: def __init__(self, payment_client: PaymentClient, db: Database): self.payment_client payment_client self.db db這樣寫的好處是每個(gè)類的依賴都在構(gòu)造簽名里清清楚楚團(tuán)隊(duì)里做代碼 review 時(shí)一眼就能看出這個(gè)類依賴了哪些外部服務(wù)方便評(píng)估風(fēng)險(xiǎn)和替換 mock。6.3 抽象接口與實(shí)現(xiàn)分離在 Python 里抽象有兩種方式一種是寫 ABC抽象基類一種是直接用“鴨子類型”只要實(shí)現(xiàn)了同名方法就可以。對(duì)于大型業(yè)務(wù)模塊我傾向于定義接口協(xié)議用typing.Protocol來(lái)表明“這個(gè)模塊需要什么樣的依賴”而不是強(qiáng)制繼承 ABC。舉個(gè)實(shí)際例子某項(xiàng)目里有郵件發(fā)送服務(wù)最開(kāi)始直接用了某個(gè)第三方 SDK 的MailClient到處from mail_sdk import MailClient。后來(lái)要換供應(yīng)商所有引用點(diǎn)都要改。我重構(gòu)時(shí)定義了一個(gè)協(xié)議class MailSender(Protocol): def send(self, to: str, content: str) - bool: ...然后將第三方 SDK 封裝在一個(gè) adapter 類里業(yè)務(wù)模塊只依賴MailSender。換供應(yīng)商時(shí)只需要新增一個(gè) adapter業(yè)務(wù)代碼零改動(dòng)。這樣做的另一層好處是測(cè)試時(shí)只需要 mock 一個(gè)符合MailSender協(xié)議的對(duì)象不需要 mock 任何第三方 SDK 的內(nèi)部結(jié)構(gòu)。抽象隔離了變化也隔離了外部庫(kù)對(duì)我們代碼的污染。心得不要一開(kāi)始就抽象過(guò)度設(shè)計(jì)比重復(fù)代碼更討厭。我通常是在“第二次要用相同邏輯”時(shí)才開(kāi)始提取接口。第一次用完就抽象往往假設(shè)錯(cuò)了方向反而讓結(jié)構(gòu)更亂。7. 代碼審查與自動(dòng)化把習(xí)慣固化成團(tuán)隊(duì)紀(jì)律7.1 代碼審查不是找茬寫好個(gè)人代碼是一回事團(tuán)隊(duì)協(xié)作又是另一回事。我越來(lái)越發(fā)現(xiàn)代碼審查Code Review不是為了揪出誰(shuí)的 bug也不是為了證明誰(shuí)更厲害而是為了“分享上下文”。我在 review 里最想看到的是這段代碼為什么這么寫有沒(méi)有考慮邊界評(píng)論區(qū)里能提出問(wèn)題也能記錄決定。我給自己定了一個(gè) review 清單每次看別人代碼都過(guò)一遍有沒(méi)有裸except、空分支、被靜默吞掉的異常有沒(méi)有配置硬編碼在代碼里有沒(méi)有全局可變狀態(tài)在模塊之間被共享有沒(méi)有函數(shù)做了兩件以上的事新增的依賴能不能避免有沒(méi)有更輕量的方案日志有沒(méi)有帶 trace_id字段結(jié)構(gòu)是否統(tǒng)一測(cè)試是否覆蓋了成功路徑和至少一種失敗路徑這個(gè)清單不在工具里而在腦子里。每次 review 都對(duì)著過(guò)一遍既快又穩(wěn)。時(shí)間久了寫代碼的人也會(huì)自動(dòng)先照這個(gè)清單自查。7.2 用自動(dòng)化工具減少口舌之爭(zhēng)Review 里最浪費(fèi)時(shí)間的是“格式問(wèn)題”和“命名問(wèn)題”。比如有人用單引號(hào)、有人用雙引號(hào)有人 tab 縮進(jìn)、有人空格縮進(jìn)為了這些吵架毫無(wú)價(jià)值。所以我的 CI 里直接集成了一整套自動(dòng)化檢查black統(tǒng)一代碼格式拒絕手工調(diào)格式。isort統(tǒng)一 import 順序。flake8或ruff檢查未使用的變量、重復(fù)定義、潛在語(yǔ)法錯(cuò)誤。mypy靜態(tài)類型檢查。pre-commit在本地 commit 之前就跑一遍上述工具。用pre-commit的最大好處是在代碼進(jìn)入倉(cāng)庫(kù)之前就把低級(jí)問(wèn)題攔住了。CI 里的檢查成了一個(gè)兜底真正需要人看的只有邏輯問(wèn)題。配置pre-commit其實(shí)不復(fù)雜新建一個(gè).pre-commit-config.yaml把black、isort、ruff加進(jìn)去然后pre-commit install即可。團(tuán)隊(duì)統(tǒng)一配置誰(shuí)機(jī)器上跑不過(guò)誰(shuí)就不能提交。剛開(kāi)始大家會(huì)抱怨“麻煩”但跑一周之后沒(méi)人再愿意手工調(diào)格式了。7.3 提交信息與分支規(guī)范提交信息看似無(wú)關(guān)緊要但在回滾和追溯時(shí)特別重要。我堅(jiān)持用 Conventional Commits 風(fēng)格feat: 增加訂單導(dǎo)出功能 fix: 修復(fù)金額精度丟失問(wèn)題 chore: 更新依賴版本 refactor: 重構(gòu)支付模塊的異常處理 ^這個(gè)格式讓git log變得可讀也有人會(huì)用 changelog 自動(dòng)生成版本記錄。但更重要的是分支命名、提交信息要和任務(wù)系統(tǒng)關(guān)聯(lián)起來(lái)。比如分支用feature/order_export提交信息里帶#123這樣的任務(wù)編號(hào)這樣以后查一個(gè)問(wèn)題能直接從 git 記錄跳到任務(wù)上下文甚至翻到當(dāng)初的討論記錄。還有一條鐵律絕不直接向 master/main 推送代碼所有變更都必須通過(guò) Pull Request/Merge Request。這條規(guī)則的背后不是流程潔癖而是為了強(qiáng)制代碼經(jīng)過(guò)至少一次 review 和 CI 檢查。哪怕是你自己的個(gè)人項(xiàng)目我也建議走一遍這個(gè)流程——至少能讓你自己回看一遍。經(jīng)驗(yàn)代碼審查的回復(fù)里盡量用“建議”“可以考慮”“我擔(dān)心”這樣的語(yǔ)氣而不是“你錯(cuò)了”“必須改”。工程協(xié)作本質(zhì)上是在管理風(fēng)險(xiǎn)不是在爭(zhēng)輸贏。好的 review 文化決定了一個(gè)團(tuán)隊(duì)能走多遠(yuǎn)。7 條習(xí)慣講完了都是我這幾年流水線里真刀真槍趟出來(lái)的。寫 Python 容易但把 Python 寫出工程感靠的不是某一個(gè)炫技語(yǔ)法而是這些看似瑣碎的日常約束。我個(gè)人最深的體會(huì)是這些習(xí)慣不是枷鎖而是保護(hù)網(wǎng)。有了類型邊界、結(jié)構(gòu)化日志、單測(cè)兜底和自動(dòng)檢查我反而敢大膽重構(gòu)代碼了——因?yàn)槲抑谰退愀腻e(cuò)了測(cè)試和日志也會(huì)第一時(shí)間告訴我。如果你也剛開(kāi)始帶項(xiàng)目不妨從其中一兩條開(kāi)始推行不用一步到位。少踩一個(gè)坑就是賺到。