用 Codex 重構老舊複雜代碼不改壞線上功能:先補特徵測試(Characterization Test)再分步抽離實戰

老舊業務代碼邏輯纏繞、缺少單測,直接讓 Codex 重寫極易改壞線上隱性邏輯。本文整理特徵測試(Characterization Test)配合分步抽離與 Git 檢查點的實戰流程,附 3 段提示詞與審查要點。

NNathaniel bigo··原創首發·AI 輔助撰寫
10 分鐘讀完
資料核對於 2026-11-19 · 依據官方文檔與公開資料整理 Plus 帳號

結論先說

  1. 老代碼重構的第一步不是改業務代碼,而是補特徵測試(Characterization Test)。特徵測試不評判舊邏輯「對不對」,而是忠實記錄當前代碼在各類輸入下的真實返回值、拋錯類型和副作用,為後續改動拉起安全網。
  2. 嚴格區分「補測試提交」與「純結構重構提交」。先在零業務改動的基線上讓特徵測試全部通過並提交到 Git,再要求 Codex 在不修改測試斷言的前提下分步抽離函數或模組。
  3. 盤點階段優先開只讀沙箱。用 codex --sandbox read-only 讓模型先通讀調用鏈、全局變量與隱藏副作用,輸出依賴地圖後再進入編輯模式(權限邊界詳見 /guides/codex-permissions-sandbox)。
  4. 每次只做一種結構變換,小步提交配合 /review。把「提取純函數」「替換魔法值」「解耦外部接口調用」拆成獨立步驟,每步跑通測試再用本地審查確認未混入行為改動。
  5. 長上下文多輪重構消耗較高額度。若國內缺少外幣卡或現有檔位配額吃緊,可在本站自助選購 ChatGPT Plus 充值 或配額更高的 ChatGPT Pro 充值,團隊多人協作可了解 ChatGPT Business 團隊定製。

Codex 遺留代碼安全重構五步流程

圖:本站根據 OpenAI Codex 官方文檔:Codex CLI 及工程實踐整理的示意圖

本文根據 OpenAI Codex 官方文檔《Codex CLI》《Command line options》《Custom instructions with AGENTS.md》及遺留代碼重構工程實踐整理,資料核對於 2026-11-19。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 OpenAI 官方網站。

適用於誰

  • 接手缺少文檔與單元測試的祖傳模組,既要拆解千行大函數、又擔心破壞線上隱性分支的後端與前端開發者;
  • 曾讓 Codex 一次性重構整個文件,結果出現邊緣場景迴歸、差異過大難以代碼審查的工程師;
  • 希望建立可復現、可隨時回滾的 AI 輔助重構標準流程的研發團隊。

一、為什麼直接讓 Codex 重寫老代碼容易改壞線上

許多老舊核心文件(如訂單結算、權限判定、報表彙總)歷經多年熱修,表面充滿重複判斷和過深嵌套,但內部往往埋着兼容歷史數據的隱性分支——例如把 null 和空字符串視為不同含義、依賴特定字段的校驗順序、或順手修改了入參對象本身。

如果直接對 Codex 說「幫我把 orderService.ts 重構得更簡潔」,模型通常會出於代碼審美做出三類危險操作:一是合併它認為多餘的條件判斷,悄悄改變了極端輸入的返回結果;二是順手升級接口簽名或重命名導出符號,導致未在上下文裏的外部調用方報錯;三是一次生成數百行差異,代碼審查者根本無法逐行核驗等價性。

因此,安全使用 Codex 重構老代碼的核心思路,是把「探索與鎖定現狀」和「調整代碼結構」徹底拆開。

一步重寫與特徵測試分步抽離對比

圖:本站結合工程維護經驗整理的對比示意圖

二、階段一:只讀盤點依賴並補齊特徵測試

在動任何一行生產代碼之前,先保證 Git 工作區乾淨,並新建獨立分支。如果不熟悉整個倉庫結構,可先參考 /guides/codex-onboard-unfamiliar-project-agents-md 完成項目規則摸底。

