重構 on Tarragon

設計驅動重構方法論 - Domain Root 檢查與技術債務清理實戰

Wed, 04 Mar 2026 00:00:00 +0000

在一次常規的 Phase 4 重構評估中，我們打開了 library_domain.dart 這個檔案，發現它足足有 600 多行，裡面混雜著聚合根、Value Object 和服務類別，彼此糾纏在一起。更糟的是，統計書籍狀態的函式正在使用根本不存在的枚舉值——程式編譯不過，但那些錯誤已經在那裡不知多久了。

如果在重構之前沒有系統性地理解設計意圖，我們很可能會把問題修錯方向，或者在「修好」一處的同時破壞了其他地方。

於是我們建立了一套方法論，把設計文件的閱讀和驗證，放在所有重構動作的最前面。

為什麼設計文件要在程式碼之前讀

看到壞味道就處理、看到重複就提取——傳統重構路線沒有問題，但對 Domain 層的核心實體來說，這樣做有個盲點：我們可能根本不清楚這段程式碼的業務意圖。

不清楚「Library 為什麼要追蹤 SourceType 而不是 ReadingStatus」，技術上漂亮的重構可能在業務上悄悄引入錯誤。設計驅動重構的前提是：所有重構決策必須基於現有的設計文件，而不是單純從程式碼的技術形狀來判斷。

驗證流程

第一階段：設計文件檢查

在動任何一行程式碼之前，我們先回頭讀文件。閱讀順序很重要：從需求規格出發，再到用例說明，再到 UI 設計規格，最後到錯誤處理設計。

這個閱讀順序的邏輯是：先確立業務目標（需求規格），再理解使用場景（用例），再看 UI 層如何呈現（UI 規格），最後檢查系統如何應對異常（錯誤處理）。這樣走一遍，Domain Root 在整個系統中扮演的角色就會變得清晰。

以 Library 實體為例，文件告訴我們它需要支援不同來源類型的書籍統計——實體書、電子書、借閱書各有不同的計算邏輯。但程式碼裡用的是 ReadingStatus 枚舉，而且還在使用 'digital'、'borrowed' 這些根本不在枚舉定義裡的值。這不是設計問題，這是實作根本跑錯了方向。

第二階段：測試覆蓋率分析

讀完文件之後，我們看測試。測試是另一種形式的設計文件，它告訴我們這段程式碼「被期待如何運作」。

這個階段最常發現的問題是測試的方向跑偏了。我們在 book_test.dart 裡發現，它引用了 flutter_test 套件，但 Domain 層的單元測試根本不應該依賴 Flutter 框架——這意味著這些測試在純 Dart 環境中根本無法執行，CI 流程也因此產生了盲點。

此外還有大量被 skip 的測試。每個 skip 都是一個未被驗證的業務假設，累積起來就是風險。

第三階段：程式實作驗證

前兩個階段讓我們建立了對「設計意圖」的理解。第三階段才是真正對照程式碼，逐一確認哪裡偏離了設計。

這個階段的關鍵產出是一份問題清單，而且每個問題都有分類：是類型系統錯誤、是架構違規、是技術債務，還是可維護性問題。分類決定了後續的修復優先級。

問題分類與修復優先級

我們在實際的 Book 和 Library 重構中，識別出了四類問題，按照影響範圍決定修復順序。

類型系統錯誤優先級最高。 使用不存在的枚舉值、把 String 傳給期望強類型的參數，這類問題一旦進入生產環境就是執行時崩潰。我們把所有這類問題排在第一批處理。

異常處理不統一緊隨其後。 Library 實體裡有自定義的 DuplicateBookException，但整個專案其他地方都統一使用 AppError 體系。這種不一致性不只是風格問題，它讓錯誤處理的呼叫端無法用一致的方式應對。

技術債務屬於第二優先級。 最典型的例子是 author 欄位使用 String 類型。這在功能上可以運作，但它限制了後續的多作者支援、譯者解析和富文字搜尋能力。這類問題有明確的演進路徑，但不是緊急的。

