如何在Python項目中應用分層架構

TLDR（AI Claude 的總結）

本文來自一位 Python 開發者對一個龐大的 Python 項目的代碼結構的總結。

該項目包含近 3 萬個 Python 文件，由全球 400 多名開發者共同維護。為了應對代碼日益增長的復雜性，項目采用了分層架構的設計。即將代碼庫劃分為多個層級，并限制不同層級之間的依賴關系，依賴只能從上層流向下層。

文章詳細介紹了該項目的分層結構，以及如何利用 Import Linter 工具來強制執行分層規則。通過追蹤被忽略的非法 import 語句數量，可以衡量分層結構實現的進度。

分層架構確實能夠有效降低大型項目的復雜度，方便獨立開發。但也存在一些缺點，比如容易在高層產生過多代碼，完全實施分層需要花費時間等?？傮w來說，盡早引入分層架構，能夠減少后期的重構工作量，是管理大型 Python 項目的一個有效方式。

本文通過一個真實的大規模 Python 項目案例，生動地介紹了分層架構的實施過程、優勢和不足，對于管理大型項目很有借鑒作用。

前言

大家好，我是來自 Kraken Technologies 的 Python 開發者 David。我在的 Kraken 工作是維護一個 Python 應用，根據最新統計它擁有 27637 個模塊的。是的，你沒看錯，這個項目擁有近 28K 獨立的 Python 文件（不包括測試代碼）。

我與全球其他 400 名開發人員一同維護這個龐然大物，不斷地為它合并新的代碼。任何人只需要在 Github 上獲得一位同事的批準，就能修改代碼文件，并啟動軟件的部署，該軟件在 17 家不同的能源和公用事業公司運行著，擁有數百萬的客戶群體。

看到上面的描述，你大概率會下意識地認為這個項目的代碼肯定無比的混亂。坦白講，我也會這么想。但事實是，至少在我工作的領域，大量的開發人員可以在一個大型的 Python 項目上高效地工作。

實現這個目標的要素有很多，其中許多要素來自文化與規則而非技術，在本篇博文中，我想著重講一下我們是如何通過優化代碼組織結構來實現這一目標的。

分層架構

如果你已經負責維護某個應用的代碼倉庫一段時間，肯定會感受到隨著時間的推移代碼復雜度越來越高。在不斷開發與維護的過程中，應用中各部分的邏輯代碼混合在一起，獨立地分析應用中的某個模塊變得越來越困難。

這也是我們早期維護代碼倉庫時遇到的問題，經過研究后我們決定采用分層架構（即將代碼庫劃分成多個組件（也就是層級，后面不再注釋），并限制各組件間的引用關系）來應對這一問題。

分層（Layering）是一種較為常見的軟件架構模式，在這種模式下不同的組件（即層級，后面不在重復注釋）會被以（概念上）棧的形式組織起來。在這個棧中，下層組件不能依賴（引入）其上層組件。

依賴向下關系流動的分層架構

例如，在上圖中，C 可以依賴 B 和 A，但不能依賴 D。

分層架構的應用很寬泛，你可以自由地定義組件。例如：你可以將多個可獨立部署的服務視作多個組件，也可以直接將項目中不同部分的源碼文件視作不同的組件。

依賴關系的定義也很寬泛。通常，只要兩個組件間存在直接交叉（即使只發生在概念層級上），我們就認為它們之間存在依賴關系。間接交叉（例如通過配置傳遞）通常不被視為依賴關系。

如何在 Python 項目中應用分層架構

分層架構在 Python 項目中的最佳實踐是：將 Python 模塊作為分層依據，將導入語句視為依賴依據。

以如下項目倉庫目錄舉例：

myproject
?__init__.py
?payments/
??__init__.py
??api.py
??vendor.py
?products.py
?shopping_cart.py

目錄中模塊之間的嵌套關系是分層的最佳依據。假設，我們決定按照一下順序進行分層：

#?依賴關系向下流動（即上層可以依賴下層）
shopping_cart
payments
products

為了滿足上述架構的要求，我們需要禁止?payments?中的模塊從?shopping_cart?模塊中引入內容，但可以從?products?模塊中引入內容（參考圖 1）。

分層也可以嵌套，因此我們可以在 payments 模塊中繼續分層，例如：

api
vendor

設置多少分層以及以什么順序進行排列沒有唯一正確的答案，需要我們不斷的在實踐中總結。但是合理的運用分層架構確實能夠有效地降低項目結構的復雜度，使其能夠更易于理解和修改。

我們是如何在 Kraken 的項目中實踐分層架構的

