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