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

圖片

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

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

依賴關系向內(nèi)指向“業(yè)務核心”，外層可以依賴內(nèi)層，但內(nèi)層絕不可以反向依賴外層。

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

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

圖片

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

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

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

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

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

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

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

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

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

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

當一個請求穿越框架層，進入系統(tǒng)內(nèi)部時，接口適配器層便開始發(fā)揮作用。這一層的核心職責是將外部輸入轉(zhuǎn)化為內(nèi)部可理解的數(shù)據(jù)結(jié)構，并將應用邏輯的執(zhí)行結(jié)果以合適的格式返回給調(diào)用者。

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

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

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

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

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

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

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

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

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

3. 應用邏輯層：業(yè)務流轉(zhuǎn)的核心引擎

在 Clean API 架構中，應用邏輯層是整個系統(tǒng)真正開始處理業(yè)務需求的地方。它承接來自接口適配器層的請求，并協(xié)調(diào)數(shù)據(jù)驗證、權限控制、外部調(diào)用以及最終的業(yè)務執(zhí)行。

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

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

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

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

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

• 語法驗證發(fā)生在請求層，確保傳入的數(shù)據(jù)格式正確；
• 語義驗證則在應用邏輯層進行，確保數(shù)據(jù)在業(yè)務規(guī)則下是合理且合法的。

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

4. 實體邏輯層：業(yè)務規(guī)則與數(shù)據(jù)交互的核心

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

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

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

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

5. 數(shù)據(jù)層：存儲抽象與適配的關鍵一環(huán)

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

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

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

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

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

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

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

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

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

請求（Request）

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

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

控制器（Controller）

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

服務（Service）

服務層在此處承擔了主要職責，它接收來自請求的 target_id和 creator_id，并查找或創(chuàng)建相應的領域?qū)ο?nbsp;Favorite。這一過程確保了輸入的有效性和用戶的授權狀態(tài)，并協(xié)調(diào)后續(xù)的數(shù)據(jù)處理步驟。

實體邏輯（Entity Logic）

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

數(shù)據(jù)（Data）

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

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