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