工程結構與 Go Modules
Go Project Layout and Go Modules
從 go mod init 開始,講清楚模組、套件與目錄的關係,cmd 與 internal 該怎麼放,依賴怎麼選版本,以及多個服務共用一個儲存庫時該用單一模組還是 go.work。
這篇的步驟
這是「用 Go 打造微服務」系列的第一篇。整個系列共 34 篇,分成八個階段,以一間線上商店的訂單服務為主線,照順序讀,每篇都接著上一篇:
- 一、Go 地基(第 1~4 篇):工程結構、錯誤處理、並發、context,先把語言基本功打穩。
- 二、寫一個服務(第 5~8 篇):HTTP 中介層、分層與依賴注入、資料庫交易、測試,寫出一個結構清楚、測得了的單體服務。
- 三、拆成微服務(第 9~12 篇):什麼時候該拆,把它拆成
api-gateway、order、payment、inventory,處理 gRPC、API Gateway、服務發現。 - 四、可靠性(第 13~16 篇):逾時、重試、熔斷、冪等、訊息佇列與分散式交易。
- 五、上線與維運(第 17~20 篇):可觀測性、優雅關閉、單一服務的容器與 Kubernetes 部署、效能調校。
- 六、實戰部署(第 21~23 篇):用 Docker Compose 與 Kubernetes 部署整套系統,再回頭看系統怎麼從十萬、百萬到千萬級一步步演進。
- 七、實戰踩坑(第 24~26 篇):併發、支付與金額處理的常見問題。
- 八、安全與 AI 協作(第 27~33 篇):安全性,以及用 Claude Code 與 AI 工作流開發、審查、部署、排查、debug 與安全性檢查,最後用 Go 寫 MCP server 接上 OpenProject。
最後一篇是番外(第 34 篇),談服務與文件上線後,怎麼讓搜尋引擎與 AI 找到它們。程式碼從頭到尾沿用同一個儲存庫。
這篇要解決什麼
剛開始寫 Go 的人,最常卡住的往往不是語法,而是「檔案要放哪裡」:一個資料夾可以放幾個套件?main 要放在根目錄還是 cmd/?internal 到底有什麼魔法?為什麼 go.sum 會一直變長?加了一個依賴之後,最後編進執行檔的到底是哪個版本?
這些問題在單一小工具上不太明顯,但當系統慢慢長成好幾個服務(後面整個系列要做的就是這件事)時,一開始的目錄與模組邊界會直接影響:哪些程式碼能被別的服務引用、升級依賴時會牽動多少地方、CI 要怎麼切、Docker 映像檔要怎麼建置。改結構的成本會隨著程式碼量線性甚至超線性成長,所以值得在第一篇就把地基打穩。
這篇會從零建立線上商店 example.com/shop 的骨架,先只有訂單服務,一步一步加入套件、命令列進入點、內部套件、外部依賴,最後談多服務儲存庫的取捨。讀完你應該能回答:
- 模組(module)、套件(package)、目錄三者的對應關係是什麼。
cmd/、internal/、pkg/各自解決什麼問題,什麼時候不需要它們。- Go 如何用「最小版本選擇」決定依賴版本,
go.sum又在保護什麼。 - 一個儲存庫裡有多個服務時,單一模組與多模組+
go.work的差別。
第 1 步:建立模組,看懂 go.mod
Go Modules 是 Go 官方的依賴管理與建置單位。一個「模組」就是一棵目錄樹,根目錄有一個 go.mod 檔,宣告這棵樹的「模組路徑」以及它依賴哪些其他模組。先建立一個空專案:
mkdir shop && cd shop
go mod init example.com/shop產生的 go.mod 很短:
module example.com/shop
go 1.24這裡有兩件事要理解。
模組路徑就是匯入路徑的前綴
module 那一行宣告的字串,會成為這個模組內所有套件匯入路徑的前綴。之後在 internal/order 目錄底下的套件,它的匯入路徑就是 example.com/shop/internal/order。這個路徑不需要真的能在網路上存取,但如果模組要被別人用 go get 取得,它就必須對應到一個可以下載原始碼的位置,例如 github.com/帳號/儲存庫。常見做法是:會公開的模組用真實的程式碼託管網址;只在公司內部或單一儲存庫內使用的模組,可以用一個自己控制的網域名稱,避免日後搬家時要改所有匯入路徑。
go 指令行代表語言版本,不只是註解
go 1.24 這行不是裝飾。從 Go 1.21 起它是「最低需求版本」:工具鏈若比它舊,會拒絕建置(或依 toolchain 設定自動下載新版工具鏈)。更重要的是,它決定了語言語意。例如 Go 1.22 起,for 迴圈的變數改成「每一次迭代一個新變數」,這個行為只在 go.mod 宣告 1.22 以上時生效。同一份程式碼在 go 1.21 與 go 1.22 的模組裡,閉包抓到的迴圈變數可能不一樣。所以升級這一行時,要當成一次語言升級來測試,而不是隨手改個數字。
提示:
toolchain指令行(例如toolchain go1.24.3)是「建議用哪一版工具鏈建置」,go指令行是「最低語言版本」。團隊想鎖定 CI 與本機一致時,常見做法是兩者都寫,並在 CI 中設定GOTOOLCHAIN=local以避免在建置過程中偷偷下載。
第 2 步:套件就是目錄
Go 的規則非常單純:一個目錄就是一個套件(測試用的 _test 外部套件是唯一例外)。同一個目錄下的所有 .go 檔必須宣告同一個 package 名稱,它們彼此可以直接看到對方的所有識別字,不需要匯入。不同目錄就是不同套件,必須透過匯入路徑引用,而且只看得到大寫開頭(匯出)的名稱。
這帶來幾個實務上的結論:
| 觀念 | 說明 | 實務影響 |
|---|---|---|
| 可見性只有兩級 | 大寫開頭對外匯出,小寫只在套件內可見 | 沒有 protected、沒有「同一模組可見」,要靠目錄切分來控制 |
| 套件名稱是呼叫端的前綴 | 呼叫端寫 order.New(),不是 New() | 名稱要短、是名詞,避免 order.OrderService 這種重複 |
| 不能循環匯入 | A 匯入 B,B 就不能再匯入 A | 套件的依賴必須是有向無環圖,強迫你想清楚分層 |
| 目錄名不必等於套件名 | 但慣例上應該一致 | 不一致會讓讀者每次都得打開檔案確認 |
用一個小例子對照。假設 internal/order 目錄底下有兩個檔案,它們屬於同一個套件,可以互相使用小寫的識別字;呼叫端則只看得到大寫開頭的名稱:
// 片段:internal/order/order.go
package order
import "errors"
// Status 是訂單狀態;大寫開頭,其他套件可以使用 order.Status。
type Status string
const (
StatusPending Status = "pending"
StatusPaid Status = "paid"
StatusCancelled Status = "cancelled"
)
// Item 是訂單中的一個品項;金額一律以「分」為單位的 int64 表示,避免浮點誤差。
type Item struct {
SKU string
Qty int
Price int64 // 單價,單位:分
}
// Order 對外匯出,欄位也都匯出;呼叫端寫成 order.Order。
type Order struct {
ID string
UserID string
Items []Item
Total int64 // 單位:分
Status Status
}
// New 是建構函式;呼叫端寫成 order.New(...),讀起來就是「新訂單」。
func New(id, userID string) *Order {
return &Order{ID: id, UserID: userID, Status: StatusPending}
}
// AddItem 會呼叫小寫的 validQty;它定義在同一套件的另一個檔案,套件外看不到。
func (o *Order) AddItem(it Item) error {
if !validQty(it.Qty) {
return errors.New("order: quantity must be positive")
}
o.Items = append(o.Items, it)
o.Total += it.Price * int64(it.Qty)
return nil
}注意命名:呼叫端寫 order.New、order.StatusPaid,套件名稱已經提供了語境,所以函式不必叫 NewOrder;型別 Order 與套件同名是少數可以接受的重複,因為它就是這個套件的核心。
套件命名最常見的錯誤,是用 utils、common、helpers 這類名稱。它們沒有描述「這個套件提供什麼」,結果什麼都往裡面丟,最後幾乎每個套件都匯入它,任何小改動都會觸發整個專案重新編譯,甚至形成循環匯入的壓力。比較好的做法是依「提供的能力」命名:money(金額計算)、clock(可替換的時間來源)、retry(重試策略)。如果真的想不到名字,通常代表這段程式碼應該就留在使用它的那個套件裡。
另一個要知道的規則是 main 套件。只有 package main 且包含 func main() 的套件能被建置成執行檔。main 套件不能被其他套件匯入,所以它應該盡量薄:讀設定、組裝依賴、啟動伺服器,然後把真正的邏輯交給其他套件。這個原則在後面〈分層架構與依賴注入〉會再展開。
第 3 步:用 cmd 與 internal 排出骨架
有了「套件就是目錄」的概念,就可以排出服務的骨架。下面是一個常見、但刻意保持精簡的結構:
圖:cmd 底下每個子目錄是一個執行檔;internal 底下的套件只有本模組能匯入。
shop/
├── go.mod # module example.com/shop
├── go.sum
├── cmd/
│ ├── order/ # 訂單服務的進入點(package main)
│ │ └── main.go
│ ├── payment/ # 之後拆出來的服務,也各自一個進入點
│ ├── inventory/
│ └── api-gateway/
├── internal/
│ ├── order/ # 訂單領域:一個領域一個套件
│ │ ├── handler.go # HTTP 處理器
│ │ ├── service.go # 業務邏輯
│ │ └── repository.go # 資料存取
│ ├── payment/
│ └── inventory/
├── api/proto/ # 服務之間的 API 定義(gRPC 那篇才會用到)
└── deploy/ # docker compose 與 k8s 設定一開始只需要 cmd/order 與 internal/order,其他目錄是系列後面才會逐步長出來的,這裡先列出來讓你知道最終的樣子。
cmd/:一個子目錄一個執行檔
同一個儲存庫裡往往不只一個執行檔:每個服務一個,有時還有資料庫遷移工具、一次性的資料修補程式。把它們分別放在 cmd/<名稱>/main.go,用 go build ./cmd/order 就能建置出名為 order 的執行檔(執行檔名稱取自目錄名)。如果整個模組只會有一個執行檔,直接把 main.go 放在根目錄也完全沒問題,不必為了「看起來專業」硬加 cmd/。
internal/:編譯器保證的邊界
internal 是 Go 工具鏈唯一內建語意的目錄名稱:路徑中含有 internal 的套件,只能被「internal 的上一層目錄」底下的套件匯入。以上面的結構來說,example.com/shop/internal/order 只能被 example.com/shop/... 底下的套件使用,其他模組試圖匯入會直接編譯失敗。
這個保證在微服務架構裡特別有價值。它擋住的是「其他模組」;同一個模組裡的 cmd/payment 技術上仍然匯入得到 internal/order。服務之間應該只透過 API(HTTP、gRPC、訊息)溝通,而不是直接匯入彼此的 Go 套件;一旦訂單服務的資料庫存取程式碼被庫存服務匯入,兩個服務就在原始碼層級耦合了,之後誰都不敢改。所以 internal/ 守住對外的邊界,服務與服務之間的邊界則要靠慣例與程式碼審查(也可以用 internal/order/internal/... 再巢狀一層,讓編譯器只允許 internal/order 底下使用)。
pkg/ 要不要?
很多範本專案會有 pkg/ 目錄,用來放「打算給外部使用」的套件。它沒有任何工具鏈語意,純粹是慣例。實務上的建議是:如果你確實有要提供給其他模組使用的程式庫(例如共用的客戶端 SDK),把它放在清楚命名的頂層目錄或獨立模組即可;如果沒有,就不需要 pkg/。預設把東西放進 internal/,等到真的有外部使用者時再搬出來,這比反過來安全得多,因為「把匯出的東西收回來」會破壞別人的程式碼,而「把內部的東西公開」不會。
提示:不要一開始就照搬某個「標準專案結構」範本,建立十幾個空目錄。Go 社群的共識是結構跟著需求長:先有
go.mod和main.go,套件多到需要分組時再加internal/,執行檔超過一個時再加cmd/。
第 4 步:讓進入點知道自己是哪個版本
在多服務環境中,一個很實際的需求是:線上跑的到底是哪一版?出問題時,日誌與監控要能對應回某個 commit。Go 1.18 起,工具鏈會自動把模組版本、依賴清單與版本控制資訊(commit、時間、是否有未提交的修改)嵌進執行檔,程式可以用 runtime/debug.ReadBuildInfo 讀出來,不必再自己用 -ldflags 塞變數。
下面是一個完整的進入點範例,它印出自己的建置資訊,並示範「main 只做組裝」的寫法:
package main
import (
"flag"
"fmt"
"log/slog"
"os"
"runtime/debug"
)
// buildInfo 從執行檔內嵌的資訊取出模組路徑、版本與 commit。
func buildInfo() (path, version, revision string) {
info, ok := debug.ReadBuildInfo()
if !ok {
return "unknown", "unknown", "unknown"
}
path, version, revision = info.Main.Path, info.Main.Version, "unknown"
for _, s := range info.Settings {
if s.Key == "vcs.revision" {
revision = s.Value
}
}
return path, version, revision
}
func main() {
showVersion := flag.Bool("version", false, "印出版本後結束")
addr := flag.String("addr", ":8080", "HTTP 監聽位址")
flag.Parse()
path, version, revision := buildInfo()
if *showVersion {
fmt.Printf("%s %s (%s)\n", path, version, revision)
return
}
logger := slog.New(slog.NewJSONHandler(os.Stdout, nil)).With(
"service", "order",
"version", version,
"revision", revision,
)
logger.Info("starting", "addr", *addr)
// 真正的伺服器組裝會在〈net/http 與中介層〉補上。
}幾個細節:
info.Main.Version在go build本地建置時通常是(devel)或依 git 標籤推算出的偽版本;用go install 模組@v1.2.3安裝時則是正式版本。vcs.revision、vcs.time、vcs.modified只有在版本控制目錄內建置、且沒有用-buildvcs=false關閉時才會存在。在 Docker 多階段建置裡如果沒有複製.git,這些值就會缺席,這是常見的「為什麼線上版本顯示 unknown」原因。- 把版本放進
slog的共用屬性,每一行日誌都會帶上版本,後面〈可觀測性:日誌、指標、追蹤〉會沿用這個做法。
你也可以用 go version -m ./order 直接查看任何 Go 執行檔裡嵌入的依賴清單,排查「線上那個執行檔到底用了哪版依賴」時非常方便。
第 5 步:加入依賴,理解最小版本選擇
接下來加入外部依賴。在程式碼中匯入一個外部套件後,執行:
go get example.com/some/lib@v1.4.0 # 加入或升級到指定版本
go mod tidy # 補上缺的、移除沒用到的依賴
go list -m all # 列出最終選中的所有模組版本
go mod why -m example.com/some/lib # 查為什麼需要這個模組go.mod 會多出 require 區塊,go.sum 則記錄每個模組版本內容的雜湊值。
go.sum 在保護什麼
go.sum 不是鎖定檔,而是完整性校驗檔。每次下載模組時,工具鏈會比對雜湊值,確認拿到的原始碼與第一次加入時完全相同;預設還會向公開的校驗資料庫(sumdb)確認這個版本的雜湊沒有被竄改過。因此 go.sum 必須提交到版本控制。它變長是正常的,因為它會記錄建置圖中可能用到的模組版本;不要手動編輯,交給 go mod tidy 維護即可。
最小版本選擇(MVS)
許多語言的套件管理器會在可接受範圍內選「最新」版本,而 Go 反其道而行:它選滿足所有需求的最小版本。演算法是這樣的:從主模組出發,走訪所有 require,對同一個模組,取所有需求中最高的那個版本,這就是最終使用的版本。它不會因為上游發布了新版本而自動升級。
圖:主模組需要 A 與 B,A 要求 C v1.2、B 要求 C v1.4,最終選 C v1.4;即使 C v1.7 已發布也不會被選到。
這個設計帶來兩個好處:
- 可重現:只要
go.mod不變,任何時間、任何機器建置出來的依賴版本都一樣,不需要另外的鎖定檔。 - 升級是明確的動作:依賴版本只在你執行
go get升級時才會改變,而且改變會清楚出現在go.mod的 diff 裡,方便審查。
代價是:你必須主動升級才拿得到安全修補。常見做法是在 CI 中定期執行 go list -m -u all 檢查可升級的版本,並用 govulncheck 掃描已知漏洞(它只會回報程式碼實際呼叫到的有漏洞函式,雜訊比單純比對版本少很多)。
語意化版本與 /v2
Go 要求模組遵守語意化版本,並把「主版本」編進匯入路徑:v0 與 v1 的匯入路徑相同,v2 以後必須在模組路徑尾端加上 /v2、/v3。也就是說 example.com/lib 與 example.com/lib/v2 在 Go 看來是兩個不同的模組,可以同時存在於同一個建置中。這讓大型系統能分批遷移主版本,而不是一次全部升級。發布自己的程式庫時,如果要做不相容的改動,就要依這個規則改模組路徑。
第 6 步:replace、vendor 與工具依賴
除了 require,go.mod 還有幾個指令在實務上很常用。
| 指令 | 用途 | 注意事項 |
|---|---|---|
replace | 把某模組換成本機路徑或另一個來源,例如暫時改用 fork 修 bug | 只對主模組生效,被別人依賴時會被忽略;修完要記得移除 |
exclude | 排除某個有問題的版本 | 很少用,通常升級到修正版更直接 |
retract | 由模組作者宣告某些已發布版本不應使用 | 寫在作者自己的 go.mod,使用者升級時會看到警告 |
tool | Go 1.24 起,把開發工具(程式碼產生器、檢查工具)記錄為依賴 | 以 go get -tool 模組路徑 加入,用 go tool 名稱 執行 |
工具依賴
過去專案常用一個 tools.go 檔加上建置標籤,來把程式碼產生器之類的工具鎖進 go.mod。Go 1.24 加入了 tool 指令,這個技巧就不需要了:
go get -tool golang.org/x/tools/cmd/stringer
go tool stringer -type=Status ./internal/order工具版本會跟著 go.mod 一起被鎖定,團隊成員和 CI 都會使用同一版,不會出現「我本機的產生器版本不同,產出的程式碼一直有 diff」的狀況。後面〈gRPC 與 Protocol Buffers〉產生程式碼時,也可以用同樣方式管理產生器。
vendor 目錄
go mod vendor 會把所有依賴的原始碼複製到 vendor/ 目錄,之後建置時直接使用它。適合的情境是:建置環境完全無法連網,或公司政策要求所有第三方程式碼都要進入版本控制審查。缺點是儲存庫會變大、升級依賴時 diff 很龐大。大多數團隊改用模組代理(GOPROXY)快取依賴即可,不一定需要 vendor。
提示:私有模組要設定
GOPRIVATE=example.com/shop/*,讓工具鏈對這些路徑跳過公開代理與校驗資料庫,直接從版本控制系統下載,避免把內部模組名稱送到外部服務查詢。
第 7 步:多個服務在同一個儲存庫
系列後半會有 order、payment、inventory、api-gateway 多個服務,它們都放在同一個儲存庫(monorepo),就要決定模組怎麼切。常見有兩種做法,本系列採用第一種:
圖:左邊整個儲存庫一個 go.mod;右邊每個服務各自一個 go.mod,本機開發時用 go.work 串起來。
做法一:整個儲存庫一個模組
根目錄一個 go.mod(example.com/shop),每個服務是 cmd/<服務>/ 加上 internal/<領域>/,也就是第 3 步的結構。
- 優點:最簡單。所有服務使用同一組依賴版本,共用程式碼直接匯入,不需要發版本號。一次
go test ./...跑完全部。 - 缺點:任何服務升級某個依賴,所有服務都跟著升級;依賴圖是所有服務的聯集,某個服務用到的大型函式庫會出現在每個服務的
go.sum中(雖然不會被編進沒用到它的執行檔)。
做法二:每個服務一個模組,搭配 go.work
每個服務目錄各自有 go.mod,可以獨立升級依賴、獨立打標籤發版。共用的程式庫也是獨立模組。本機開發時,用 Go 1.18 加入的工作區(workspace)把它們串起來:
go work init ./order ./inventory ./platform產生的 go.work 讓這些模組在本機互相引用時直接使用工作目錄中的原始碼,不需要先發布版本或寫 replace。
go 1.24
use (
./inventory
./order
./platform
)要注意的是,go.work 是「開發便利」,不是「發布設定」:CI 建置單一服務時,常見做法是設定 GOWORK=off,確保該服務的 go.mod 本身就能正確建置,否則可能出現「本機能編、CI 單獨建置卻失敗」的情況。許多團隊因此選擇不把 go.work 提交到版本控制。
怎麼選
| 情境 | 建議 |
|---|---|
| 服務數量少、同一個團隊維護、部署節奏一致 | 單一模組,最省事 |
| 服務由不同團隊維護,需要各自決定依賴升級節奏 | 多模組+go.work |
| 有要提供給外部使用的 SDK 或程式庫 | 該程式庫獨立成模組並正式打版本標籤 |
| 不確定 | 先從單一模組開始,用 internal/ 守住服務之間的邊界;之後拆模組只需要搬 go.mod,匯入路徑通常不用改 |
不論哪一種,服務之間「不直接匯入對方的業務程式碼」這條原則都不變。能共用的只有真正通用、穩定的平台程式碼(日誌設定、追蹤初始化、健康檢查),以及由 API 定義產生出來的客戶端程式碼。
常見陷阱
- 模組路徑與實際位置不一致:
go.mod寫github.com/a/b,程式碼卻放在github.com/a/c,別人go get時會得到「module declares its path as…」錯誤。改名時要同步更新go.mod與所有匯入。 - 把
go 1.xx當成可以隨便改的註解:它會改變語言語意(例如迴圈變數的作用域),升級後要跑完整測試,特別是有閉包抓迴圈變數或 goroutine 的地方。 - 手動編輯
go.sum、或不提交它:前者會讓校驗失敗,後者會讓別人的建置失去完整性保護。交給go mod tidy維護並提交。 replace指向本機路徑後忘記移除:在你的機器上能建置,CI 與同事的機器上找不到路徑。需要長期本機聯合開發時,改用不提交的go.work。utils、common套件無限膨脹:它們會變成依賴圖的中心,讓分層失效。依能力命名,或把程式碼留在使用它的地方。- 服務之間直接匯入對方的
internal以外套件:短期省事,長期讓兩個服務必須一起改、一起部署,失去拆服務的意義。 - Docker 建置時沒帶
.git:debug.ReadBuildInfo拿不到 commit,線上版本無法追溯。可以在建置時改用-ldflags "-X main.revision=..."補上,或在建置階段保留版本控制資訊。 - 一開始就照抄大型範本:一堆空目錄只會增加閱讀成本。結構應該跟著程式碼長,而不是先有結構再找東西塞。
重點整理
- 一個
go.mod定義一個模組;模組路徑是所有套件匯入路徑的前綴,go指令行決定最低版本與語言語意。 - 一個目錄就是一個套件;可見性只有大小寫兩級,套件之間不能循環匯入,所以目錄切分就是架構切分。
cmd/<名稱>/放各個執行檔的薄進入點,internal/放不對外的程式碼並由編譯器保證邊界,pkg/只是慣例、不是必需。- 用
runtime/debug.ReadBuildInfo讀取內嵌的版本與 commit,放進日誌的共用屬性,方便追溯線上版本。 - Go 以最小版本選擇決定依賴版本:取所有需求中的最高者,不自動追最新,建置可重現、升級是明確動作。
go.sum是完整性校驗而非鎖定檔,必須提交;主版本 v2 以上要寫進模組路徑。- 開發工具用 Go 1.24 的
tool指令鎖版本;私有模組設定GOPRIVATE。 - 多服務儲存庫可以選單一模組或多模組+
go.work;不確定時從單一模組開始,並堅守「服務之間不直接匯入業務程式碼」。
下一篇
骨架有了,但只要程式一開始呼叫資料庫或其他服務,就會遇到「失敗了該怎麼回報、怎麼判斷、怎麼不把內部細節洩漏出去」的問題。下一篇〈錯誤處理:包裝、哨兵、自訂型別〉就從 error 介面開始,替訂單服務建立一套一致的錯誤處理方式。