接手一個代號叫 t3code 的舊項目是我這幾年做過最耗時也最有收獲的一件事。項目名里的 t3其實是當初團隊里一位老前輩隨手起的內部代號——取的是 Third Try 的意思也就是第三次推倒重來的版本?？芍S刺的是等我真正開始梳理這套代碼的時候它已經(jīng)歷了至少四次局部重寫代碼庫里同時躺著三套風格完全不同的命名規(guī)范核心業(yè)務鏈路里還有一份寫了五年卻沒人敢動的祖?zhèn)髋渲媚K。這篇文章不是什么理論教學而是把 t3code 從病入膏肓到恢復正常迭代速度的完整過程記錄下來的里面包含了我踩過的坑、用過的工具、以及最終沉淀下來的判斷標準。如果你手頭也有一坨不敢碰的老代碼或者正準備對現(xiàn)有系統(tǒng)做一次大規(guī)模重構這篇文章值得你花點時間讀完。先說結論t3code 這個項目最終沒有選擇推到重寫而是走了一條漸進式重構 局部重寫的混合路線。整個過程耗時大約四個月核心模塊的接口響應時間從平均 1200ms 降到了 380ms線上故障率降低了大約 70%更重要的是團隊里新來的兩個同事可以在兩周內獨立完成從前需要老員工帶著看一個月才能搞定的需求改動。下面我會按照實際操作順序把從代碼體檢、風險判斷、分階段重構到最終沉淀檢查清單的完整鏈路逐步拆開來講。1. t3code 項目起因攢了三四年的技術債到了不得不還的時候1.1 為什么這個代號叫 t3——它到底經(jīng)歷了什么t3code 最早是一個企業(yè)內部的數(shù)據(jù)統(tǒng)計系統(tǒng)最初是一個工程師用一周時間寫出來的臨時腳本集合用來每天跑幾張報表。后來業(yè)務擴張腳本變成了 Web 服務服務拆出了微服務微服務又引入了消息隊列。等到我接手的時候這個系統(tǒng)的代碼量已經(jīng)膨脹到將近 80 萬行其中有大約 30% 的代碼邏輯屬于看著有用但沒人說得清是否還有調用方。說病入膏肓一點不過分。那段時間系統(tǒng)幾乎每周都會出一次線上事故要么是某個定時任務突然卡死要么是某個接口偶發(fā)超時。每次排查到最后問題都指向同一批代碼——那些由不同時期不同人寫下的、相互交織的模塊。最折磨人的不是代碼本身的復雜度而是那份薛定諤的文檔文檔上寫了某個模塊負責 A 功能但實際代碼里它還悄悄改了 B 表的數(shù)據(jù)而這個副作用只有 2019 年某個深夜加班的同事知道那位同事在留言里寫了一句不要再動這段邏輯之后就離職了。促使我正式把 t3code 作為重構項目立項的導火索是一次持續(xù)了六個小時的線上故障。凌晨兩點某個核心報表的數(shù)據(jù)出現(xiàn)大面積偏差我們花了四個小時定位到原因——一個看似人畜無害的配置項在六年前被某個已離職的同事寫死在了代碼里而前一周另一位同事順手給配置中心加了個默認值于是新邏輯和舊邏輯同時生效數(shù)據(jù)被疊加計算了一遍。那一次之后領導和團隊達成了一致這筆技術債不能再拖了。1.2 項目啟動前我先整理了這樣一份問題清單接到重構任務之后我沒有立刻打開編輯器開始改代碼。相反我用三天時間做了一次系統(tǒng)性的問題盤點最后輸出了一份讓整個團隊都沉默的清單。這份清單分成四類死代碼與不可達邏輯通過靜態(tài)分析和運行時日志交叉比對確認大約有 12% 的代碼在過去一年里從未被執(zhí)行過。這些代碼不算致命但它們在每次全局搜索和代碼審查中都會消耗注意力。共享可變狀態(tài)有多個模塊通過同一個全局緩存實例讀寫數(shù)據(jù)而且沒有統(tǒng)一的版本控制任何一邊改了數(shù)據(jù)結構另一邊都會在毫無提示的情況下拿到損壞的數(shù)據(jù)。隱式耦合一個最典型的例子是 A 模塊的日志里會順帶打印 B 模塊的錯誤信息導致日志監(jiān)控系統(tǒng)把 B 的故障歸因到 A 上每次排查都會走彎路。不可測試的上帝函數(shù)某個核心計算函數(shù)有六百多行內部直接操作數(shù)據(jù)庫連接、緩存、消息隊列和外部 HTTP 調用參數(shù)有十一個其中五個是布爾標記位。這個函數(shù)是整個系統(tǒng)最脆弱的部分因為沒人敢給它寫單元測試。這份清單的價值不在于發(fā)現(xiàn)了多少問題而在于讓我們明確了重構的邊界。不可能一次解決所有問題但如果不知道問題在哪任何所謂的技術方案都是在賭運氣。后來團隊內部形成了一個共識任何重構項目的前兩周只做診斷和盤點不允許動業(yè)務代碼。誰動了誰請全組喝咖啡。2. 代碼體檢先看清全局再動手開刀2.1 繪制模塊依賴圖找到真正的核心鏈路正式動手之前我給團隊立了一個規(guī)矩沒有依賴圖的項目重構就是閉著眼在雷區(qū)里跳舞。t3code 的模塊關系已經(jīng)亂到無法靠人腦梳理所以我們借助工具先給系統(tǒng)畫了一張完整的依賴拓撲圖。我用的工具組合是jdepend配合Structure101前者負責做包級別的依賴分析輸出每個模塊之間的依賴關系后者負責把依賴關系可視化成圖并且標出環(huán)的存在——多個模塊相互依賴形成的循環(huán)引用。這一步做完之后整個系統(tǒng)的病灶就像 X 光片一樣清晰了。依賴圖讓我看清了三件用眼睛看代碼根本發(fā)現(xiàn)不了的事有一個審計日志模塊順著依賴箭頭查下來居然間接依賴了幾乎所有的業(yè)務模塊。也就是說每一次寫審計日志的操作都可能觸發(fā)一長串初始化邏輯這就是為什么某些寫操作莫名其妙地慢。名義上的三層架構表現(xiàn)層、服務層、數(shù)據(jù)層早就名存實亡服務層里有大量直接操作數(shù)據(jù)庫表的代碼數(shù)據(jù)層里反而藏著業(yè)務判斷邏輯。核心鏈路其實只有一條但為了照顧十幾種邊緣場景代碼里塞了二十多個 if 分支其中有六個分支從未被任何已知請求觸發(fā)過。依賴圖不光幫我們找到了問題更重要的是幫我們定下了重構的順序。規(guī)則很簡單從依賴關系圖的底層開始改先改那些被依賴最多、但自身不依賴別人的模塊。這樣做的好處是每次改動的影響半徑是可控的不會出現(xiàn)改了一個底層工具類結果三天后才發(fā)現(xiàn)遠端的某個服務被牽連的情況。這里我想多提一句很多人覺得畫依賴圖是浪費時間有這個功夫不如直接開改。但我的親身體會是依賴圖上花掉的一周時間在后期至少省出了三周以上的聯(lián)調時間。尤其是當你需要向老板或者甲方解釋為什么重構需要四個月的時候一張清晰的依賴圖比任何 PPT 都有說服力。2.2 用靜態(tài)分析工具量化壞味道讓問題變得可以討論畫完依賴圖之后下一步是對每個模塊的代碼質量做量化評估。這個階段我用的是SonarQube加eslint針對項目里的 JavaScript 部分和pylint針對 Python 部分。t3code 是典型的多語言混雜項目核心服務用 Java有個輔助腳本模塊用 Python前端管理后臺混著老舊的 jQuery 和新版的 React。量化指標我只關注四個圈復雜度函數(shù)的圈復雜度超過 15 的一律列入重構觀察名單。圈復雜度超過 30 的直接標紅列為最高優(yōu)先級。這個指標能在一定程度上代表代碼的可理解成本——復雜度越高越?jīng)]人敢動。重復代碼率用 SonarQube 自帶的重復代碼檢測跑了一遍結果觸目驚心有將近 18% 的代碼屬于重復片段。最離譜的是同一個日期區(qū)間校驗的邏輯在項目里被復制粘貼了十一份其中三份有 Bug三份又是修過的版本還有五份完全一致。這種重復帶來的問題不只是維護代價高而是你壓根不知道哪個副本是對的。注釋與代碼的匹配度這個需要人工抽查。我隨機抽了 50 個函數(shù)發(fā)現(xiàn)有 12 個函數(shù)的注釋描述的內容和實際邏輯是矛盾的。這種會撒謊的注釋比沒有注釋更危險因為后人會相信注釋然后用錯誤的理解去改正確的代碼。測試覆蓋率整個項目的核心模塊測試覆蓋率不到 25%而且很多測試是光跑不斷言的空殼測試。這種情況下的覆蓋率數(shù)字完全沒有參考價值它只代表了代碼被執(zhí)行過不代表代碼被驗證過。我把這些量化結果整理成了一份報告并且按模塊給出了紅黃綠三個等級的評分。這份報告在項目組里引起了不少討論——有些同事一開始覺得評分不公平但當他們看到自己的模塊被標紅的具體原因時大多還是認賬的。量化的意義在于把我覺得這里寫得差變成了這里有 37 處重復代碼段和 14 處圈復雜度超標的函數(shù)后者才是能推動決策的語言。2.3 確定邊界哪些該重構哪些該重寫哪些該原地凍結代碼體檢做完之后團隊內部開了一次整整一天的評審會主題只有一個對每一塊代碼分類決定是重構、重寫、還是凍結。當時我們定的分類標準是這樣的分類判斷標準t3code 里的實際占比保留并重構邏輯仍在活躍使用結構問題可控約 45%整體重寫邏輯復雜、使用頻率高、且被判定為不可維護約 20%原地凍結仍有調用方但極少變更風險高約 18%刪除已無調用方確認死亡代碼約 12%待進一步確認調用方不明確需要運行時追蹤約 5%這個分類最大的作用是讓團隊停止在垃圾堆里蓋新房的無意義努力。之前總有人試圖在某個亂成一團的函數(shù)內部繼續(xù)加功能現(xiàn)在分類明確后那些代碼要么等重寫要么被凍結誰都不許再往里加邏輯。新增需求一律走新的替代模塊這就是后來我們常說的新舊隔離策略。3. 重構執(zhí)行的三個關鍵階段安全網(wǎng)、主干替換、數(shù)據(jù)遷移3.1 第一階段先織一張不會讓人摔死的安全網(wǎng)重構任何遺留代碼之前最忌諱的事情就是直接動手改代碼。你根本不知道現(xiàn)有邏輯里哪些行為是特性還是Bug——很多業(yè)務依賴的恰恰是那套錯誤的行為。比如 t3code 里有一個對賬模塊邏輯上要求金額精確到分但舊代碼里有個浮點數(shù)直接比較的 Bug導致有些小數(shù)位后四位的偏差被正確地吞掉了。如果重構時把這個 Bug 修掉反而會打破下游對賬系統(tǒng)的預期。所以第一階段的任務是給核心鏈路建立特征測試Characterization Test。這個想法來自 Michael Feathers 的那本《修改代碼的藝術》核心做法很樸素用代碼把當前系統(tǒng)的行為原原本本地固定下來不管它是對的還是錯的。我們選了一個數(shù)據(jù)流最復雜的核心模塊——訂單匯總計算鏈針對它的外部輸入輸出寫了幾百個特征用例。每一個用例的做法是從生產(chǎn)環(huán)境的流量錄制工具我們用的GoReplay抓取真實的請求和響應。把請求-響應對作為一條測試用例固化到自動化測試里。這些用例的意義不是驗證功能正確而是確保重構過程中任何行為偏差都能立刻被發(fā)現(xiàn)。也就是說重構前和重構后同一個請求必須得到完全相同的響應哪怕這個響應在你看來是不合理的。如果有差異測試就會紅我們就得停下來分析為什么。這套安全網(wǎng)在一開始跑的時候每天都會紅一片因為很多依賴的初始化順序是隱性的稍微調整一下模塊加載順序某些數(shù)據(jù)的計算結果就變了。但正是這些紅讓我們知道哪些改動是有副作用的。我強烈建議所有做重構項目的朋友把特征測試放在第一步。哪怕你手頭的時間再緊這個步驟不能省。它就像高空作業(yè)時系在身上的那根安全繩——你會希望它永遠用不上但沒有它你根本不敢往下跳。3.2 第二階段按照依賴圖優(yōu)先級逐層替換主干模塊安全網(wǎng)鋪好之后我們開始按依賴圖的優(yōu)先級從底層往上層逐層替換。這個階段的順序非常關鍵。我們的原則是每一輪替換都只動一個模塊替換完成后跑全量特征測試同時灰度發(fā)布給一部分真實流量觀察對比新舊邏輯的輸出差異確認一致后再進行下一輪。拿最典型的訂單匯總模塊來說替換過程分為四步第一步在新代碼目錄里建立同名模塊框架先把舊的輸入輸出接口原樣拷貝過來保持簽名完全一致。這一步的目的不是為了實現(xiàn)新邏輯而是為了讓新模塊能插拔到舊系統(tǒng)里而不破壞編譯和啟動。第二步把舊模塊里那六百多行的上帝函數(shù)按職責拆成五個邏輯片段參數(shù)解析、數(shù)據(jù)查詢、業(yè)務計算、組裝結果、記錄日志。每一段都用獨立的函數(shù)封裝并且在此期間不改變任何計算邏輯只做結構拆分。第三步把拆分后的新模塊接入主干跑特征測試。這一步通常會暴露很多問題比如舊代碼里有些副作用發(fā)生在函數(shù)中間而拆分后這些副作用的位置變了導致后續(xù)邏輯讀數(shù)異常。遇到這種情況要回到舊代碼里精確定位副作用的觸發(fā)時機然后在新的拆分結構里用顯式調用來模擬而不是靠巧合。第四步灰度對比。我們在生產(chǎn)環(huán)境把 5% 的流量切到新模塊同時把新舊模塊處理同一批請求的結果做字段級對比持續(xù)觀察三天。直到對比結果零差異才把流量逐步提升到 50%、100%。這個階段最需要耐心。平均下來我們每替換一個核心模塊需要一到兩周的時間。中間也會遇到讓人抓狂的問題比如新舊模塊的并發(fā)行為不一致——舊模塊是單線程按順序處理新模塊用線程池并發(fā)處理結果某些共享數(shù)據(jù)被重復初始化導致偶發(fā)錯亂。這類問題只有灰度流量放大到足夠大時才能暴露出來所以每一輪的灰度觀察期都不能壓縮。3.3 第三階段數(shù)據(jù)層遷移與雙寫校驗這是最容易翻車的一步前端模塊替換得七七八八之后最硬核的部分來了數(shù)據(jù)層遷移。t3code 的舊庫用了大量存儲過程完成業(yè)務邏輯有些表的結構設計根本不符合當下業(yè)務的需求比如把標簽直接拼在人名字段里用逗號分隔。這種設計在查詢特定標簽的用戶時只能靠LIKE %tag%去掃全表。數(shù)據(jù)遷移我們采用了比較保守的雙寫方案新表結構設計完成后在遷移窗口開啟前建立新舊兩張表之間的同步管道。業(yè)務寫入操作同時寫舊表和新表讀取操作暫時仍全部走舊表。同步管道跑一周確保新表的數(shù)據(jù)和舊表完全一致。這一周我們每天跑對賬任務對比關鍵字段的數(shù)量和校驗和有差異就立即暫停雙寫并排查原因。確認數(shù)據(jù)一致后把讀取操作切換到新表觀察一周。此時舊表仍然在寫入但沒人再讀了。最后將寫入操作切到新表舊表徹底降級為只讀備份再保留兩個月后下線。雙寫階段看起來簡單實際上處處是坑。我印象最深的是兩張表的字段映射關系里有一個枚舉值含義發(fā)生了變化——舊表里status2表示已取消但在新表里status2表示已退款。這個映射錯誤在數(shù)據(jù)一致性對賬中被抓住了但如果不是提前設計了字段級校驗而不是全表行數(shù)校驗這個問題會在切換讀操作之后才暴露那時候排查成本會翻好幾倍。數(shù)據(jù)遷移給我的教訓是永遠不要相信人眼比對數(shù)據(jù)。哪怕你覺得自己看得很仔細幾百條數(shù)據(jù)或許還能看出來到了幾十萬條量級必須依靠腳本做自動化逐字段對比。我們用 Python 寫了一個簡單的對賬腳本跑一次只需要幾分鐘但它成了整個遷移過程中最讓人安心的工具。4. 重構過程中真實踩過的坑以及對應的規(guī)避方案4.1 坑一過度抽象導致的第二次泥潭重構進行了大約六周之后我們犯了一個當時覺得挺合理、事后追悔莫及的錯誤。有一位同事提出既然這么多模塊都要做類似的日志記錄和權限校驗不如抽一個通用基礎組件出來統(tǒng)一管理這些橫切邏輯。聽起來很對對吧我同意了。結果這個通用基礎組件在兩個星期之內收到了來自七個不同模塊的定制化需求每個模塊都要求它支持自己特有的配置項。為了兼容這些需求組件內部塞滿了 if-else 和可配置開關接口參數(shù)從一開始的三個膨脹到九個。到了第三周這個組件的復雜度已經(jīng)超過了它想取代的那些分散代碼的總和。后來我們痛定思痛把這個組件直接拆掉退回每個模塊自帶輕量實現(xiàn)。拆掉之后系統(tǒng)反而更清爽了。這個教訓我記到今天重構中的抽象必須源于至少三個以上的真實調用場景而不是基于將來可能有需要的預判。在代碼里預防未來大多數(shù)時候只是在制造現(xiàn)在的復雜度。與其用一個過度設計的通用組件不如允許暫時的重復等真正看到重復的規(guī)律時再做抽象。4.2 坑二并行發(fā)布時新舊邏輯的偶發(fā)錯亂第二坑發(fā)生在數(shù)據(jù)遷移接近尾聲的時候。由于新舊兩套邏輯在線上并行運行我們需要在代碼里通過配置開關來控制流量切換。有一天晚上配置中心推送了一個新配置同一個服務實例里新舊兩個模塊同時收到了配置更新事件結果其中一個模塊按照新配置走了新邏輯另一個模塊還沒來得及更新仍在跑舊邏輯——兩套邏輯同時對同一批數(shù)據(jù)動了手險些造成線上數(shù)據(jù)污染。排查原因后發(fā)現(xiàn)這不是配置中心的問題而是我們自己的代碼在切換邏輯時沒有做原子化處理。正確的做法應該是在每次請求進來的時候根據(jù)請求的唯一 ID 計算一個 hash確定它走舊邏輯還是新邏輯并且在整個請求生命周期內保持一致。我們最初用的是全局開關配額的切換無法保證同一請求的前半段和后半段讀到一致的開關狀態(tài)。這個問題的規(guī)避方案其實不復雜任何灰度切換都必須做到請求級一致性而不是配置級一致性。一個請求一旦被標記為走新邏輯那么它內部涉及的所有子調用、數(shù)據(jù)庫讀寫、消息投遞都必須遵循新邏輯的規(guī)則不允許在中間某個環(huán)節(jié)因為配置更新而跳到舊邏輯去。4.3 坑三人員交接期知識斷層如何彌補重構進行到一半的時候團隊里最熟悉舊系統(tǒng)的兩位老同事之一提出了離職。這件事一度讓項目陷入停滯因為很多舊邏輯的知識只存在他的腦子里而文檔和代碼都沒有完整記錄。這件事讓我意識到重構項目里最脆弱的資產(chǎn)不是代碼而是活的知識。從那之后我們強制推行了兩條制度第一任何模塊的重構都必須由兩個人共同負責一個熟悉舊邏輯一個擅長新代碼。兩個人的組合不能是一個純新手配一個純專家必須有交叉。這樣即使走了一個人另一個人也能在兩周內把關鍵知識傳給接手者。第二每周必須開一次行為差異評審會在評審會上負責每個模塊的人要用大白話講解這個模塊重構前和重構后的行為差異包括那些沒有在代碼里體現(xiàn)的隱性規(guī)則。這些講解被錄音并整理成筆記存到了項目知識庫里。這套機制沒辦法讓知識 100% 傳承但它把依賴某個人的記憶變成了依賴團隊的過程。后來項目過了危機期我們回頭看這可能是比技術重構本身更有價值的制度建設。5. 從 t3code 沉淀出的可復用清單留給以后的自己5.1 重構成本評估表什么時候該重構什么時候該重寫經(jīng)歷 t3code 之后我最大的收獲是不是所有爛代碼都值得重構。有些代碼爛到了骨頭里重構的成本比推倒重寫還要高。為了快速做這個判斷我整理出了下面這張評估表后續(xù)每遇到類似項目都會先過一遍評估維度傾向重構傾向重寫代碼調用范圍核心鏈路的一部分被使用幾乎所有模塊都在依賴它行為確定性有明確的輸入輸出規(guī)格行為模糊沒人說清所有副作用測試基礎已有部分可用測試或能快速補充幾乎沒有測試且代碼不可測試數(shù)據(jù)結構復雜度數(shù)據(jù)結構穩(wěn)定字段少有變化表結構疾病纏身字段語義混亂業(yè)務價值業(yè)務邏輯仍然清晰且活躍業(yè)務已被邊緣化邏輯無人理解如果評估結果是重寫那就不要猶豫不要嘗試在舊代碼上面修修補補。如果評估結果是重構那就嚴格按照安全網(wǎng)、依賴圖、分層替換的節(jié)奏來推進。最怕的就是既不重構也不重寫只靠打補丁度日——那是真正的慢性死亡。5.2 團隊協(xié)作層面的節(jié)奏控制重構項目的失敗很多時候不是因為技術難而是因為節(jié)奏失控。t3code 項目里我們定了幾條紀律每條都來源于一次或多次真實的教訓每兩周必須有一個可演示的成果。不管這個小成果是拆分了一個函數(shù)、減少了一個隱式耦合還是新建了一個能跑的模塊?？裳菔镜某晒茏寛F隊保持信心也能讓管理層看到進展。每一次代碼評審重構項目必須使用比平時更嚴格的審查標準。不是只是能跑就行而是要求每個新函數(shù)不超過 40 行、每個模塊不允許出現(xiàn)循環(huán)依賴、每個公共接口必須有真實調用方。允許犯錯的預算要提前劃定。我們當時規(guī)定重構期間允許出現(xiàn)最多兩次需要回滾的嚴重事故超過這個次數(shù)就必須暫停重新評估進度和方案。給意外留出預期意外真的來了才不會把團隊心理防線擊穿。5.3 重構完成之后觀測體系才算真正的驗收很多人以為重構上線就算完了其實恰恰相反重構上線的那一刻監(jiān)控和觀測才真正變得重要。t3code 重構完成后的前兩個月我們搭建了一套完整的觀測體系用來持續(xù)驗證重構的成果。核心指標有三類穩(wěn)定性指標接口錯誤率、超時率、熔斷次數(shù)。重構后的系統(tǒng)如果穩(wěn)定性不升反降說明還有隱藏問題。性能指標TP50、TP95、TP99 響應時間。重構不能只是代碼好看了必須體現(xiàn)在關鍵業(yè)務鏈路的響應速度上。交付效率指標從需求到上線平均耗時、線上缺陷數(shù)。這個指標最能反映開發(fā)體驗的真實改善——如果重構只是代碼結構變好但團隊交付速度沒變那這個重構的商業(yè)價值就需要重新審視。我們還專門搭了一個重構前后對比看板把上述指標按時間軸放在一起展示。在重構完第一個月的時候TP99 還有一些抖動因為某些舊的定時任務仍然在跑和新的數(shù)據(jù)管道產(chǎn)生了資源競爭。我們順著看板上的異常點往下排查最終清掉了幾條已經(jīng)不再需要的定時任務系統(tǒng)才真正穩(wěn)定下來。這個看板直到項目結束后的半年都還在持續(xù)運行因為它已經(jīng)變成了團隊日常巡檢的默認工具。關于 t3code 這個項目我能寫出來的經(jīng)驗大概就是這些。最后再補充一句事后復盤的時候團隊里很多人都在感慨如果當時沒有堅持先做診斷、再定邊界、然后織安全網(wǎng)這三步而是直接拿著 IDE 沖進代碼里開改結局很可能是把一套還能勉強運轉的系統(tǒng)攪成一鍋更稠的粥。重構這門手藝慢就是快、穩(wěn)就是快這是我在這四個月里最深的體會。