如何組織 Go 代碼？Go 作者的回答驚呆了
這是最常見的問題之一。你可以通過互聯網尋找這個問題的答案。不過，我不確認我的設計是否 100% 正確，但希望給你一些參考。
前段時間，我有幸見到了 Robert Griesemer[1](Go 的作者之一)。我們問了他這個問題：“如何組織 Go 代碼?”。他說：“我不知道。” - 這很顯然并不令人滿意，我知道。當我們問他如何設計他的代碼時，Robert 說他總是從扁平結構開始，并在必要時創建包。
我花了很多時間在生產應用程序的兩個寵物項目中嘗試不同的方法。在本文中，我將向你展示所有選擇并告訴你它們的優缺點。閱讀完這篇博文后，你將不會有一種“統治所有模式的模式”。
01 在我們開始之前
無論你如何組織代碼，你都必須考慮閱讀它的人。最重要的是你不應該讓你的貢獻者或同事思考。把所有東西都放在明顯的地方。不要重新發明輪子。你還記得 Rob Pike[2] 說過的關于 go fmt 的話嗎?
Gofmt 的風格沒有人喜歡，但 gofmt 是每個人的最愛。
你可能不喜歡眾所周知的模式。堅持下去對我們和整個社區都更好。但是，如果你有充分的理由做出不同的決定，那也沒關系。如果你的包設計良好，源代碼樹會很好地反應出來。
讓我們從文檔開始。每個開源 Go 項目在 pkg.go.dev[3] 上都有它的文檔。對于每個包，你首先看到的是包的概述。以net/http包為例，在描述每個公共函數、常量或類型之前，你需要對包提供的內容進行描述。你可以從中學習如何使用 API 和更深入的細節。從哪個來源生成概覽?該net/http包有一個 doc.go[4] 文件，作者在其中放置了該包的一般描述。你可以將此概述放在文件夾中的任何其他文件中，但 doc.go 大家公認的標準。
那么Readme文件中應該有什么?首先，對這個項目的總體概述——它的目標。然后，你應該有一個快速入門部分，你可以在其中描述開始處理項目時應該做的事情，包括任何依賴項，如 Docker 或我們正在使用的任何其他工具。你可以在此處找到基本示例或指向更詳細描述項目的外部網站的鏈接。你必須記住，此處應保留的內容取決于項目。你必須從讀者的角度思考。什么信息對他們最重要?
當你有更多文檔要提供時，將它們放入docs文件夾中。不要將它們隱藏在像/common/docs 中。這種方法有好處：很容易找到，并且在一個拉取請求中，你可以更改公共 API 及其文檔。你不必克隆另一個存儲庫并在它們之間同步更改。
我的下一個建議可能讓你吃驚。我建議使用眾所周知的工具，例如make，我知道有一些替代品，例如 sake[5], mage[6]、zim[7]或 opctl[8]。問題是要開始使用它們，你必須學習它們。如果任何項目都使用不同的自動化工具，新維護人員將更難開始。我的觀點是你應該明智地選擇你的工具。你使用的工具越多，項目啟動工作就越困難，特別有新人加入。
我一直在從事一個項目，我必須在本地運行 2 個不同的依賴項，在 CLI 中登錄到 AWS 帳戶，并連接到虛擬網絡才能在我的 PC 上運行測試。基本設置需要一兩天才能完成，我想我不必告訴你這些測試有多么不穩定[9]。
關于 linting 建議使用 golangci-lint[10]。啟用對你的項目來說似乎合理的所有 linter。通常使用默認啟用的 linter 規則可能是一個好的開始。
02 扁平結構(單包)
讓我們從最推薦的方法開始：只要你不被迫添加新包，就將整個代碼保存在根文件夾中。在項目開始時，這種方式真的挺好。當我開始使用它時，我發現它很有幫助，并且對它最終將如何工作有一個模糊的想法。
將所有內容放在一個地方有助于避免包之間的循環依賴。當你將某些內容放入單獨的包時，你會發現需要根文件夾中的其他內容，你將被迫為此共享依賴項創建第三個包。隨著項目的發展，情況變得更糟。你最終可能會擁有許多包，其中大多數包幾乎都依賴于其他包。許多函數或類型必須是公開的。這種情況模糊了 API，使其更難閱讀、理解和使用。
使用單個包，你不必在文件夾之間跳來跳去并思考架構，因為所有的內容都在一個地方。這并不意味著你必須將所有內容都保存在一個文件中，例如：
- courses/
- main.go
- server.go
- user_profile.go
- lesson.go
- course.go
在上面的例子中，每個邏輯部分都被組織成單獨的文件。當你犯了錯誤并將結構放入錯誤的文件時，你所要做的就是將其剪切并粘貼到新位置。你可以這樣考慮：單個文件代表應用程序的一個實體部分。你可以按代碼(HTTP 處理程序、數據庫存儲庫)或其提供的內容(管理用戶的配置文件)對代碼進行分組。當你需要某樣東西時，你就會知道在哪里可以找到它。
什么時候創建一個新包?如果你有充分的理由這樣做，比如：
1)當你有不止一種啟動應用程序的方式時
假設你有一個項目，并且希望以兩種模式運行它：CLI 命令和 Web API。在這種情況下，創建一個/cmd包并包含 cli和web子包是很常見的。
- courses/
- cmd/
- cli/
- main.go
- config.go
- web/
- main.go
- server.go
- config.go
- user_profile.go
- lesson.go
- course.go
你可以將多個main()函數放入單個文件夾中的單獨文件中。要運行它們，你必須提供一個明確的文件列表來編譯，而其中只有一個要 main()。這使應用程序的運行變得非常復雜。更簡單的方式是直接輸入 go run ./cmd/cli。
當你有一個子包時，./cmd/ 文件夾的使用可能聽起來過于復雜。我發現它在需要添加時很有用，例如，使用來自消息代理的消息。此主題將在拆分依賴項的部分中更詳細地介紹。
2)當你想提取更詳細的實現時
標準庫就是一個很好的例子。讓我們看看 net/http/pprof[11] 包。該net包為網絡 I/O 提供了一個可移植的接口，包括 TCP/IP、UDP、域名解析和 Unix 域套接字。你可以根據此包提供的內容構建你想要的任何協議。net/http 包使我們能夠發送或接收 HTTP 請求。HTTP 協議使用 TCP/UDP，因此http包是 net 的子包是很自然的。net/http/pprof包中的所有類型和方法都可以返回 HTTP 協議，因此自然是一個 http 子包。
database/sql包也是如此。如果你有更多非關系數據庫的實現，它們將放在database包下，和 sql包同級。
你看出來模式了嗎?數據包(packet )在樹中(tree)越深，傳遞的細節就越多。換句話說，每個子包都在父包上提供了更具體的實現。
3)當你開始為密切相關的事物添加公共前綴時
一段時間后，你可能會注意到，為了避免誤解或命名沖突，你開始為函數或類型添加前綴或后綴。通過這樣做，我們試圖模擬項目中缺少包的情況可能是一個好兆頭。很難說什么時候提取新的子包。每次當你看到它提高了 API 的可讀性并使代碼更清晰時請提取新的子包。
- r := networkReader{}
- //
- r := network.Reader{}
如你所見，扁平結構既簡單又強大。在某些用例中，你可能會發現它很有用且很有幫助。這種組織代碼的方式不僅僅適用于小型或新建項目。以下是遵循單包模式的庫示例：
- https://github.com/go-yaml/yaml
- https://github.com/tidwall/gjson
值得記住的是，你不需要不惜一切代價堅持這種組織代碼的方式。保持簡單是有原因的，但添加更多包可能會使你的代碼更好。不幸的是，沒有銀彈。你需要做的是嘗試并詢問你的同事或維護人員哪個選擇對他們來說更具可讀性。
03 模塊化
之前描述的組織代碼的方式在某些場景可能效率不高。我花了很多時間試圖獲得“正確的”項目結構。一段時間后，我注意到對于業務應用程序，我開始嘗試另一種類似的方式組織代碼。
當我們開發直接為客戶提供客戶端的應用程序時，扁平結構可能效率不高。你希望創建提供一組與控制器、基礎設施或業務領域的一部分相關的功能的模塊。讓我們仔細看看兩種最流行的方法，并談談它們的優缺點。
按種類(kind)組織
這個模型很受歡迎。我認識的人沒有提倡使用這種策略來組織代碼的，但我在新舊項目中都發現了它。按種類組織是一種策略，它試圖通過將部分放入基于其結構的桶中，從而為過于復雜的代碼單元帶來秩序。將包稱為repositories 或 model 是很常見的。這樣做的結果是你會創建類似 utils 或者 helpers 的包，因為你覺得應該把一個函數或一個結構放在一個單獨的地方，但沒有找到任何合適的地方。
- .
- ├── handlers
- │ ├── course.go
- │ ├── lecture.go
- │ ├── profile.go
- │ └── user.go
- ├── main.go
- ├── models
- │ ├── course.go
- │ ├── lecture.go
- │ └── user.go
- ├── repositories
- │ ├── course.go
- │ ├── lecture.go
- │ └── user.go
- ├── services
- │ ├── course.go
- │ └── user.go
- └── utils
- └── stings.go
在上面的示例中，你可以看到項目是按類型組織的。你什么時候想添加新功能或修復與課程相關的錯誤，你會從哪里開始尋找?在一天結束時，你將開始從一個包跳到另一個包，希望能在那里找到有用的東西。
Graph that shows dependencies between packages
這種方法有其后果。每個類型、常量或函數都必須是公共的，才能在項目的另一部分中訪問。你最終將大多數類型標記為公有。即使對于那些不應該公開的人。它混淆了應用程序的這一部分中的重要內容。其中許多是可能隨時更改的細節。
另一方面，按種類組織對我們來說是很自然的。我們是在處理程序或數據庫表的類別中思考的技術人員。這就是我們的成長方式，也是我們被教導的方式。如果你沒有經驗，這種方法可能更有益，因為它可以幫助你更快地開始。從長遠來看，你可能會遇到不便，但這并不意味著你的項目會失敗 — 恰恰相反，有很多成功的應用程序都是以這種方式設計的。
按組件組織
組件是應用程序的一部分，它提供獨立的特性，很少或沒有外部依賴。你可以將其視為插件，當你將其中之一移除時，整個應用程序仍然可以運行，但功能有限。它可能發生在運行數月或數年的生產應用程序中。
應用程序可能具有一個或多個提供業務價值的核心組件。在領域驅動設計術語中，組件是有界上下文。我們將在以后的文章中用 Go 的上下文來描述 DDD。
包的 API 應該描述包提供的內容而不是更多。它不應該暴露任何從消費者的角度來看不重要的低級細節。它應該盡可能簡約。消費者可能是另一個包或另一個導入我們代碼的開發人員。
該組件應包含提供業務價值所需的一切。這意味著，每個存儲、HTTP 處理程序或業務模型都應該存儲在文件夾中。
- .
- ├── course
- │ ├── httphandler.go
- │ ├── model.go
- │ ├── repository.go
- │ └── service.go
- ├── main.go
- └── profile
- ├── httphandler.go
- ├── model.go
- ├── repository.go
- └── service.go
由于以這種方式組織代碼，當你擁有與任務相關的課程時，你就知道從哪里開始尋找。它沒有分布在整個應用程序中。然而，要實現良好的模塊化并不容易。可能需要多次迭代才能實現一個好的封裝 API。
還有一個挑戰。如果這些包相互依賴怎么辦?假設你想在用戶的個人資料上顯示最近的課程。它們應該共享相同的存儲庫或服務嗎?
在這種特殊情況下，從個人信息(profile)文件的角度來看，課程是一種外部依賴。解決該問題的最佳方法是在 profile 必須需要的方法的包中創建一個接口。
- type Courses interface {
- MostRecent(ctx context.Context, userID string, max int) ([]course.Model, error)
- }
在course包中，你公開了一個實現此接口的服務。
- type Courses struct {
- // maybe some unexported fields
- }
- Func (c Courses) MostRecent(ctx context.Context, userID string, max int) ([]Model, error) {
- // return most recent coursers for specific user
- }
在main.go中你從course包中創建Courses的結構實例并將其傳遞給profile包。在profile包中的測試中，你創建了一個 mock 實現。因此，你甚至可以在沒有course實現包的情況下開發和測試 profile 功能。
如你所見，模塊化使代碼更具可維護性和可讀性，但它需要你更加努力地思考你的決策和依賴關系。該邏輯可能看起來非常適合新包，但似乎太小了。另一方面，在處理項目期間，現有包的部分可能會開始增多，并在一段時間后提升為自主代碼段。
當代碼在包內部增多時，你可能會問自己：如何組織單個模塊內部的代碼?這是另一個難以回答的問題。在本節中，我展示了使用應用程序組件時的扁平結構。但是，有時這還不夠……
04 簡潔的架構
你可能聽說過以下術語：Clean Architecture[12]、Onion Architecture 或類似術語。Uncle Bob 寫了一本書[13]，詳細描述了每一層的含義以及應該或不應該包含的內容。這個想法很簡單。你的應用程序或模塊有 4 層(取決于你的代碼庫有多大)：Domain、Application、Ports、Adapters。在某些來源中，名稱可能不同。例如，作者沒有使用 Ports 和 Adapters，而是使用 Inbound 和 Outbound。核心思想類似。讓我們用例子來描述每一層。
Domain
這是我們應用程序的核心。每個業務邏輯都應該在這里。這意味著如果更改或添加任何業務需求，你必須更新我們的域部分。這個包應該沒有任何外部依賴。它不應該知道這段代碼是在哪個上下文中執行的。這意味著，它不應該依賴任何基礎設施部分或知道任何 UI 細節。
- course := NewCourse("How to use Go with smart devices?")
- s := course.AddSection("Getting started")
- l := s.AddLecture("Installing Go")
- l.AddAttachement("https://attachement.com/download")
- // etc
請注意，此時你并不關心課程的存儲位置或如何添加新課程(使用 HTTP 請求或使用 CLI)。在domain包中，你描述了課程可能包含的內容以及你可以對其進行的操作。就這些!
Application
該層包含應用程序的每個用例。它是基礎設施和 Domain 之間的粘合點。在這個地方，你獲得輸入(從它來自的任何地方)，將其應用于域對象，然后將其保存或發送到其他地方。
- func (c Course) Enroll(ctx context.Context, courseID, userID string) error {
- course, err := c.courseStorage.FindCourse(ctx, courseID)
- if err != nil {
- return fmt.Errorf("cannot find the course: %w")
- }
- user, err := c.userStorage.Find(ctx, userID)
- if err != nil {
- return fmt.Errorf("cannot find the user: %w")
- }
- if err = user.EnrollCourse(course); err != nil {
- return fmt.Errorf("cannot enroll the course: %w")
- }
- if err = c.userStorage(ctx, user); err != nil {
- return fmt.Errorf("cannot save the user: %w")
- }
- return nil
- }
在上面的代碼中，你可以找到用戶注冊課程的用例。它是兩部分的組合：與域對象(User，Course)和基礎設施(存儲和獲取數據)交互。
Adapters
適配器也稱為 Outbound 或基礎設施(Infrastructure)。該層負責與外界存儲和獲取數據。它可以是數據庫、blob 存儲、文件系統或其他(微)服務。通常，該層在應用程序層的接口中具有其表示形式。它有助于在不運行數據庫或將文件寫入文件系統的情況下測試應用程序層。
適配器是對低級細節的抽象，因此你軟件的其他部分不必“知道”你使用的是哪個數據庫版本、SQL 查詢長什么樣或你存儲文件的位置。
Ports
Ports(稱為 Inbound)是應用程序的這一部分，負責從用戶那里獲取數據。它可以是 HTTP 處理程序、事件處理程序或 CLI 命令。它獲取用戶的輸入并將其傳遞給 Application 層。此操作的結果返回到 Port。
- func enrollCourse(w http.ResponseWriter, r *http.Request) {
- body, err := io.ReadAll(r.Body)
- if err != nil {
- w.WriteHeader(http.StatusBadRequest)
- logger.Errorf("cannot read the body: %s", err)
- return
- }
- req := enrollCourseRequest{}
- if err = json.Unmarshal(body, &req); err != nil {
- w.WriteHeader(http.StatusBadRequest)
- logger.Errorf("cannot unmarshal the request: %s", err)
- return
- }
- if err = validate.Struct(req); err != nil {
- w.WriteHeader(http.StatusBadRequest)
- logger.Errorf("cannot validate the request: %s", err)
- return
- }
- if err = app.EnrollCourse(req.CourseID, req.UserID); err != nil {
- w.WriteHeader(http.StatusInternalServerError)
- logger.Errorf("cannot enroll the course: %s", err)
- return
- }
- }
請注意，編寫執行相同邏輯的 CLI 命令很簡單。唯一的區別是輸入的來源。
- var userID string
- var courseID string
- var enroleCourseCmd = &cobra.Command{
- Use: "courseID userID",
- Args: cobra.MinimumNArgs(2),
- Run: func(cmd *cobra.Command, args []string) {
- if err = app.EnrollCourse(courseID, userID); err != nil {
- w.WriteHeader(http.StatusInternalServerError)
- logger.Errorf("cannot enroll the course: %s", err)
- return
- }
- },
- }
保持這些層的整潔和一致可能會給你的代碼帶來很多價值。它易于測試，職責明確，從哪里開始尋找要更改的代碼更加明顯。如果是與課程相關的錯誤并且是業務邏輯問題，則你將開始檢查 Domain 或 Application 層。
另一方面，很難保持界限清晰和一致。它需要大量的自律、經驗和至少幾次迭代才能正確完成。這就是為什么很多人在這個領域失敗的原因。
05 總結
組織代碼很困難。更困難的是，應用程序的體系結構在其生命周期內可能會更改幾次，進化。你可以從扁平結構開始，但最終會得到多個模塊和許多子包。不要期望第一次就做對。它可能需要多次迭代并從其他人那里收集反饋。
此外，你可以根據應用程序的不同部分混合不同的代碼組織方式。在你的業務邏輯部分，可以從模塊化開始。但是，許多應用程序需要的實用程序就不適合用現有的包，你可以在那里遵循扁平結構模式。
原文鏈接：https://developer20.com/how-to-structure-go-code/
參考資料
[1]Robert Griesemer: https://en.wikipedia.org/wiki/Robert_Griesemer
[2]Rob Pike: https://www.youtube.com/watch?v=PAAkCSZUG1c
[3]pkg.go.dev: https://pkg.go.dev/
[4]doc.go: https://github.com/golang/go/blob/master/src/net/http/doc.go
[5]sake: http://tonyfischetti.github.io/sake/
[6]mage: https://github.com/magefile/mage
[7]zim: https://github.com/fugue/zim/
[8]opctl: https://opctl.io/
[9]不穩定: https://testing.googleblog.com/2020/12/test-flakiness-one-of-main-challenges.html
[10]golangci-lint: https://github.com/golangci/golangci-lint
[11]net/http/pprof: https://pkg.go.dev/net/http/pprof
[12]Clean Architecture: https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html
[13]寫了一本書: https://www.amazon.com/Clean-Architecture-Craftsmans-Software-Structure/dp/0134494164
本文轉載自微信公眾號「幽鬼」，可以通過以下二維碼關注。轉載本文請聯系幽鬼公眾號。
