Go 項目文件夾結構的簡單指南
作者：孔令飛
一個智能的文件夾結構使你的開發過程更加順暢，并幫助你的項目蓬勃發展。這里列一些在 Golang 項目中常用的文件夾結構。
在 Golang（或任何編程語言）中討論文件夾結構時，我們關注的是如何在項目中組織文件與目錄。這種組織方式如同路線圖，可幫助開發者維護、導航并擴展項目，通過清晰地劃分關注點、模塊與功能來奠定長期可維護性的基礎。遵循 Go 社區的約定不僅便于閱讀與協作，還能提升代碼質量。
一、為什么文件夾結構重要？
擁有一個良好組織的文件夾結構可以帶來以下優點：
- 層次分離：將業務邏輯、數據訪問、API 處理等模塊置于各自文件夾，便于開發者聚焦于特定領域，而不會感到不知所措或困惑；
- 良好組織：結構化代碼與依賴后，大型項目亦可輕松導航，你總是知道在哪里可以找到所需的內容；
- 可重用性：良好的結構讓你創建可以在項目不同部分中使用的組件或包，從而節省時間和精力；
- 易于維護：一致的目錄約定使代碼查找與更新更簡單，降低長期維護成本；
- 模塊化：合理的分層鼓勵模塊化設計，便于在項目擴展時增添新功能。
簡而言之，一個智能的文件夾結構使你的開發過程更加順暢，并幫助你的項目蓬勃發展！
二、Go 中的常見文件夾結構
這里列一些在 Golang 項目中常用的文件夾結構。
1. 扁平結構
扁平文件夾結構是一種組織方法，其中所有文件直接存儲在根目錄中，沒有任何深層嵌套或多個子目錄。這種簡單性使得導航和管理變得容易，特別是對于小型或簡單的項目。
project/
├── main.go
├── handler.go
├── service.go
├── repository.go
├── config.go
├── utils.go
├── go.mod
└── go.sum用例：
- 小型項目： 適合復雜度低的項目，使開發者能夠在少量文件中管理所有功能；
- 原型和最小可行產品（MVP）： 非常適合快速構建原型或最小可行產品（MVP），便于快速迭代而無需組織文件夾；
- 命令行工具： 非常適合只需要少量支持文件的小型命令行應用程序，使得執行和測試變得簡單；
- 學習與實驗： 對于學習新編程語言或框架的初學者非常有益，因為它減少了文件組織的復雜性。
2. 分層結構
按照處理器（Handler）、服務（Service）、倉庫（Repository）、模型（Model）等層次劃分，強調關注點分離。
project
├── cmd
│ └── app
│ └── main.go
├── internal
│ ├── handlers
│ │ └── user_handler.go
│ ├── services
│ │ └── user_service.go
│ ├── repositories
│ │ └── user_repo.go
│ └── models
│ └── user.go
├── pkg
├── configs
├── go.mod
└── go.sum用例：
- 中型項目： 適用于需要在不同功能和層之間有明確分離的應用；
- 關注點分離： 促進了一種清晰的架構，其中處理程序僅負責管理請求，將業務邏輯委派給服務，并將數據訪問委托給倉庫；
- 單元測試： 每一層都可以獨立進行單元測試，確保一個層的更改不會影響其他層，從而提高可維護性。
3. 領域驅動設計（DDD）
在領域驅動設計（DDD）中，應用程序被劃分為領域或界限上下文，每個領域擁有自己的層，包括模型、倉庫和服務。這種方法有助于隔離邏輯，并保持代碼的領域特定性，從而促進更好的組織和清晰度。
project
├── cmd
│ └── app
│ └── main.go
├── internal
│ ├── user
│ │ ├── handler.go
│ │ ├── service.go
│ │ ├── repository.go
│ │ └── user.go
│ └── product
│ ├── handler.go
│ ├── service.go
│ └── repository.go
├── pkg
├── configs
├── go.mod
└── go.sum用例：
- 復雜項目： 最適合具有多個業務領域的應用程序，確保每個領域可以獨立演變而不影響其他領域；
- 解耦與可擴展性： 當應用程序的不同部分需要隔離以實現可擴展性和可維護性時非常有用；
- 模塊化： 促進模塊化，因為每個領域可以單獨管理和開發，允許團隊在特定領域工作而不發生沖突。
4. 簡潔架構（Clean Architecture）
簡潔架構將應用程序組織成不同的層，每層都有明確的依賴關系指向內部。這個結構確保核心業務邏輯獨立于外部系統，如數據庫、框架或用戶界面。
project
├── cmd/
│ └── app/
│ └── main.go
├── internal
│ ├── delivery/
│ │ └── http/
│ │ └── user_handler.go
│ ├── usecases/
│ │ └── user_service.go
│ ├── repository/
│ │ └── user_repo.go
│ └── entities/
│ └── user.go
├── pkg/
├── configs/
├── go.mod
└── go.sum關鍵原則:
- 核心實體：領域模型是架構的核心，確保業務邏輯是主要關注點；
- 用例：封裝特定于應用程序的業務規則，定義實體之間的交互；
- 交付層：通過各種接口（API、CLI、gRPC）管理外部交互；
- 倉庫：處理數據訪問，允許與數據庫和第三方服務交互，而不與業務邏輯耦合。
用例：
- 大型可擴展項目: 適用于需要隨著時間的推移進行適應和擴展的應用程序，而不影響核心功能；
- 獨立測試： 促進核心邏輯的輕松測試，無需依賴框架、數據庫或其他外部服務，增強可維護性和靈活性。
5. 模塊化結構
模塊化結構將應用程序組織為松耦合、自包含的模塊，每個模塊都有自己的代碼庫。這種方法允許每個模塊專注于特定的功能或業務單元，提高了可重用性和可擴展性。
project/
├── user_module/
│ ├── handler/
│ ├── service/
│ ├── repository/
│ ├── user.go
│ ├── go.mod
│ └── go.sum
├── product_module/
│ ├── handler/
│ ├── service/
│ ├── repository/
│ ├── product.go
│ ├── go.mod
│ └── go.sum
├── api_gateway/
│ ├── main.go
│ ├── go.mod
│ └── go.sum
└── configs/用例：
- 微服務：適合基于微服務架構構建的應用程序，在該架構中，不同的團隊可以獨立于各個模塊進行工作；
- 解耦與可擴展性：鼓勵明確的關注點分離，使每個模塊能夠獨立開發、測試和部署；
- 獨立的依賴管理：每個模塊可以擁有自己的 go.mod 文件，便于單獨管理依賴并減少模塊之間的沖突。
6. 基于特性（Feature-Based）結構
在基于特性的文件夾結構中，應用程序的每個特性或功能都被視為一個獨立的單元。與該特性相關的所有代碼，包括處理程序、服務、存儲庫等，都位于該特性的目錄中。這種方法增強了特性內部的一致性，并促進了特定于特性的邏輯的封裝。
project/
├── cmd/
│ └── app/
│ └── main.go
├── internal/
│ ├── user/
│ │ ├── handler/
│ │ ├── service/
│ │ ├── repository/
│ │ └── user.go
│ ├── product/
│ │ ├── handler/
│ │ ├── service/
│ │ ├── repository/
│ │ └── product.go
│ ├── order/
│ │ ├── handler/
│ │ ├── service/
│ │ ├── repository/
│ │ └── order.go
├── pkg/
│ └── logger.go
├── configs/
├── go.mod
└── go.sum特點：
- 封裝：每個特性封裝了自己的邏輯、模型和層次，最小化不必要的依賴；
- 可擴展性：結構可以隨著新特性的添加而輕松增長，只需創建新的特性目錄；
- 關注業務需求：由于組織圍繞特性展開，它與業務需求緊密對齊，使開發團隊更直觀；
- 高內聚性：每個特性相關的代碼被分組在一起，使得維護和增強特定功能的代碼庫變得更容易。
用例：
- 大型應用程序： 最適合由多個獨特功能組成的大型應用程序，例如用戶管理、產品目錄或訂單處理，這些功能可以邏輯上分開；
- 功能團隊： 特別適用于圍繞功能所有權組織的團隊，每個團隊負責從頭到尾管理一個功能，從而增強協作和責任感
7. 六邊形架構（Ports & Adapters）
六邊形架構，通常稱為端口與適配器，是一種架構模式，強調將核心業務邏輯與外部依賴分離。在這種結構中，核心通過端口（即接口）與外部世界交互，而外部系統如數據庫和 Web 框架則充當實現這些接口的適配器。
project/
├── cmd/
│ └── app/
│ └── main.go
├── internal/
│ ├── core/
│ │ ├── user/
│ │ │ ├── entity.go
│ │ │ └── usecase.go
│ │ └── product/
│ │ └── ...
│ ├── adapters/
│ │ ├── database/
│ │ │ └── user_repo.go
│ │ ├── api/
│ │ │ └── user_handler.go
│ │ └── messaging/
│ │ └── user_event.go
│ └── ports/
│ ├── user_repository.go
│ ├── user_service.go
│ └── ...
├── pkg/
├── configs/
├── go.mod
└── go.sum特點：
- 核心獨立性： 核心業務邏輯獨立于外部層，如框架、數據庫和 API。這樣的獨立性增強了可維護性和靈活性；
- 端口（接口）： 端口定義了核心業務邏輯與外部系統的交互方式，允許核心與其適配器之間建立明確的契約；
- 適配器： 適配器（例如，用于數據庫、API 和消息傳遞）可以輕松更換，而不影響核心邏輯。這有助于測試和重構，因為核心可以與外部依賴項隔離進行測試。
用例：
- 解耦的業務邏輯： 理想用于業務邏輯必須與數據庫、API 或用戶界面框架等外部系統解耦的應用程序，確保靈活性和適應性；
- 外部系統變化的項目： 特別適用于需要靈活性的項目，其中外部系統可能隨著時間而變化，使應用程序能夠在不對核心邏輯進行重大重寫的情況下進行適應。
8. 單一代碼庫（Monorepo）
單一代碼庫是一個包含多個服務或庫的單一倉庫。這種結構通常在大型組織中使用，允許不同的項目獨立開發和部署，同時仍然在統一的代碼庫中運行。
project/
├── services/
│ ├── user-service/
│ │ ├── cmd/
│ │ │ └── main.go
│ │ ├── internal/
│ │ │ ├── handler/
│ │ │ ├── service/
│ │ │ ├── repository/
│ │ │ └── models/
│ │ ├── go.mod
│ │ └── go.sum
│ └── product-service/
│ ├── cmd/
│ ├── internal/
│ └── go.mod
├── libs/
│ ├── logging/
│ ├── authentication/
│ └── utils/
├── go.mod
└── go.sum特點:
- 多個服務： 每個服務（例如，user-service、product-service）都是自包含的并獨立運行，但它們都位于同一個代碼庫中；
- 共享庫： 常用工具和庫（如日志記錄和身份驗證）可以組織在一個libs/目錄中，允許在不同服務之間重用；
- 共享模塊： 項目可以有一個頂層go.mod文件用于單體代碼庫，或者每個服務可以根據所需的模塊化程度擁有自己的go.mod文件。
- 代碼共享與一致性： 鼓勵共享代碼并在多個服務之間保持一致性，減少重復并確保標準化。
用例：
- 大型組織： 非常適合擁有多個團隊的大型組織，這些團隊在獨立服務上工作，同時需要共享庫和一致的實踐；
- 微服務架構： 對于微服務架構或多服務系統特別有效，因為它簡化了在單個代碼庫內的協作和協調。
9. CQRS（命令查詢責任分離）
在 CQRS（命令查詢責任分離）中，命令和查詢操作被組織成獨立的模型。命令負責改變狀態（例如，創建或更新數據），而查詢則專注于讀取數據。這種結構增強了處理請求時的關注點分離。
project/
├── cmd/
│ └── app/
│ └── main.go
├── internal/
│ ├── commands/
│ │ ├── create_user.go
│ │ ├── update_user.go
│ │ └── delete_user.go
│ ├── queries/
│ │ └── get_user.go
│ ├── repositories/
│ │ └── user_repo.go
│ ├── models/
│ │ └── user.go
│ └── services/
│ └── user_service.go
├── configs/
├── go.mod
└── go.sum特點：
- 職責分離： 命令和查詢被劃分為不同的模型，簡化了代碼庫的擴展和維護；
- 可擴展架構： 該結構特別適合需要分別優化讀寫操作的應用程序，非常適合大規模系統；
- 解耦： 促進命令和查詢處理邏輯之間的明確分離，使兩種操作的管理更加容易。
用例：
- 獨特的讀寫需求： 最適合需要以不同方式管理讀寫操作的應用程序，尤其是在事件驅動架構或高性能應用中；
- 事件源和一致性： 對于需要事件源或具有復雜數據一致性要求的系統非常有用，能夠更清晰地處理狀態變化。
10. 洋蔥架構（Onion Architecture）
洋蔥架構強調通過將代碼組織成圍繞中心核心的同心圓（或層）來實現關注點分離。最內層代表業務邏輯和領域模型，而外層則包含外部依賴項，例如框架、用戶界面和數據庫。
project/
├── cmd/
│ └── your-app/
│ └── main.go
├── internal/
│ ├── domain/
│ │ ├── entity.go
│ │ └── service.go
│ ├── application/
│ │ ├── usecase.go
│ └── infrastructure/
│ ├── persistence/
│ │ ├── repository.go
│ ├── api/
│ │ └── handler.go
│ └── ...
├── pkg/
│ └── shared/
├── configs/
│ └── config.yaml
└── go.mod特點：
- 分層方法： 架構呈同心圓結構，最內層代表核心領域，外層代表應用程序的接口和基礎設施；
- 依賴倒置： 核心領域邏輯獨立于外部框架和技術，促進可維護性和可測試性；
- 關注點分離： 每一層都有明確的責任，有助于隔離更改并最小化副作用；
- 關注業務邏輯： 核心業務邏輯位于中心，使應用程序能夠演變而不影響外部依賴；
- 可測試性： 由于核心邏輯與基礎設施解耦，因此更容易為領域和應用層編寫單元測試；
用例：
- 復雜業務領域: 適用于具有復雜業務規則的應用程序，這些規則需要明確的關注點分離。
- 長期項目: 理想用于預計會隨著時間演變的項目，使開發人員能夠在不進行重大重寫的情況下適應業務需求的變化。
- 角色清晰的團隊: 當不同團隊負責應用程序的不同層面（例如，業務邏輯與基礎設施）時效果良好。
11. 常見架構
通用結構適用于更簡單的項目或場景，在這些場景中，開發速度和易于理解優先于嚴格的架構指導方針。它允許靈活性，但從長遠來看可能導致可維護性較差的代碼。
project/
├── cmd/
│ └── myapp/
│ └── main.go
├── internal/
│ ├── app/
│ │ └── myapp/
│ │ ├── handler.go
│ │ └── service.go
│ ├── pkg/
│ │ └── myprivlib/
│ ├── domain/
│ │ ├── entity.go
│ │ └── service.go
│ └── infrastructure/
│ ├── persistence/
│ │ └── repository.go
│ ├── api/
│ │ └── handler.go
│ └── messaging/
│ └── producer.go
├── pkg/
│ └── mypubliclib/
├── vendor/
├── api/
│ └── api_spec.yaml
├── web/
│ ├── static/
│ └── templates/
├── configs/
│ └── config.yaml
├── init/
│ └── myapp.service
├── scripts/
│ ├── build.sh
│ └── install.sh
├── build/
│ ├── package/
│ └── ci/
├── deployments/
│ └── kubernetes/
├── test/
│ └── data/
├── docs/
│ └── architecture.md
├── tools/
│ └── mytool/
├── examples/
│ └── example_usage.go
├── third_party/
├── githooks/
├── assets/
├── website/
│ └── index.html
├── go.mod
└── go.sum特點：
- 簡潔性： 一種直接的結構，能夠組織代碼而不帶來過度的復雜性；
- 單層抽象：常見結構可能不會像洋蔥或清晰架構那樣強制分層，從而導致較少的抽象；
- 最小依賴管理：管理依賴的開銷較少，使新手更容易理解項目布局；
- 靈活的代碼組織：開發者可以根據項目需求組織代碼，而不是遵循嚴格的架構指南，從而允許創造性解決方案。
用例：
- 小型到中型項目：適合較小的應用程序或項目，其中復雜性可控，嚴格的關注點分離可能顯得多余；
- 快速原型開發：助于快速迭代想法，而無需維護嚴格的架構框架；
- 單開發者項目：適合喜歡簡單、結構較少環境的個人開發者來構建應用程序；
- 學習和實驗：適合學習 Go 的初學者或那些嘗試新想法的人，因為它允許探索而不會被架構決策拖累。
三、結論
為你的項目選擇合適的文件夾結構至關重要，這取決于多個因素，包括應用程序的規模和復雜性、團隊協作以及未來的可維護性。
理想的結構應與你的具體需求和偏好相一致，確保它促進開發并增強整體代碼庫的組織性。
通常，從滿足你當前需求的簡單結構開始是有益的，并在項目發展或需求變化時進行重構。這種靈活性使你能夠適應新的挑戰，同時保持清晰和可管理的代碼庫。
責任編輯：趙寧寧
來源：
令飛編程