1. 用只讀模式繪製行為與副作用清單

在項目根目錄啟動只讀會話(避免模型順手改動文件):

bash
codex --sandbox read-only

在會話中發送第一段提示詞,鎖定被重構模組的外部邊界:

text
請只讀取 src/billing/calcDiscount.ts 及其直接調用方,不要修改任何文件。
請整理一份行為與副作用清單,包含:
1. 所有外部調用入口和參數類型(含可空、缺省與異常入參);
2. 函數內部的全部條件分支、邊界閾值與拋錯條件;
3. 是否讀寫全局變量、環境變量、系統時間、數據庫或修改入參對象本身。

2. 讓 Codex 生成特徵測試並鎖定當前行為

拿到清單後,回到常規工作區模式(建議保留審批確認),按「只新增測試文件、不碰生產源碼」的原則補齊特徵測試。更多測試生成細節也可參考 /guides/codex-write-tests-and-run。

text
請為 src/billing/calcDiscount.ts 編寫特徵測試(tests/billing/calcDiscount.char.test.ts)。
硬性要求:
1. 禁止修改 src/ 下的任何生產代碼,即使發現疑似歷史缺陷也先按當前真實輸出斷言,並在註釋中標註「疑似歷史行為待確認」;
2. 覆蓋正常路徑、空值與零值邊界、疊加折扣優先級、異常拋錯類型及入參是否被原地修改;
3. 如果依賴系統時間或外部客戶端,僅對外部 I/O 邊界做最小隔離;
4. 編寫完成後運行測試命令,確認所有用例在未改動源碼時 100% 通過。

核對要點:人工逐條檢查測試斷言,確認用例真正觸發了源碼中的複雜分支,而不是簡單模擬返回值。確認全部綠燈後,立即執行一次獨立提交,例如 test(billing): add characterization tests for calcDiscount。

訂閱與帳號準備提示:對千行老代碼做依賴分析、補測與多輪重構會持續讀取多文件上下文,容易觸發額度上限(計算規則見 /guides/codex-usage-limits)。重度開發建議升級 ChatGPT Pro 5x iOS 可覆蓋檔 或 ChatGPT Pro 5x 信用卡不可覆蓋檔;新註冊帳號若在手機號環節遇到阻礙,可參考 Codex 註冊手機驗證服務。

三、階段二:單步結構抽離與檢查點驗證

特徵測試提交入庫後,每一輪重構都遵循「單目標 → 跑測試 → 看差異 → 小步提交」的固定閉環。本站建議單次重構提交的有效業務變更控制在 150 行以內,方便逐行核對。

推薦的拆解順序(由安全到複雜)

  1. 隔離外部依賴(引入接縫):先把時間獲取、配置讀取、日誌寫入等隱式依賴改成可選參數注入,保持舊簽名兼容。
  2. 提取無副作用純函數:把深層嵌套的折扣計算、金額舍入、狀態映射抽成獨立純函數,主流程只留清晰編排。
  3. 收斂重複判斷與魔法數字:替換為語義化常量和衛語句(Early Return),降低圈複雜度。
  4. 驗證並清理:確認所有特徵測試及原有集成測試綠燈後,再單獨開一次任務討論是否修復之前標註的「疑似歷史缺陷」。

單步重構提示詞模板

text
基於已通過的特徵測試 tests/billing/calcDiscount.char.test.ts,對 src/billing/calcDiscount.ts 執行第一步重構:
目標僅限:將「會員等級折算」和「滿減階梯計算」提取為同文件內的兩個純函數。
嚴格約束:
1. 禁止修改任何已有測試文件與測試斷言;
2. 禁止改變導出函數簽名、返回字段名與異常類型;
3. 不要順手重構文件其餘部分或修改無關文件;
4. 修改完成後自動運行全部相關測試並展示 git diff --stat。

每次測試通過後,在 Codex CLI 中運行 /review 做一次自動代碼覆核(用法詳見 /guides/codex-code-review),確認沒有夾帶邏輯語義變化再執行 git commit。若某一步把測試改紅且定位困難,直接 git checkout -- . 回到上一個乾淨提交,比在改亂的現場繼續讓 AI 補救省時得多。

