在軟件架構領域，網上討論最廣泛的架構之一是整潔架構（Clean Architecture）。它通過將項目劃分為多個層級，實現關注點分離，從而提升代碼的可維護性和可擴展性。

圖片

每一層都遵循單一職責原則，確保每個類只負責一部分邏輯，不僅使系統結構更清晰，也極大地方便了單元測試的編寫與執行。

整潔架構的核心理念可以概括為：

依賴關系向內指向“業務核心”，外層可以依賴內層，但內層絕不可以反向依賴外層。

換句話說，沒有哪一層可以看到比它更高層的細節。它們可以引用自己的子層，但從不允許跨層依賴或反向耦合。

這種設計思想不僅適用于整體系統架構，在具體場景如 API 開發中同樣具有重要價值。那么，如何將 Clean Architecture 的理念應用到 API 端點的設計中？這就引出了“Clean API 架構”這一實踐模式：

圖片

它將接口層、應用服務、領域邏輯和數據訪問等模塊清晰隔離，使 API 結構更加清晰、易于測試和長期演進。

1. 框架：從請求入口到架構分層

在現代 Web 系統中，任何一個 API 請求通常都需要經過多個層級的處理——從負載均衡器、Web 服務器，到應用服務器，最終由具體的 API 或 Web 框架將請求路由到正確的代碼路徑。目前主流的開發框架如 Rails、Django 和 Spring Boot 等都提供了豐富的文檔支持和成熟的生態體系，是大多數開發者首選的技術棧。

然而，當請求真正進入框架并開始業務邏輯處理后，不同系統的設計路徑往往開始顯著分化。

以 Rails 為例，其采用經典的 MVC（Model-View-Controller）架構，在小型項目中表現優異，結構清晰且上手成本低。但對于大型、高可用性的 API 系統而言，這種模式逐漸顯露出局限性——控制器和模型容易膨脹為臃腫的“上帝類”，違背了單一職責原則，導致維護困難、測試復雜。

正因如此，在框架層級之下，我們所構建的整個系統設計更加注重解耦與可擴展性，并深受 Clean Architecture 的啟發。這套設計理念強調業務邏輯應獨立于外部依賴（如數據庫、UI、框架等），從而提升系統的可測試性和長期可維護性。

在本系列后續內容中，我們將深入剖析我們是如何按照這一思想來組織各層級代碼的。

在每一層中，我們會定義一個或多個單一職責的支持類，它們只服務于當前層級，不引用上下層的具體實現。這種嚴格隔離不僅有助于代碼復用，也有效避免了層級混亂和過度耦合的問題。

此外，雖然我們在架構中使用了諸如 AWS EC2、SQS、RDS 和 ElastiCache 等云服務，但這些服務在我們的設計中被作為框架層的輔助工具類存在，而非核心業務邏輯的一部分。正如 Clean Architecture 所強調的那樣：業務規則不應依賴于基礎設施或數據存儲方式，而應保持完全的獨立。這也確保了我們的系統具備更強的可移植性與靈活性。

2. 接口適配器層：連接外部世界與核心邏輯的橋梁

當一個請求穿越框架層，進入系統內部時，接口適配器層便開始發揮作用。這一層的核心職責是將外部輸入轉化為內部可理解的數據結構，并將應用邏輯的執行結果以合適的格式返回給調用者。

在這一過程中，控制器（Controller）扮演著協調者的角色。它首先通過 Request 對象提取請求參數，驗證其語法格式，并完成用戶身份認證等前置操作。隨后，控制器實例化相應的業務類，驅動數據在不同層級之間的流轉，從而啟動真正的應用邏輯處理流程。

值得注意的是，控制器并不是接口適配器層中唯一負責業務流程的對象。我們還引入了 Jobs（任務），用于處理異步隊列相關的操作——這部分內容將在后續章節中詳細展開。

為了確保系統的清晰分層與職責分離，控制器依賴于多個輔助類：

• Validators（驗證器） 
  負責檢查輸入數據的合法性，確保進入系統的信息符合預期格式；
• Presenters（展示器） 
  專注于輸出數據的格式化處理，為上層邏輯提供統一的數據視圖；
• Response（響應）對象 
  則承擔最終輸出的封裝工作，能夠將數據轉換為 JSON、HAML 或其他客戶端可識別的格式返回。

