This resume is also available in English.

一、Go 地基第 1 / 4 篇 · 全部目錄

專欄 › 一、Go 地基 › 第 1 篇

工程結構與 Go Modules

Go Project Layout and Go Modules

從 go mod init 開始,講清楚模組、套件與目錄的關係,cmd 與 internal 該怎麼放,依賴怎麼選版本,以及多個服務共用一個儲存庫時該用單一模組還是 go.work。

  • Go
  • Modules
  • Project Layout
這篇的步驟
  1. 這篇要解決什麼
  2. 第 1 步:建立模組,看懂 go.mod
  3. 第 2 步:套件就是目錄
  4. 第 3 步:用 cmd 與 internal 排出骨架
  5. 第 4 步:讓進入點知道自己是哪個版本
  6. 第 5 步:加入依賴,理解最小版本選擇
  7. 第 6 步:replace、vendor 與工具依賴
  8. 第 7 步:多個服務在同一個儲存庫
  9. 常見陷阱
  10. 重點整理
  11. 下一篇

這是「用 Go 打造微服務」系列的第一篇。整個系列共 34 篇,分成八個階段,以一間線上商店的訂單服務為主線,照順序讀,每篇都接著上一篇:

  1. 一、Go 地基(第 1~4 篇):工程結構、錯誤處理、並發、context,先把語言基本功打穩。
  2. 二、寫一個服務(第 5~8 篇):HTTP 中介層、分層與依賴注入、資料庫交易、測試,寫出一個結構清楚、測得了的單體服務。
  3. 三、拆成微服務(第 9~12 篇):什麼時候該拆,把它拆成 api-gateway、order、payment、inventory,處理 gRPC、API Gateway、服務發現。
  4. 四、可靠性(第 13~16 篇):逾時、重試、熔斷、冪等、訊息佇列與分散式交易。
  5. 五、上線與維運(第 17~20 篇):可觀測性、優雅關閉、單一服務的容器與 Kubernetes 部署、效能調校。
  6. 六、實戰部署(第 21~23 篇):用 Docker Compose 與 Kubernetes 部署整套系統,再回頭看系統怎麼從十萬、百萬到千萬級一步步演進。
  7. 七、實戰踩坑(第 24~26 篇):併發、支付與金額處理的常見問題。
  8. 八、安全與 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 排出骨架

有了「套件就是目錄」的概念,就可以排出服務的骨架。下面是一個常見、但刻意保持精簡的結構:

shop/ go.mod:example.com/shop cmd/ 每個服務一個進入點 internal/ 本模組才能匯入 api/proto/ 服務間 API 定義 deploy/ compose、k8s order/main.go payment/ inventory/ api-gateway/ order/ handler.go 處理器 service.go 業務邏輯 repository.go 資料存取 payment/ inventory/ main 只負責組裝, 匯入 internal/order 一開始只需要 cmd/order 與 internal/order,其他目錄隨系列逐步長出

圖: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 v1.0 B v2.3 需要 ≥ v1.2 需要 ≥ v1.4 C v1.2 C v1.4 C v1.7 已發布 選中:需求中最高的 C v1.4 沒有人要求 v1.7,所以不會自動升級

圖:主模組需要 A 與 B,A 要求 C v1.2、B 要求 C v1.4,最終選 C v1.4;即使 C v1.7 已發布也不會被選到。

這個設計帶來兩個好處:

  1. 可重現:只要 go.mod 不變,任何時間、任何機器建置出來的依賴版本都一樣,不需要另外的鎖定檔。
  2. 升級是明確的動作:依賴版本只在你執行 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,使用者升級時會看到警告
toolGo 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.work shop/go.mod(一份) cmd/order internal/order cmd/inventory internal/inventory cmd/payment internal/payment 同一組依賴版本、一次 go test ./... go.work(本機開發用) order/go.mod 自己的依賴版本 inventory/go.mod 自己的依賴版本 platform/go.mod 可獨立打版本 CI 建置單一服務時設 GOWORK=off

圖:左邊整個儲存庫一個 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 介面開始,替訂單服務建立一套一致的錯誤處理方式。