最近微信群里有小伙伴再次提出了靈魂疑問：

Go 項目應該怎么組織目錄結構？

這是個反復出現的問題。網上確實有一些過度復雜的博客和示例倉庫，把很多同學都整糊涂了。

今天我們來梳理一下常見的“坑”，以及更實用的項目組織方式。

畢竟 Go 這一門編程語言的核心哲學是：less is more，少點花里胡哨的層次。

核心原則（一句話版）

• 先把可用的東西做出來，再考慮拆包。
• 不要為了 “某種慣例” 或 “看起來專業” 而過度設計。
• internal/、pkg/、cmd/ 這些都是工具，并不是每個項目都必須要用的。

要點與示例

1. main 放哪里？

建議：主程序（CLI / server）放在倉庫根目錄的 main（或直接 main.go）是最簡單也最常用的。

優勢之一是安裝/運行最短路徑。

便于 go install：

# 最短最干凈的安裝方式（root 有 main）
go install github.com/eddycjy/project@latest

只有庫（library）的倉庫自然沒有 main。如果既有庫又有二進制，可以把 main 放子目錄（很多人習慣 cmd/yourcmd/，但 cmd 本身并非必須）。

示例（根目錄有 main）：

/project
  go.mod
  main.go      // 程序入口
  lib/         // 如果你還有對外庫
  internal/    // 可選
  README.md

或者把可復用代碼放到一個清晰命名的包，而不是把 main 挪得過遠。

2. internal/ 是特性不是儀式

internal/ 的機制是 Go 工具鏈強制的：internal 下的代碼只能被父目錄（和子級樹）里的包導入。

好處是可以阻止外部依賴，但不是每個項目都需要它。

這時候就涉及到什么時候用？

當你真的有很多對外不暴露但跨包復用的代碼，并且項目會被大量第三方使用時才考慮 internal/。

對絕大多數小中型項目來說，不用 internal/ 更簡單、更靈活。

示例（使用場景）：

/project
  internal/
    secrets/   // 只有 project 內部可以 import
  pkg/         // 對外可用庫（慎用 pkg_/）
  main.go

3. 別盲目使用 pkg/

pkg/ 是歷史遺留的慣例，在現代 Go 里沒必要把所有對外包都塞進 pkg/。

包名與路徑應以可讀性與語義為核心。把包放到頂層（/auth、/db、/storage）通常更直觀，且導入路徑更短。

示例對比：

不推薦（多一層 pkg）：

import "github.com/you/project/pkg/storage"

更推薦（語義清晰）：

import "github.com/you/project/storage"

4. 不要亂建 util、common 等

“工具類” 包看起來方便，但會變成隨手塞東西的垃圾倉庫。把函數/類型放到語義化更強的包里，或放在最常用的使用位置鄰近代碼，而不是一個籠統的 util。

反面示例：

// util/strings.go
package util
func Reverse(s string) string { ... }

更好寫法（語義化）：

// text/reverse.go
package text
func Reverse(s string) string { ... }

// 或者直接放在使用它的包里，例如 handler/text_helpers.go

5. 包不要太多（也別千行一包）

Go 可以在一個包里有多個文件，這一點要善用。每新增一個包，就可能增加依賴、回環風險和遷移成本。相反，也不要把完全不相關的代碼塞成一個冗長的包——保持“以用途/語義分包”。

經驗規則：

• 如果一組代碼有同一語義與同一生命周期，放到同一個包。
• 每個包最好能在 200–1000 行范圍內（這不是硬性規則，只是可讀性提醒）。
• 切包優先按“用途”而不是“文件大小”。

6. 文件別太細碎

許多人喜歡把每個小函數放不同文件，結果翻代碼像翻書頁。合理把相關函數聚合到同一文件，便于閱讀。

避免把每個 tiny helper 分成獨立文件。

7. 語義化命名優先于目錄深度

庫名、包名與目錄名應體現用途。例如 applog 比 util/log 更有意義。

這樣看代碼的同學通過 import 一眼能看出大致的用途。

8. 版本管理和 semver 建議

建議盡量使用 0.x 階段語義化版本（保守上 v0.x），在你要打破 API 時給出明確變更說明，而不是過早把版本固定為 v2/v3，導致用戶為小改動分叉倉庫。

換句話說：先發布、后演進，記錄變更而不是封閉。

推薦的最小倉庫模板（實戰）

下面給出一個適合多數小中型項目的極簡布局，能覆蓋 CLI / library 混合場景：

/project
  go.mod
  main.go             // 如果是二進制，把入口放這里
  README.md
  config/              // 配置相關包
  storage/             // 存儲邏輯
  api/                 // HTTP handler / grpc / rpc
  tools/               // 非構建、非導出的腳本 & 工具（可忽略 go build）
  docs/

如果你確實需要多個可發布包，再考慮增加清晰命名的子包，而不是 pkg/ 通用層。

Go 官方建議，要關注細節

Go 官方確實給了一份指南：go.dev/doc/modules/layout[1]。

里面有句話經常被曲解：

Larger packages or commands may benefit from splitting… Initially, put them in internal/.

這里的重點其實是 larger 和 may。

結果很多人一上來就機械套用：不管項目大小，先建個 internal/；

現實是要知道目錄不是 “一步到位” 的事，需要階段性調整和設計。

總結

我們要回歸 Go 的哲學：簡單優先，先能跑，再優雅。多數團隊在項目初期做的過度工程（把 internal/、pkg/、cmd/ 都直接套上）更多是為了 “看起來成熟”，但長期結果往往是維護負擔增加。

把注意力放在清晰的包命名、合理的功能邊界、良好的 README 上，必要時再重構目錄結構和演進會比較好。

參考資料

[1] go.dev/doc/modules/layout: https://go.dev/doc/modules/layout