此外，系統中還包含一種特殊的適配器——套接字中繼類（Socket Relay），它通過 WebSocket 等通信通道，實時將狀態變更推送給客戶端，實現雙向通信能力。

Request 類則是一個類型化的數據結構，聚合了當前請求所需的所有信息。與傳統 HTTP 請求（通常是以鍵值對形式存在的 CGI 風格請求）不同，這種設計提供了更強的類型安全性和結構清晰性。

Response 類的功能類似于 Rails 中的渲染器，但它更加靈活，支持多種輸出格式，如 HAML、JSON 或自定義類型，便于構建多端兼容的 API 響應。

最后，參數提取器（Parameter Extractor） 從原始的 params 散列中提取數據，并將其轉換為正確的類型，如整數、浮點數或字符串，為后續邏輯提供強類型的輸入保障。

整體而言，接口適配器層作為系統的“翻譯官”，在外部請求與內部邏輯之間建立起高效、清晰的橋梁，是實現 Clean Architecture 分層思想的重要一環。

3. 應用邏輯層：業務流轉的核心引擎

在 Clean API 架構中，應用邏輯層是整個系統真正開始處理業務需求的地方。它承接來自接口適配器層的請求，并協調數據驗證、權限控制、外部調用以及最終的業務執行。

對于 GET 請求這類讀取型端點，請求一旦進入該層，首先由服務類（Service）進行處理。服務對象負責確保輸入參數的有效性，驗證用戶是否有權限訪問目標資源，并通過 Repo（用于數據庫操作） 或 Adapter（用于外部 API 調用） 從實體邏輯層獲取所需數據。

在數據獲取完成后，服務對象將結果封裝為一個由 Result 對象返回。這種設計不僅統一了成功與失敗的返回結構，也便于上層（如控制器）根據結果類型做出相應的響應決策。

而對于 POST、PUT 和 DELETE 等寫入型請求，應用邏輯的處理流程類似，但引入了異步機制以提升性能和可靠性。服務對象仍然負責驗證輸入、授權用戶，并準備寫入所需的數據。不同之處在于，這些變更操作會被包裝并提交到我們的任務隊列（基于 Amazon SQS）中排隊，交由后臺的作業（Job）或異步服務來執行真正的數據寫入操作。這種方式既減輕了主流程的壓力，也增強了系統的容錯能力和可擴展性。

此外，作業還承擔著觸發副作用的職責。例如，在數據持久化完成之后，作業可以通過 Relay 模塊向客戶端發送 WebSocket 消息，實時通知狀態變更，實現前后端之間的即時反饋。

值得一提的是，在本架構中，Service 類還會組合一組專門的 Validator 類，對請求內容進行語義級別的驗證。這意味著我們在系統中構建了雙層驗證機制：

• 語法驗證發生在請求層，確保傳入的數據格式正確；
• 語義驗證則在應用邏輯層進行，確保數據在業務規則下是合理且合法的。

這種分層驗證策略顯著提升了系統的健壯性，避免了無效或非法數據對核心業務邏輯造成干擾，同時也使代碼更具可測試性和可維護性。

4. 實體邏輯層：業務規則與數據交互的核心

實體邏輯層（Entity Logic Layer） 是系統中最具通用性和復用價值的部分。它不僅服務于當前 API 端點，也為其他多個接口和業務流程提供基礎能力支撐。這一層承載了系統的核心業務規則以及與外部存儲系統的交互邏輯。

在這一層級中，我們實現對持久化數據庫（如 MySQL 或 PostgreSQL）的訪問，封裝了數據的讀取、寫入和轉換邏輯；同時，Adapter 類 則負責對接各類外部服務 API，例如 AWS 提供的 S3（對象存儲）、ElastiCache（緩存服務）等，使得系統能夠靈活集成多種基礎設施資源。

與上層（如應用邏輯層）中為特定端點定制的服務類不同，實體邏輯層中的類設計強調高內聚、低耦合與廣泛復用性。它們通常不依賴于具體的請求或業務場景，而是圍繞領域模型構建穩定的數據訪問和業務處理能力。

簡而言之，實體邏輯層是整個 Clean API 架構中最接近“不變”的部分——它屏蔽了外部變化的影響，確保系統核心邏輯穩定可靠，同時也為上層模塊提供了統一、可測試、可替換的數據交互接口。