常見問題

問:老代碼本身確實有 Bug,特徵測試階段要不要順手一起修了?

答:不建議在結構重構中夾帶 Bug 修復。特徵測試階段應忠實鎖定線上現行行為,把可疑點記錄成註釋或工單;等結構拆清、所有測試穩定通過後,再另開獨立提交專門修 Bug 並更新對應預期斷言,這樣上線後若出現問題能立刻區分是重構引入還是業務改動導致。

問:如果老代碼強依賴全局單例或靜態數據庫連接,特徵測試跑不起來怎麼辦?

答:先做最小「接縫改造」(如在文件末尾增加可選依賴注入參數,預設仍指向原有單例),保證老調用方零修改即可編譯運行,再用測試傳入輕量內存替身跑通特徵測試,之後再逐步抽離核心邏輯。

問:國內沒有外幣信用卡,或者公司研發團隊需要開票報銷,怎麼開通高配額 ChatGPT / Codex 訂閱?

答:可通過本站 AI 會員充值總覽 按需選擇 ChatGPT Plus、ChatGPT Plus 自助卡密 或更高額度的 ChatGPT Pro,支持支付寶、微信支付與 AlipayHK,採用卡密自助兌換(無需提供帳號密碼)或客服協助,支持開具增值稅發票;多人團隊可直接在站內諮詢 Business 團隊定製方案。實時價格以頁面顯示為準,售後遵循掉訂閱按剩餘天數折退、封號不在質保範圍的規則。

相關教學

參考資料

  • OpenAI Codex 官方文檔:Codex CLI — https://learn.chatgpt.com/docs/codex/cli
  • OpenAI Codex 官方文檔:Command line options — https://learn.chatgpt.com/docs/developer-commands
  • OpenAI Codex 官方文檔:Custom instructions with AGENTS.md — https://learn.chatgpt.com/docs/agent-configuration/agents-md
  • OpenAI Codex 官方文檔:Non-interactive mode — https://learn.chatgpt.com/docs/non-interactive-mode

Nathaniel 的更多內容

  1. 01

    獨立開發者用 ChatGPT + Codex 跑通產品全流程:市場驗證、PRD、原型到代碼上線覆盤清單

    單人做獨立產品最容易陷入「閉門寫兩個月代碼上線零用戶」或「AI 寫到一半目錄越改越崩」。本文整理「ChatGPT 負責市場驗證、PRD 與覆盤 + Codex 負責工程實現與測試」的五階段雙軌流程,附起手提示詞與 7 項上線覆盤清單。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成規範文件命名規則、整理混亂目錄樹與合併零散發票抬頭清單腳本

    面對滿桌面的「新建文件夾」「最終版2」和上百張零散電子發票,手工改名抄台帳耗時又容易漏重。本文分享先脫敏取樣、再用 ChatGPT 生成帶預演和回滾日誌的本地 Python 腳本,離線安全完成目錄整理與發票抬頭合併去重的實戰流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外電郵營銷(EDM)受眾分層文案、A/B 主題行測試與防進垃圾箱自檢

    做海外獨立站或出海 SaaS 電郵營銷(EDM),最怕千人一面群發被直接送進垃圾箱。本文結合 Gmail/Yahoo 批量發件人規範,梳理用 ChatGPT 設計受眾分層文案、批量生成 A/B 主題行矩陣並開展發前垃圾詞與合規自檢的實戰提示詞。

    ChatGPT0
  4. 04

    用 ChatGPT 寫 Notion Formula 2.0 公式、Obsidian Dataview 查詢與 Airtable 自動化腳本

    給 Notion 數據庫寫多條件 Formula 2.0 公式、給 Obsidian 寫 Dataview 動態看板,或在 Airtable 裏寫自動化腳本,經常因為一個小括號或類型不匹配報錯半天。本文整理三大工具的通用上下文喂料規範與三套直接可複製的生成提示詞。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 處理複雜 JSON / YAML / XML 字段映射、格式轉換與校驗規則編寫實戰

    對接第三方 API、遷移 Kubernetes 配置或解析政企 XML 報文時,手工對照幾百行嵌套字段既慢又容易漏掉空值與類型邊界。本文整理用 ChatGPT 完成字段映射表梳理、生成確定性轉換腳本以及編寫 JSON Schema / Pydantic / XSD 校驗規則的實戰流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 準備本科/碩士畢業論文答辯:提煉答辯 PPT 結構、模擬導師犀利追問與 3 分鐘自述稿

    畢業論文寫完後,要在 3–5 分鐘內講清研究價值並頂住答辯評委的連環追問並不輕鬆。本文整理在嚴格遵守高校學術規範的前提下,用 ChatGPT 提煉答辯 PPT 結構、打磨 3 分鐘口語自述稿並開展模擬導師犀利追問的排練流程與提示詞。

    ChatGPT0

