有一次我們在讓 AI 對專案進行 code review 時，意外發現了一個潛伏已久的問題：系統中存在超過 30 個錯誤代碼，每個功能模組各自定義自己的錯誤類型，三種截然不同的拋出方式在同一套程式碼中並存。更糟糕的是，這些問題是在系統規模已經相當可觀的時候才被發現的。

要怎麼整治一個運轉中的複雜系統，而不讓它在過程中崩潰？這個問題促使我們發展出一套完整的大規模系統遷移方法論。

一切始於複雜度爆炸的警示信號

那次 code review 暴露了三個互相強化的問題。

第一個是錯誤分類的過度細化。30 多個錯誤代碼聽起來很精確，但精確和有用是兩回事。開發者需要記憶大量代碼，當新人加入或功能邊界模糊時，維護成本以幾何級數上升。過度分類是在創造新的複雜性。

第二個是效能聲稱與現實的落差。某些模組在熱路徑中進行運行時字串拼接，累積出不小的效能成本。但更危險的是，沒有人有真實的測量數據，只有樂觀的估計。當我們最終開始測量，數字讓人警醒。

第三個是跨模組的一致性缺失。不同功能模組使用不同的錯誤處理模式，開發者在模組間切換時面臨隱形的學習成本。問題在於標準從未真正統一過。

1// 同一系統中並存的三種錯誤處理風格
2// 模組 A：拋出字串
3throw 'OPERATION_FAILED';
4
5// 模組 B：自訂 Exception 類別
6throw CustomException('MODULE_B_ERROR', details);
7
8// 模組 C：使用通用 Exception
9throw Exception('Generic error message');

每種模式都需要不同的測試策略，跨系統傳輸時序列化邏輯也得各自處理。維護成本不是線性增長，是指數增長。

從單點修復到系統性解決的思維轉變

面對這樣的混亂狀態，我們最初的直覺反應是逐一修復。修模組 A、修模組 B、再修模組 C。這個路子走不通。局部最佳化往往導致全域最差化——修了一處，另一處又冒出新的不一致。

正確的思路是：分散的問題需要統一的解決方案。

但統一不代表一次性全部替換。系統在運行，使用者在使用，我們無法承受完整重寫帶來的風險。這裡的核心設計挑戰是：如何在不停機的前提下，從舊系統平穩遷移到新系統？

答案是雙軌並行的過渡策略。

橋接模式：零中斷遷移的關鍵

我們設計了一個橋接層，讓舊系統和新系統可以同時運行。這個橋接層支援四種模式：

  • 向後相容優先：新系統呼叫舊格式，確保現有整合不中斷
  • 新系統優先：新的程式碼優先使用新格式，舊代碼仍可通過橋接運作
  • 雙系統驗證：同時在兩套系統中驗證結果，用於關鍵期的安全確認
  • 逐步遷移：按功能模組分批切換，控制每次的變更範圍

這個設計讓遷移工作可以分批進行、隨時暫停，任何問題都不會擴散到整個系統。

適配器層：零語意損失的精確映射

橋接模式解決了「如何並行」的問題，適配器層則解決了「如何轉換」的問題。

每個功能模組都有專屬的適配器，負責將舊錯誤格式精確映射到新格式。這裡的關鍵字是「精確」。每個舊錯誤代碼都對應一個明確的新類型，包含錯誤嚴重程度和建議的恢復策略。

 1// 模組特化適配器：每個映射關係都是顯式定義的
 2static const Map<String, ErrorMapping> errorMapping = {
 3  'OLD_VALIDATION_ERROR': ErrorMapping(
 4    newType: 'VALIDATION_ERROR',
 5    severity: Severity.moderate,
 6    recovery: Recovery.userInputRequired,
 7  ),
 8  'OLD_NETWORK_TIMEOUT': ErrorMapping(
 9    newType: 'TIMEOUT_ERROR',
10    severity: Severity.high,
11    recovery: Recovery.automaticRetry,
12  ),
13};

沒有模糊映射，沒有「差不多」的近似替換。如果一個舊錯誤代碼找不到對應的新類型，系統會明確報錯，而不是靜默地做出錯誤的轉換。這個設計確保了語意的完整保留。

可量化的改善：我們得到了什麼

這套方法論在實際專案中得到了驗證，結果是具體可測量的。

錯誤類型從 30 個以上精簡到 15 個核心類型，減少了一半。測試案例統一整理後，607 個測試全數通過。效能方面，錯誤建立速度提升了 2 到 10 倍，記憶體使用量減少了 35% 到 40%。

更難量化但同樣重要的是：新人上手時間從兩週縮短到三天。當所有人都用同一套模式思考和工作，很多摩擦就消失了。

成功遷移的三個關鍵因素

第一是充分的前期準備。在動手之前，我們花了相當多的時間理解現狀：現有系統的哪些部分相互依賴？哪些模組的改動風險最高？有哪些隱性的使用約定沒有被文件化？這些問題如果在遷移過程中才發現，代價會大很多。

第二是自動化優先的工具支援。能夠自動化的絕不手工處理。這不只是效率問題，更是正確性問題——人工操作在大量重複工作中不可避免地會出錯。我們為每個遷移步驟建立了自動化工具，並配套多層次的驗證機制。

第三是清晰的責任與溝通結構。遷移涉及的變更範圍廣，如果責任不明確，問題很容易在模組邊界消失。我們確保每個人都清楚自己負責的範圍，以及問題需要向誰回報。

四個常見陷阱，以及如何避開

我們在過程中也走過彎路，或是預見了潛在的彎路並提前避開。這四個陷阱值得特別提醒。

第一個是低估複雜度。表面上看起來只是「換一種寫法」的遷移，往往涉及語意上的細微差異和大量的邊界情況。充分的現狀分析，包括讓系統用現有代碼跑一遍完整的測試套件，是不能省略的步驟。

第二個是忽視相容性。急於達到目標狀態而忽略過渡期需求，是許多遷移失敗的直接原因。向後相容性策略必須在一開始就設計好，而不是在遇到問題時才臨時想辦法。

第三個是工具過度依賴。自動化工具強大，但有能力邊界。我們見過團隊在工具無法處理的邊界情況上卡住很久，因為他們沒有準備人工處理的備案。正確認識工具的能力邊界，同時準備人工介入的方案，是務實的做法。

第四個是缺乏回滾計畫。只考慮成功情況的遷移計畫是不完整的。每個階段都應該有明確的回滾方案，並且在實際執行前就演練過。當問題真的發生時，你不會有足夠的時間從零開始想恢復方案。

遷移哲學：四個設計原則

統一性優於客製化。一致的介面和行為模式，在長期的維護成本上遠勝於為每個特殊需求提供特化方案。

測量優於估計。效能是否真的改善了？覆蓋率是否真的提高了？在有真實數據之前，任何聲稱都只是猜測。建立可測量的指標，並在遷移前後都進行測量。

漸進優於激進。可控的小步前進，比一次性的大幅重寫更安全，也更容易發現問題。漸進遷移讓我們可以在不確定性中保持前進，同時把風險控制在可管理的範圍內。

自動化優於手工。工具化的流程不只是更快，也更可靠。把判斷和轉換邏輯編碼進工具，讓錯誤在流程中被機制攔截，而不是依賴人工審查。

結語

大規模遷移讓人感到畏懼，因為技術風險和組織風險同時存在。但核心思路並不複雜：統一解決分散的問題，用橋接和適配器確保過渡期安全，用可測量的指標確認改善是真實的。

有這套流程在手，「看起來很危險」就變成了「可以管理的挑戰」。