可維護性問題排在最後。 包括缺乏需求追蹤編號的註解、業務規則說明不足等。這些問題不影響功能，但它們是技術債務的溫床——當下一個人來維護這段程式碼時，他沒有足夠的上下文。

幾個具體的重構模式

類型系統修正

問題很常見：用字串或錯誤的枚舉值來做判斷，而不是使用正確的類型。

修正前：

1books.where((book) => book.readingStatus == 'digital')

修正後：

1books.where((book) => book.source.type.isDigital)

表面上看這只是換了一個屬性，但背後的意義完全不同：前者依賴字串的巧合匹配，後者依賴類型系統的保證。

異常處理統一

自定義異常類別散落在程式碼各處，是一種常見的技術債務模式。

修正前：

1throw DuplicateBookException('message', bookId: id, title: title);

修正後：

1return OperationResult.failure(
2  BusinessLogicError(
3    message: 'message',
4    businessRule: 'BOOK_DUPLICATE_PREVENTION',
5    code: ErrorCodes.duplicateBook,
6    context: {'bookId': id, 'title': title},
7  ),
8  'userMessage'
9);

這個轉換不只是換個類別，它同時把拋出異常改成了回傳結果——這是更適合 Domain 層的錯誤傳遞方式，讓呼叫端可以明確地決定如何處理每種失敗情況。

Value Object 重構

把 String 提升為 Value Object 是一個需要仔細計畫的重構，因為它涉及所有使用處的同步更新。

修正前：

1final String author;

修正後：

1final BookAuthor author;

關鍵在於轉換策略要設計好：BookAuthor.fromString(stringValue) 負責從舊有字串資料遷移，bookAuthor.displayValue 負責在需要字串輸出的場合提供相容性。有了這兩個轉換點，才能在保持向後相容性的前提下完成遷移。

分階段執行，每段必驗

每個修復階段結束後都要驗證：dart analyze 無錯誤、核心功能正常運作、API 介面保持不變。我們曾經跳過這個步驟，結果後續階段的問題疊加在一起，讓除錯變得極其困難。

從這次重構中得到的

這次對 Book 和 Library 兩個 Domain Root 的重構，最終涉及了 35 個以上的檔案，把 24 個編譯錯誤降到了零，並且完整建立了需求追蹤的 REQ-LIB-XXX 編號體系。

收穫更大的是設計文件優先讓我們避開了幾個危險方向。如果直接看到 author 是 String 就去重構，可能會建出不符合業務需求的 Value Object。如果直接看到自定義異常就去統一，可能會在類型系統問題還沒修好的基礎上做錯誤的抽象。

下次面對需要重構的模組時，先花 15 分鐘讀相關設計文件，再決定從哪裡下手。那 15 分鐘很可能讓你避開一個需要幾個小時才能發現的方向錯誤。

程式碼自然語言化撰寫方法論

Wed, 04 Mar 2026 00:00:00 +0000

程式碼不是寫給電腦看的，是寫給人類讀的。電腦只管執行，人類才要維護。

認知負擔：一切的出發點

人類工作記憶有限，大約一次只能處理七個項目（Miller’s Law）。看到縮寫要在腦中展開、看到模糊詞要猜測含義、看到長函式要分段記憶——這些都是認知負擔。

自然語言化的目標很簡單：讓程式碼像讀文章一樣自然，把讀者的認知資源留給理解業務邏輯，而不是解碼程式碼本身。

第一原則：命名要能直接讀懂

函式命名

1// 錯誤：不知道在做什麼
2void process(data) {}
3void handle(item) {}
4
5// 正確：一眼看懂
6void calculateBookReadingProgress(Book book) {}
7void validateUserRegistrationData(User user) {}
8void enrichBookMetadataFromExternalSource(Book book) {}

變數命名

1// 錯誤：縮寫和多用途
2var usr = getCurrentUser();
3var data = loadUserData();
4data = processBookData(); // 100行後同一變數換了意思
5
6// 正確：明確且專用
7final authenticatedUser = getCurrentUser();
8final userProfileData = loadUserData();
9final enrichedBookMetadata = processBookData();