同產品的其他教學

  1. 01

    用 ChatGPT 整理家庭裝修預算明細、隱蔽工程驗收清單與主材優缺點對比表實戰

    第一次裝修面對幾十頁施工報價單、密密麻麻的水電防水隱蔽項目與五花八門的主材參數,極易踩坑增項。本文梳理用 ChatGPT 審查裝修報價漏項、生成帶公式的預算明細表、定製工地隱蔽工程驗收單與主材對比表的實戰提示詞。

    ChatGPT0
  2. 02

    用 ChatGPT 做費曼學習法讀書共讀:反向追問檢驗自己是否真讀懂專業書籍與整理書單筆記

    讀完一本專業硬書常感覺「合上書就忘」,直接讓 AI 概括全書又容易產生懂了的錯覺。本文介紹用 ChatGPT 結合 Study Mode 與費曼學習法做反向追問共讀,通過通俗複述、挑刺盲區到沉澱書單卡片的完整流程與提示詞。

    ChatGPT0
  3. 03

    用 ChatGPT 做外貿產品多語種目錄、展會邀約與客戶跟進節奏表(附脫敏與本地化提示詞)

    做外貿展會與海外推廣時,手工翻譯十幾款產品目錄費時且容易留下一堆中式英文,展後客戶跟進也常缺節奏。本文梳理用 ChatGPT 先脫敏建術語庫、再批量產出多語種目錄、展前邀約函與展後 21 天跟進節奏表的實戰流程與提示詞。

    ChatGPT0
  4. 04

    用 ChatGPT 寫高質素技術專欄文章、開源項目 Release Notes 與版本更新日誌實戰

    讓 AI 直接憑空寫技術文章容易滿篇空洞套話,直接甩 Git 記錄寫更新日誌又常常漏掉破壞性變更。本文整理用 ChatGPT 結合真實代碼片段、壓測數據與 PR 摘要,高效產出深度技術專欄、GitHub Release Notes 與 CHANGELOG 的實戰工作流。

    ChatGPT0
  5. 05

    用 ChatGPT 做產品用戶訪談紀要編碼、提煉高頻痛點需求池與 RICE 優先級打分實戰

    手頭攢了十幾份用戶訪談逐字稿,手工貼便利貼歸納痛點耗時又容易帶入主觀偏見。本文分享用 ChatGPT 完成脫敏檢查、逐份開放式編碼、跨樣本聚類高頻痛點並搭建 RICE 優先級打分表的 5 步實戰流,附可直接複製的三段核心提示詞。

    ChatGPT0
  6. 06

    ChatGPT 網頁版上載超過 10 個文件或回形針附件按鈕變灰怎麼辦:打包合併與配額限制排查

    在 ChatGPT 網頁版批量分析文檔時,常遇到一次選超 10 個文件被攔截或輸入框回形針按鈕變灰。本文依據 OpenAI 文件上載與存儲說明,梳理 6 類常見報錯的分流排查法,提供 ZIP 打包、本地合併與 Projects 複用方案及可直接複製的解包提示詞。

    ChatGPT0

0 條評論

登入 後參與評論

還沒有評論,來搶沙發~