在我編寫這邊文章的時候，已經有 17 家不同的能源和公共事業相關的企業購買了 Kraken 的許可證。我們在內部稱呼這些企業為 client，并為每一家企業都運行了一個獨立的實例。也正因如此，Kraken 的不同實例間形成了一種「同根不同枝」的特點。

通俗地講就是不同實例間的很多行為其實是共享的，但是每個 client 也都有屬于自己的定制代碼，以滿足他們特定的需求。從地域層面來講也如此，在英國運行的所有 client 之間存在一定的共性（他們屬于同類的能源行業），而日本的 Octopus Energy 則不共享這些的共性。

隨著 Kraken 平臺的成長，我們也在不斷地優化著我們的分成架構，來幫助我們更好地滿足不同客戶的需求。目前的分層的頂層結構大致如下：

#?依賴關系向下流動（即上層可以依賴下層）
kraken/
????__init__.py
????
????client/
????????__init__.py
????????oede/
????????oegb/
????????oejp/
????????...
????
????territories/
????????__init__.py
????????deu/
????????gbr/
????????jpn/
????????...
????
????core/

client 組件在結構的頂部。每一個 client 在該層都有一個專屬的子包（例如，oede 對應 Octopus Energy Germany）。在此之下的是 territories 組件，用于滿足不用國家所需的特定行為，同樣為不同地區設置了不同的子包。最底層是 core 組件，包含了所用 client 都會用到的通用代碼。

我們還制定了一個特別的規則：client 組件下的子包必須是獨立的（即不能被其他 client 引用），territories 組件下的子包也是如此。

將 Kraken 以這種分層結構構建之后，我們可以在有限的區域內（例如一個組件的子包）便捷地進行代碼的更新和維護。由于 client 組件位于結構的頂部，因此不會有任何其他組件會直接依賴于它，這樣我們就能更方便地更改特定 client 有關的內容，而且不必但因會影響到其他 client 的行為。

同樣，只更改 territories 組件內的一個子包也不會影響到其他的子包。這樣，我們就可以快速、獨立地進行跨團隊開發，尤其是當我們進行的更改只影響少量 Kraken 實例的時候。

通過 Import Linter 確保項目中的分層實現

雖然引入了分層結構，但我們很快發現，僅僅在理論上論述分層是不夠的。開發人員經常會不小心進行分層間的違規引入。我們需要以某種方式確保分層結構的理論能夠在代碼結構中被遵循，為了達到此目的我們在項目中引入了第三方庫 Import Linter。

Import Linter 是一款開源工具，用于檢查項目中的引用邏輯是否遵循了指定的結構。首先，我們需要在一個 INI 文件中定義一個描述目標需求的配置，類似這樣：

[importlintertop-level]

name?=?Top?level?layers
type?=?layers
layers?=
????kraken.clients
????kraken.territories
????Kraken.core

我們還可以使用另外兩個配置文件強制不同的 clients、territories 之間相互獨立。類似這樣：

#?文件?1
[importlinterclient-independence]
name?=?Client?independence
type?=?independence
layers?=
????kraken.clients.oede
????kraken.clients.oegb
????kraken.clients.oejp
????...

#?文件?2
[importlinterterritory-independence]
name?=?Territory?independence
type?=?independence
layers?=
????kraken.territories.deu
????kraken.territories.gbr
????kraken.territories.jpn
????...

然后，你可以在命令行運行?lint-import，它會告訴你項目中是否有任何導入行為違反了我們配置中的要求。我們會在每次拉取代碼的時候運行此功能，因此如果有人使用了不合規的導入，檢查就會失敗，代碼也就不會被合并。

上面展示的并不是我們項目全部的配置文件。團隊成員可以在應用程序的更深處添加自己的分層，例如：kranken.ritories.jpn 本身就是分層。我們目前擁有超過 40 個配置文件用于規定我們的分層結構。

消除技術債

我們沒有辦法在確定是由分層架構的第一時間就使整個項目符合架構需求。因此，我們使用了 Import Linter 中的一項特性，該功能允許您在檢查非法導入之前忽略對某些導入的檢查。

[importlintermy-layers-contract]
name?=?My?contract
type?=?layers
layers?=
????kraken.clients
????kraken.territories
????kraken.core
ignore_imports?=
????kraken.core.customers?->
????kraken.territories.gbr.customers.views
????kraken.territories.jpn.payments?->?kraken.utils.urls
????(and?so?on...)

此后，我們使用項目構建時被 Import Linter 忽略的導入語句的數量作為跟蹤技術債完成度的指標。這樣，我們就能觀察到隨著時間的推移技術債的情況是否有所改善，以及改善的速度如何。

Ignored imports since 1 May 2022