類別命名

1// 錯誤：說不清在做什麼
2class Manager {}
3class Handler {}
4class BookDAO {}
5
6// 正確：業務職責一目了然
7class BookMetadataEnrichmentService {}
8class UserRegistrationValidator {}
9class LibraryBookSearchEngine {}

布林命名

布林變數應該能讀成問句，在 if 裡就能自然被理解：

1bool isValid;      // "Is valid?"
2bool hasPermission; // "Has permission?"
3bool canEdit;       // "Can edit?"
4
5// 不好：語意不清
6bool permission;

常見命名反模式

匈牙利命名法：strName, intCount — 型別系統自己會提供型別資訊，名稱不用重複
無意義前綴：theUser, aBook — 沒帶來任何資訊，直接刪掉
過度縮寫：usrMgr — 迫使讀者展開，userManager 更自然
數字後綴：user1, user2 — 改成 primaryUser, secondaryUser 才說明關係

第二原則：函式控制在五到十行

超過十行通常表示函式承擔了多重職責。判斷是否需要拆分的最快方法：函式名稱裡有「和」或「或」的話，一定要拆。

 1// 錯誤：15行，三種職責混在一起
 2Book processBook(String isbn) {
 3  if (isbn.length != 13) throw ArgumentError('Invalid ISBN');
 4  if (!isValidISBNChecksum(isbn)) throw ArgumentError('ISBN checksum failed');
 5  final apiResponse = httpClient.get('/books/$isbn');
 6  if (apiResponse.statusCode != 200) throw Exception('API failed');
 7  final bookData = json.decode(apiResponse.body);
 8  return Book.create(
 9    id: BookId(generateUniqueId()),
10    title: BookTitle(bookData['title']),
11    source: BookSource.external(),
12  );
13}
14
15// 正確：拆成三個單一職責函式
16Book createBookFromISBN(String isbn) {
17  validateISBNFormat(isbn);
18  final bookData = fetchBookDataFromExternalAPI(isbn);
19  return buildBookFromExternalData(bookData);
20}
21
22void validateISBNFormat(String isbn) {
23  if (isbn.length != 13) throw ArgumentError('ISBN must be 13 digits');
24  if (!isValidISBNChecksum(isbn)) throw ArgumentError('ISBN checksum validation failed');
25}
26
27Map<String, dynamic> fetchBookDataFromExternalAPI(String isbn) {
28  final apiResponse = httpClient.get('/books/$isbn');
29  if (apiResponse.statusCode != 200) throw Exception('Failed to fetch book data');
30  return json.decode(apiResponse.body);
31}
32
33Book buildBookFromExternalData(Map<String, dynamic> bookData) {
34  return Book.create(
35    id: BookId(generateUniqueId()),
36    title: BookTitle(bookData['title']),
37    source: BookSource.external(),
38  );
39}

第三原則：一個變數只做一件事

同一個變數在不同地方承載不同意義，是我見過最難追蹤的 bug 來源之一。

 1// 錯誤：同一變數三種身分
 2var result = validateUser(userData);
 3if (result.isValid) {
 4  result = processPayment(paymentData);
 5  if (result.success) {
 6    result = updateDatabase(result.data);
 7  }
 8}
 9
10// 正確：每個變數都有自己的名字
11final userValidationResult = validateUser(userData);
12if (userValidationResult.isValid) {
13  final paymentProcessingResult = processPayment(paymentData);
14  if (paymentProcessingResult.success) {
15    final databaseUpdateResult = updateDatabase(paymentProcessingResult.data);
16  }
17}

變數生命週期也要管：

 1// 錯誤：books 在100行間一直換狀態
 2void processLibraryBooks() {
 3  var books = getAllBooks();
 4  books = filterAvailableBooks(books);
 5  books = sortBooksByTitle(books);
 6}
 7
 8// 正確：每個階段的狀態都有名字
 9void processLibraryBooks() {
10  final allLibraryBooks = getAllBooks();
11  final availableBooks = filterAvailableBooks(allLibraryBooks);
12  final sortedAvailableBooks = sortBooksByTitle(availableBooks);
13}