5. 數據層：存儲抽象與適配的關鍵一環

數據層（Data Layer） 是整個 Clean API 架構中最底層的一環，其核心職責是為上層模塊提供統一的數據訪問接口，并屏蔽具體存儲實現的細節。理想情況下，這一層應保持高度簡潔和可替換，專注于連接數據庫、緩存、文件系統或其他持久化機制。

為了實現跨平臺一致性，我們在不同技術棧中（例如 Android 或 iOS 開發）也為數據存儲層建立了統一接口。通過依賴注入（Dependency Injection） 技術，我們可以在測試時輕松替換真實的數據源為內存中的模擬實現（Mock）。例如，在本地運行單元測試時，可以使用基于 SQLite 的內存數據庫代替實際的文件系統或遠程服務，從而提高測試效率并減少外部依賴的影響。

在 Web 服務器環境中，我們通常將云服務（如 Redis、Memcached、MySQL 等）抽象為單例對象，并根據部署環境動態指向不同的實際資源。例如，在開發階段，這些服務可以指向本地運行的 Docker 容器；而在生產環境中，則連接真實的云服務實例。

支撐數據層的各類存儲系統——如 MySQL 和 Postgres——通常以進程級別的單例形式存在，并通過依賴注入或配置管理進行初始化和替換。像 ActiveRecord 這樣的 ORM 會維護自己的連接池，而 Redis 和 Memcached 等服務也需要類似的全局訪問控制機制來管理連接資源。

對于基于 HTTP 的無狀態服務（如 S3、DynamoDB 等），我們通常采用模擬雙（Instance Doubles）或覆蓋連接參數的方式來隔離外部環境。這使得測試過程更加可控，同時也能保證代碼邏輯在不同環境下的一致性。

總之，數據層不僅是系統與外部世界交互的橋梁，更是實現可測試性、可維護性和可擴展性的關鍵所在。通過良好的抽象設計與靈活的注入策略，它確保了我們的業務邏輯不受底層存儲細節的牽制，真正做到“一次編寫，多環境運行”。

6. 這是否過度設計？讓我們通過一個簡單的示例來探討

為了更好地理解各層架構的實際應用，我們來看一個最基礎的 API 示例：將文件添加到收藏夾。即使在這樣一個看似簡單的操作中，每一層的設計理念依然得到了體現。

假設我們要創建一個允許用戶將某個文件添加到其收藏夾的功能。在這個過程中，盡管表面上看只需要一個簡單的數據庫操作，但實際上，這個功能隱式地依賴于我們之前定義的每一層架構。

請求（Request）

請求參數直接從 HTTP 請求中提取，包含 target_id（目標文件的ID）和 creator_id（執行該操作的用戶ID）。這些未經處理的原始參數構成了一個隱式的請求對象。

Params: { "target_id": 123, "creator_id": 456 }

控制器（Controller）

由于此場景下沒有復雜的驗證或表示邏輯需求，因此無需專門編寫控制器代碼。這意味著我們可以跳過這一步驟，直接進入服務層處理業務邏輯。

服務（Service）

服務層在此處承擔了主要職責，它接收來自請求的 target_id和 creator_id，并查找或創建相應的領域對象 Favorite。這一過程確保了輸入的有效性和用戶的授權狀態，并協調后續的數據處理步驟。

實體邏輯（Entity Logic）

實體邏輯層負責與持久化存儲交互，這里使用了一個特殊的 ActiveRecord 方法 first_or_create 來檢查是否存在符合條件的記錄，若不存在則創建新記錄。這種方法不僅簡化了數據訪問邏輯，還保證了數據的一致性。

數據（Data）

在數據層，Favorite 模型充當了與底層數據庫交互的角色，提供了對特定對象的操作接口。它封裝了所有與數據庫相關的細節，如連接管理、查詢構建等，使得上層代碼可以專注于業務邏輯而非技術實現。

通過這個簡單的例子可以看出，即使是看似微不足道的功能，Clean API 的分層設計也能夠提供清晰的結構劃分，確保每個部分專注于自己的職責。這樣的設計雖然初看起來可能顯得有些復雜，但它極大地提高了代碼的可維護性、測試性和擴展性。隨著系統規模的增長，這種架構的優勢將會更加明顯。