如何組織 Go 代碼？Go 作者的回答驚呆了

程序應該是爲人們閱讀而編寫的，只是偶然地供機器執行——Abelson 和 Sussman

這是最常見的問題之一。你可以通過互聯網尋找這個問題的答案。不過，我不確認我的設計是否 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 帳戶，並連接到 VPN 才能在我的 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

本文由 Readfog 進行 AMP 轉碼，版權歸原作者所有。
來源：https://mp.weixin.qq.com/s/ciAQo0bgjFd3Ktq9ryYecQ