第四原則：用事件驅動表達業務流程

複雜的業務流程往往會寫成一個大函式，裡面塞滿 if/else。問題不在於 if/else 本身，而是把不同職責的邏輯混在一起。

 1// 錯誤：驗證、API呼叫、結果處理全混在一起
 2void submitForm(FormData formData) {
 3  if (formData.name.isEmpty) { showErrorMessage('姓名不能為空'); return; }
 4  if (formData.email.isEmpty) { showErrorMessage('Email不能為空'); return; }
 5  if (!isValidEmail(formData.email)) { showErrorMessage('Email格式不正確'); return; }
 6  final apiResult = submitToAPI(formData);
 7  if (apiResult.success) {
 8    showSuccessMessage('提交成功');
 9    navigateToSuccessPage();
10    clearForm();
11  } else {
12    showErrorMessage('提交失敗：' + apiResult.error);
13    highlightErrorFields(apiResult.errorFields);
14  }
15}
16
17// 正確：每個事件有自己的函式
18void submitUserRegistrationForm(UserRegistrationFormData formData) {
19  final validationResult = validateUserRegistrationData(formData);
20  if (validationResult.isValid) {
21    handleSuccessfulValidation(formData);
22  } else {
23    handleValidationFailure(validationResult.errors);
24  }
25}
26
27ValidationResult validateUserRegistrationData(UserRegistrationFormData formData) {
28  final errors = <ValidationError>[];
29  if (!isValidUserName(formData.name)) errors.add(ValidationError.invalidUserName());
30  if (!isValidUserEmail(formData.email)) errors.add(ValidationError.invalidEmail());
31  return ValidationResult.fromErrors(errors);
32}
33
34void handleSuccessfulValidation(UserRegistrationFormData formData) {
35  submitUserRegistrationToAPI(formData)
36    .then(handleSuccessfulAPIResponse)
37    .catchError(handleAPIFailure);
38}
39
40void handleValidationFailure(List<ValidationError> errors) {
41  displayValidationErrors(errors);
42  highlightInvalidFormFields(errors);
43}

狀態機也是同樣的道理：

 1// 錯誤：一個函式根據狀態做完全不同的事
 2void updateBookStatus(Book book, String newStatus) {
 3  if (newStatus == 'available') {
 4    book.status = BookStatus.available;
 5    book.borrower = null;
 6    updateSearchIndex(book);
 7    notifyWaitingUsers(book);
 8  } else if (newStatus == 'borrowed') {
 9    book.status = BookStatus.borrowed;
10    book.borrowDate = DateTime.now();
11    sendBorrowConfirmation(book);
12  } else if (newStatus == 'maintenance') {
13    book.status = BookStatus.maintenance;
14    removeFromSearchIndex(book);
15    notifyMaintenanceTeam(book);
16  }
17}
18
19// 正確：每個事件獨立
20void handleBookReturnEvent(Book book) {
21  executeBookReturn(book);
22  notifyBookBecameAvailable(book);
23}
24
25void handleBookBorrowEvent(Book book, User borrower) {
26  executeBookBorrow(book, borrower);
27  confirmBorrowingToUser(book, borrower);
28}
29
30void handleBookMaintenanceEvent(Book book) {
31  markBookForMaintenance(book);
32  notifyMaintenanceRequired(book);
33}

第五原則：可讀性優於簡潔性

程式碼的價值排序：正確性 > 可讀性 > 可維護性 > 簡潔性。

行數從來不是指標，清晰才是：

 1// 錯誤：為了少寫幾行犧牲可讀性
 2books.where((b) => b.s == 'a' && b.p > 100).map((b) => b.t).toList();
 3
 4// 正確：每一步都說清楚在做什麼
 5final availableBooksWithMoreThan100Pages = allBooks
 6    .where((book) => book.status == BookStatus.available)
 7    .where((book) => book.pageCount > 100)
 8    .toList();
 9
