層級架構品質檢查機制 - Clean Architecture 合規性驗證

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

在 Flutter 專案裡導入 Clean Architecture 並不難，難的是讓整個團隊在每一次 commit 都確實遵守它。我們曾有過這樣的經驗：架構設計文件寫得很完整，但三個月後打開 codebase，Widget 裡藏著業務規則、Controller 開始自己做驗證、UseCase 直接依賴了具體的資料庫實作。

問題在於沒有機制讓「做錯事」變得困難。

為什麼架構會悄悄腐化

Clean Architecture 的核心是依賴方向：外層可以依賴內層，但內層絕對不能依賴外層。這個原則說起來簡單，但「快速解決問題」的衝動很容易讓人走捷徑。一個業務驗證邏輯，放在 Widget 裡只要三行；把它搬到正確的 Domain 層，可能需要新增 Entity 方法、更新 UseCase、再補上測試。

在時間壓力下，捷徑獲勝了。

更麻煩的是，這種腐化是漸進的。第一次違規很小；第二次引用了第一次的前例；到了第六次，層級的邊界已經模糊得看不清楚了。

解法是：不依賴自律，改依賴機制。把架構規則轉化為可以自動執行的檢查。

用檔案路徑判斷層級歸屬

我們採用的策略是用檔案路徑作為層級的明確宣告。一個檔案放在什麼目錄，就代表它屬於哪一層：

 1lib/
 2├── ui/                    // 展示層（Layer 1）
 3├── application/           // 應用行為層（Layer 2）
 4├── usecases/              // UseCase 層（Layer 3）
 5├── domain/
 6│   ├── events/            // Domain 事件層（Layer 4）
 7│   ├── interfaces/        // 介面定義層（Layer 4）
 8│   ├── entities/          // Domain 實作層（Layer 5）
 9│   ├── value_objects/     // 值物件（Layer 5）
10│   └── services/          // Domain 服務（Layer 5）
11└── infrastructure/        // 基礎設施層

這讓我們可以用簡單的字串比對判斷：這個 PR 動了哪些層的檔案？一個 Ticket 聲稱只修改展示層，但 diff 裡出現了 lib/domain/ 的檔案，那就是需要解釋的信號。

測試目錄也採用相同的對應結構：

1test/
2├── ui/           // 對應展示層修改
3├── application/  // 對應應用行為層修改
4├── usecases/     // 對應 UseCase 層修改
5└── domain/       // 對應 Domain 層修改

修改了某個層，對應的測試目錄裡就必須有覆蓋。「測試覆蓋率」從一個抽象數字，變成了具體的結構性要求。

三種最常見的違規模式

追蹤了幾十個架構違規案例之後，幾乎都落在以下三種模式。

展示層包含業務邏輯

Widget 直接呼叫過濾、排序、計算這類業務操作：

 1// 違規：Widget 自己做了業務邏輯
 2class BookListWidget extends StatelessWidget {
 3  Widget build(BuildContext context) {
 4    final books = _filterNewBooks(_getAllBooks());
 5    return ListView.builder(...);
 6  }
 7}
 8
 9// 正確：Widget 只負責把 controller 的狀態渲染出來
10class BookListWidget extends StatelessWidget {
11  final BookListController controller;
12  Widget build(BuildContext context) {
13    return ListView.builder(items: controller.filteredBooks);
14  }
15}

「什麼樣的書算新書」是業務邏輯，應該在 Domain 層定義。Widget 只做一件事：把資料渲染成畫面。

Controller 包含業務規則

 1// 違規：Controller 自己在做 ISBN 驗證
 2class BookController {
 3  Future<void> addBook(Book book) async {
 4    if (book.isbn.length != 13) {
 5      throw ValidationException('ISBN 必須為 13 碼');
 6    }
 7    await bookRepository.save(book);
 8  }
 9}
10
11// 正確：Controller 只負責呼叫 UseCase
12class BookController {
13  final AddBookUseCase addBookUseCase;
14  Future<void> addBook(Book book) async {
15    await addBookUseCase.execute(book);
16  }
17}

「ISBN 必須為 13 碼」是業務規則，應該活在 Book Entity 或 Value Object 裡。Controller 的角色是協調，不是決策。

UseCase 依賴具體實作

1// 違規：依賴具體的 SQLite 實作
2class SearchBookUseCase {
3  final SqliteBookRepository repository;
4}
5
6// 正確：依賴抽象介面
7class SearchBookUseCase {
8  final IBookRepository repository;
9}

依賴介面讓 UseCase 在測試時注入 Mock，生產環境注入真實實作，兩者互換自如。

把檢查機制自動化

辨識出違規模式之後，我們做的第一件事是把檢查寫進工具裡。

Pre-commit Hook

1#!/bin/bash
2./scripts/check_single_layer_modification.sh || exit 1
3flutter test --coverage || exit 1

check_single_layer_modification.sh 分析 commit 的 diff，確認被修改的檔案是否都屬於同一個架構層。一個本來只應動展示層的 commit，如果同時修改了 Domain 層的檔案，腳本就會退出並阻止 commit。

CI/CD 整合

Pre-commit Hook 可以被繞過，但 CI/CD 不會：

 1name: PR Architecture Check
 2on: [pull_request]
 3jobs:
 4  architecture_check:
 5    runs-on: ubuntu-latest
 6    steps:
 7      - name: 檢查單層修改原則
 8        run: ./scripts/check_single_layer_in_pr.sh
 9      - name: 執行測試並確認覆蓋率
10        run: flutter test --coverage

架構合規性成為 PR 合併的硬性前置條件。

每次 commit 前的自我檢查

自動化工具處理可以被程式判斷的規則，剩下的需要開發者自己過一遍：

這次修改的檔案，是否都屬於同一個架構層？
import 方向是否正確——只有外層依賴內層？
測試檔案路徑和被測試程式碼是否在對應的層級目錄？
有沒有 Widget 直接做業務計算、Controller 直接做驗證？

三十秒可以過完，但幾乎每次都能在 commit 前抓住一兩個值得重新考慮的決定。

機制比自律更可靠

導入這套機制之後，code review 上花的精力少了很多——大多數架構層面的問題在進入 review 之前就已經被攔截。reviewer 可以把注意力放在邏輯正確性和設計決策上，不用反覆提醒「這段邏輯不應該放在 Widget 裡」。

對新加入的開發者也很友善：不需要先把架構文件背熟才能開始開發，工具會在走錯方向時給出明確的反饋。

架構的生命力在於它能不能在日常開發壓力下被維護下去。

依賴方向 on Tarragon