10final bookTitlesForDisplay = availableBooksWithMoreThan100Pages
11    .map((book) => book.title.value)
12    .toList();

如何驗證程式碼品質

陌生人測試：讓不熟悉這段程式碼的工程師讀。5分鐘內能理解主要邏輯算合格，需要解釋才能理解就要重寫。

自然語言測試：把程式碼翻譯成中文說出來。翻譯流暢自然算合格，說不清楚就改命名。

六個月後測試：假設半年後的自己要修改這段程式碼，能快速找到位置算合格，不敢動怕壞掉就要重新設計。

每一行程式碼都是一句話，每個函式都是一個段落。好的程式碼是對未來維護者的體貼——不只是風格偏好，而是降低維護成本的工程決策。

錯誤修復和重構方法論

Wed, 04 Mar 2026 00:00:00 +0000

測試失敗了，應該修改程式，還是修改測試？

這個判斷決定了整個修復方向。判斷錯，我們會花時間做出一個「讓測試通過」但實際上破壞需求的修改。

核心原則：程式服務測試，測試服務需求

測試代表需求的具體描述。為了讓測試通過而修改測試本身，等於在需求上妥協。正確的做法是保持測試不變，調整程式實作直到符合期望。

唯一的例外：需求本身發生了變化——架構調整、業務流程重設計。這兩種情況的判斷，就是整個方法論的核心。

第一步：分類

面對測試失敗，先問「為什麼失敗」，不是「怎麼修」。

程式實作錯誤：需求沒變，但程式行為不符預期——錯誤輸出、邏輯判斷有誤、型別處理不當。處理方式直接：保持測試不變，修正程式。

最容易犯的錯誤，是在這種情況下改了測試的期望值，讓測試配合錯誤的程式。這等於讓錯誤行為成為「正確需求」。

架構變更需求：需求文件已更新，業務流程本質性改變，影響多個模組。這類情況確實需要調整測試，但前提是需求文件已反映這個變更。步驟：先確認文件、評估變更範圍、列出需修改的測試，最後才執行。跳過前置確認直接改測試，和無章法地亂改沒有區別。

觀測公開行為，不觀測內部實作

我們只驗證透過公開介面的輸入輸出、公開屬性的狀態變化。不該碰私有方法的調用順序、私有屬性的中間值。

一旦測試觀測內部狀態，它就和具體實作綁定了，任何重構都會讓測試失敗，即使行為沒變。

 1// 錯誤：觀測內部私有屬性
 2test('書籍驗證應該檢查所有欄位', () {
 3  final validator = BookValidator();
 4  validator.validate(invalidBook);
 5
 6  expect(validator._titleValidated, isTrue);   // 內部狀態
 7  expect(validator._isbnValidated, isTrue);    // 私有屬性
 8});
 9
10// 正確：觀測公開行為結果
11test('書籍驗證應該檢查所有欄位', () {
12  final validator = BookValidator();
13  final result = validator.validate(invalidBook);
14
15  expect(result.isValid, isFalse);
16  expect(result.errors, contains('標題不可為空'));
17  expect(result.errors, contains('ISBN 格式錯誤'));
18});

三個常見的反模式

測試遷就程式：程式返回錯誤值，開發者把測試期望值改成那個錯誤值。測試通過了，bug 也永遠存在了。正確做法：保持期望值不動，修正程式邏輯。

內部狀態依賴：測試直接存取 book._internalState 來驗證操作。一旦重構就失敗。改用公開方法 book.isAvailable() 驗證行為結果。

跳過文件檢查：覺得需求「應該」要改，就直接改測試，沒確認需求文件是否更新。正確做法：先查規格書，確認文件已反映變更，再評估影響範圍，最後才動手。

驗收標準

修復前：錯誤類型已判斷、需求文件狀態已確認、受影響測試範圍已識別。

修復後：所有測試 100% 通過、無內部狀態曝露、無行為旁路、每個修改都有測試保護。

100% 通過率是底線。某個測試通過不了，不是跳過它或修改它，是找出真正的問題。