從 Java 轉 Go 的人,第一次開啟 kubernetes/kubernetes 的原始碼,大多會做同一個動作:找 controller 在哪、service 在哪、DAO 在哪。畢竟在 Spring 的世界裡,程式碼就住在這三層裡。但 ls 的結果是一套陌生的詞彙:cmd、pkg、staging、api、vendor……一個熟悉的名字都沒有。
更添亂的是,搜尋引擎會把我們帶到一份 “Standard Go Project Layout”,看起來這就是官方答案;而 Go 的技術負責人 Russ Cox 專門去那個倉庫開過一個 issue,標題就叫 “this is not a standard Go project layout”1。連「標準佈局」本身都是一場誤會,那 Go 大工程的程式碼到底按什麼組織?
我們把問題拆開:
- cmd/、pkg/、internal/ 這三個隨處可見的目錄,各是什麼來歷?誰定的?
- 為什麼 etcd 頂層連 cmd/ 和 internal/ 都沒有?
- k8s 裡明明有個 pkg/controller——它是 Java 意義上的 controller 嗎?那 service、DAO 的對應物在哪?
- 有沒有 Go 專案真的按 handler/service/db 分層?
- prometheus 為什麼又是另一種答案?
本文順著這五個問題往下走,樣本是四個真實的大工程:kubernetes、multica(一個用 Go 寫的 AI agent 協作平臺)、etcd、prometheus。文中所有目錄名、檔名和行號,都來自 2026-10-31 當天各倉庫的主分支。
一、cmd、pkg、internal:三個目錄,三種來歷
先看 k8s 的頂層:
$ ls kubernetes/api/ build/ cluster/ cmd/ docs/ hack/ pkg/ plugin/staging/ test/ third_party/ vendor/ …(staging 順帶交代一句,後面不再展開:它是「待拆分倉庫的孵化區」,staging/src/k8s.io/ 下的程式碼是唯一權威副本,由 publishing-bot 單向釋出成 client-go、apimachinery 等獨立倉庫2。)
cmd/ 是多二進位制的收納處。 cmd/ 下每個子目錄編譯出一個二進位制,目錄名就是二進位制名。k8s 的 cmd/ 下有 kube-apiserver、kube-controller-manager、kube-scheduler、kubelet、kubectl、kubeadm 等元件入口,外加十幾個程式碼生成工具。這些入口檔案統一的特點是非常薄:cmd/kube-apiserver/apiserver.go 的 main 全部有效程式碼只有三行(NewAPIServerCommand → cli.Run → os.Exit),cmd/kubelet/kubelet.go 只有 1488 位元組,真正的裝配都在同目錄的 app/ 子包裡。Go 官方文件對伺服器專案的建議正是這個分工:命令放 cmd/,邏輯放 internal/3。
internal/ 是唯一有編譯器背書的目錄語義。 它不是慣例,是語言特性。Go 1.4 的釋出說明寫得很清楚:go 命令引入了一種機制,internal 包「不可以被其所在原始碼子樹之外的包匯入」4。現行工具鏈文件的表述更精確:internal 目錄裡(及其之下)的程式碼,只有與 internal 共享同一上級 import path 的程式碼才能匯入5。大專案用它把「公開 API」和「私有實現」隔開——比如 multica 的 server module 把全部 49 個業務包都放進了 internal/。
pkg/ 是爭議最大的一個。 它的流行來自那份 “Standard Go Project Layout”:把「可被外部引用的庫程式碼」放進 pkg/6。但這份「標準」的 README 自己宣告它不是官方標準,Russ Cox 在 issue #117 裡說得更直白——Go 生態裡絕大多數包並不放在 pkg/ 子目錄裡,他認可的最小布局只有三條:根目錄放 LICENSE、go.mod、Go 程式碼,「That’s it. That’s the “standard”.」1。官方的組織哲學是按功能內聚切包,包名說明「提供什麼」而不是「裝了什麼」7,util、common、misc 這類名字被官方部落格點名反對8。事實上,prometheus 和 etcd 的頂層都沒有 pkg/;multica 保留了 pkg/,但裡面放的是「跨程序共享的契約」(sqlc 生成的 DAO、daemon 與 server 之間的 WebSocket 協議),語義已經和 project-layout 的本意不同了。
| 倉庫 | 頂層目錄風格 | 二進位制入口 | 「私有實現」的圍欄 |
|---|---|---|---|
| kubernetes | cmd + pkg + staging,單 module | cmd/<元件>/,main 極薄 | 公開面走 staging 釋出;pkg/ 不對外 |
| multica(server/) | cmd + internal + pkg,單 module | cmd/server、cmd/multica | internal/ 圈住 49 個業務包 |
| prometheus | 21 個功能包平鋪,沒有 pkg/ | cmd/prometheus、cmd/promtool | internal/ 很小,近乎無圍欄 |
| etcd | 頂層目錄 = module(go.work × 14) | module 根的 main.go | go.mod 依賴圖 + 個別 internal/ |
cmd/ 和 internal/ 看似標配,其實各自回答一個具體問題:有幾個二進位制要放?哪些包不許外人碰?
cmd/ 和 internal/ 看起來是大專案的標配。但開啟 etcd,這兩個目錄都不在——它們解決的問題消失了嗎?
二、etcd:module 邊界取代了 cmd/ 和 internal/
先看現象,etcd 的頂層:
$ ls etcd/api/ cache/ client/ contrib/ etcdctl/ etcdutl/ pkg/server/ tests/ tools/ go.work …沒有 cmd/,頂層也沒有 internal/。原因藏在根目錄的 go.work 裡:這個倉庫不是一個 Go module,而是 14 個 module 組成的 workspace9——server/、client/v3/、api/、etcdctl/、etcdutl/、pkg/、tests/……每個頂層目錄自帶 go.mod,獨立版本、獨立釋出。
cmd/ 為什麼消失了。 回想 cmd/ 的本質:它是「一個倉庫要產出多個二進位制」時的集中收納。etcd 把每個二進位制拆成了獨立 module——server module 產 etcd,etcdctl module 產 etcdctl,etcdutl module 產 etcdutl。一個 module 只產出一個二進位制時,main 包放在 module 根就是唯一合理的位置,cmd/ 反而成了多餘的一層巢狀。server/main.go 確實就在那裡,而且同樣薄:整個檔案只是 etcdmain.Main(os.Args) 的殼,檔案註釋自稱 “simple wrapper of the real etcd entrypoint”10。k8s 恰好是反面的例子:單一大 module 要產出幾十個二進位制,才需要 cmd/ 來聚類。
internal/ 的消失要分兩層說。 在 module 之間,圍欄換了角色:go.mod 的依賴圖本身就是可見性邊界。client/v3 的 go.mod 只 require api/v3、client/pkg/v3 和 grpc 等少數依賴,根本不 require server/v3——外部專案(比如 k8s 的 apiserver)import client/v3 時,server 的 raft、bbolt 這些重依賴連進入依賴圖的機會都沒有。反過來,etcdutl 是快照恢復工具,它的 go.mod 老老實實 require 了 server/v3、bbolt 和 raft。誰輕誰重,go.mod 裡寫得明明白白。
但在 module 內部,internal/ 並沒有被消滅:client/v3/internal/ 下面就躺著 endpoint/ 和 resolver/ 兩個包,是 gRPC 端點解析的私有實現11。module 邊界替代的只是 internal/ 在 module 之間的角色;module 之內想做細粒度隱藏,internal/ 依然是 Go 給的唯一工具。至於 server module 完全不用 internal/,更像歷史慣例而非設計——etcdutl 既然能 require 整個 server/v3,server/etcdserver、server/storage 這些包在技術上就是「事實上的公開 API」。
目錄約定搞清楚了。回到最初的問題:controller 在哪?k8s 裡明明有個 pkg/controller/——但開啟它,會發現這個詞被重新定義了。
三、k8s 的 controller:一個被重新定義的詞
抱著找「接 HTTP 請求的那個 controller」的預期,開啟 pkg/controller/deployment/deployment_controller.go,看到的 DeploymentController struct 裡沒有路由、沒有 HTTP,最顯眼的欄位是一個佇列:queue workqueue.TypedRateLimitingInterface[string]12。
原因是在 k8s 的語境裡,controller 不是 MVC 的 controller,而是控制迴圈(control loop)。kube-controller-manager 的啟動命令對自己的描述原文就是定義:“a controller is a control loop that watches the shared state of the cluster through the apiserver and makes changes attempting to move the current state towards the desired state”13。pkg/controller/ 下約 50 個目錄——deployment、replicaset、statefulset、cronjob、namespace、garbagecollector……——全是這樣的迴圈,由 cmd/kube-controller-manager 統一註冊、統一啟動。註冊入口是 app/controller_descriptor.go 的 NewControllerDescriptors();讀舊資料時留意,它以前叫 NewControllerInitializers,後來重構成了現在的名字14。
deployment controller 是這種迴圈的教科書樣例,結構分三段(圖 3)。它給 Deployment、ReplicaSet、Pod 三個 informer 註冊事件回撥,回撥裡不寫任何業務邏輯,只做一件事:把物件的 key 放進佇列。另一邊,若干 worker 從佇列裡取 key,調 syncDeployment:從 informer 的本地快取讀物件、對比期望狀態與實際狀態、決定滾動更新還是擴縮容;失敗就把 key 限流重入隊,最多重試 15 次12。informer(監聽 + 快取)、workqueue(去重 + 限流重試)、sync loop(糾偏),三段拼出一個完整的 reconcile loop。
那 HTTP 請求路徑上有什麼?apiserver 收到「PUT 一個 Deployment」時,走的是認證 → 鑑權 → 准入 → 儲存,全程無狀態、沒有「業務邏輯」可言——真正的業務(該建幾個 Pod、怎麼滾動)發生在上面那個非同步迴圈裡。請求路徑上唯一像 Java 分層裡某個角色的,是 pkg/registry:按 API group 和資源組織的 REST storage 層,core 組下 pod、service、node、namespace、configmap……每種資源一個目錄,把 CRUD 收口到 apiserver 的 generic registry,最終落到唯一的持久化後端 etcd15。(嚴謹起見標註一下:各資源目錄內部的 storage/storage.go 檔名是按慣例的推斷,本次只核實到目錄層級。)
對齊一下兩邊的詞彙:Java 的 controller ≈ apiserver 的 REST / registry 層(接請求,但不做業務);Java 的 service ≈ 不存在——它的職責整體轉移給了 pkg/controller 裡的非同步控制迴圈;Java 的 DAO ≈ pkg/registry + etcd3 store。
難道 Go 專案都沒有 service 層?那倒未必——換一個業務系統看看。
四、multica:長回三層的 Go 專案
multica 是用 Go 寫的 AI agent 協作平臺,它的 server module 是教科書式的 cmd + internal + pkg。開啟 internal/,兩個包的名字毫不掩飾:handler、service。
以「評論裡 @ 了一個 agent,把它叫起來幹活」為例,整條呼叫鏈可以逐行對上(圖 4):
- handler 層:internal/handler/comment.go 的
CreateComment(:1629)接請求;computeCommentAgentTriggers(:2636)算出這條評論該叫醒誰,@提及由 util.ParseMentions 解析16。 - service 層:handler 調
TaskService.EnqueueTaskForMention,最終落到 internal/service/task.go 的enqueueMentionTaskWithCommentPlan(:1464)——事務、去重(哨兵錯誤ErrDuplicatePendingTask)、入隊都在這裡17。 - DAO 層:領取任務時
claimTask(:3612)呼叫qtx.ClaimAgentTask。而ClaimAgentTask不是手寫的 Go 函式——它是 sqlc 從 pkg/db/queries/agent.sql:734 那段 SQL(-- name: ClaimAgentTask :one)生成的型別安全方法18。queries/ 下 67 個 .sql 檔案的角色幾乎就是 MyBatis 的 mapper XML,generated/ 目錄是生成的 DAO。
對照 Spring 官方文件的定義——@Controller、@Service、@Repository 分別是表現層、業務層、持久層的 @Component 特化19——multica 的 handler / service / db 幾乎一一對應。
和 Java 嚴格三層相比,multica 有兩處明顯的「Go 式鬆動」。一是邊界:寫路徑和業務編排走 service,簡單的讀路徑 handler 直接持有 h.Queries 查 db,不經過 service——在 Java 的嚴格分層裡,這是會被 code review 攔下來的寫法。二是裝配:沒有框架掃描,也沒有依賴注入容器,cmd/server/main.go 手工 new 出一切(db.New(pool),再逐個傳給 service);路由集中在 130KB 的 router.go 裡註冊,那張路由表的角色約等於一整份 @RequestMapping 清單。
為什麼這個專案「敢」分層、也需要分層?因為它是 CRUD 業務系統:同步請求路徑上真的有編排要做——解析提及、計算該觸發誰、去重、入隊、保證同一 (issue, agent) 的任務序列。業務形態決定了分層的收益。
那是不是所有 Go 專案都該抄這三層?prometheus 給出了否定的答案。
五、prometheus:沒有 service 層生態位的系統
prometheus 的頂層是另一種風格:21 個目錄全部平鋪——scrape/、rules/、promql/、storage/、tsdb/、web/、discovery/、notifier/……沒有 pkg/,cmd/ 下也只有 prometheus 和 promtool 兩個入口。
它的 HTTP 層看起來像 controller:web/api/v1/api.go 一個 97KB 的檔案裝下全部 v1 端點,type API struct + NewAPI(...) + Register(router) 逐條註冊路由20。但往下看一層就斷了:沒有 service 層。NewAPI 的 40 多個引數直接是各子系統的本尊——promql.QueryEngine、storage.Queryable、scrape 和 rules 的 retriever——handler 裡直接 api.QueryEngine.NewInstantQuery(...) 然後執行,web 層只剩下引數解析、錯誤碼對映、響應序列化。
業務邏輯住在各子系統自己的目錄裡,而且是縱切自治的。以 scrape/ 為例:manager.go 管配置過載和 target 集合,scrape.go(81KB)是抓取迴圈,target.go 是領域物件,metrics.go 是這個子系統自己的監控指標——一個目錄就是一個自包含的小系統,對外只暴露一個 Manager,等著 cmd/prometheus/main.go 那個 93KB 的裝配檔案把它接進全域性21。rules/、discovery/(下掛約 30 個服務發現來源)、notifier/ 都是同樣的形態。storage/ 與 tsdb/ 的分離則是另一個標本:storage/interface.go(31KB)定義 Queryable / Appendable 介面,tsdb/ 是內建實現,web、promql、rules 只依賴介面,實現由 main 在裝配時注入。
prometheus 為什麼沒有 service 層的生態位?因為它的「業務」本來就不是「一次請求編排多個領域物件」,而是各子系統永不停歇的主迴圈:抓取、評估規則、發告警。HTTP API 只是探視這些迴圈的視窗,視窗後面沒有等待編排的東西,service 層自然無從談起。
這種切法在 Go 社群有理論表述。Ben Johnson 的 Standard Package Layout 主張領域型別放根包、子包按依賴分組(postgres、http 各做一個介面卡),並且明確要求根包不依賴應用內任何其他包22;Clean Architecture 在 Go 裡的實踐(ports / adapters / application / domain)同樣把分層規則定義成依賴方向:外層可以引用內層,反過來不行23。也就是說,Go 社群不是不分層,而是把分層的軸從「技術職能」(controller/service/dao 橫切)換成了「依賴方向與領域」(縱切)。
三個專案,三種答案。回頭看開頭的五個問題,可以收攏了。
六、寫在最後
回到開頭那個 ls 的結果。現在再看 k8s 的頂層目錄,cmd、pkg、staging 不再是陌生的詞彙;再遇到一個新的 Go 倉庫,找程式碼的姿勢可以總結成三步:
- 先看這個倉庫產出什麼:cmd/ 下有幾個二進位制?或者像 etcd 那樣,go.work 串了幾個 module、哪個 module 的根上有 main.go?
- 再看邊界在哪:internal/ 圈出了私有實現;go.mod 的 require 圈出了 module 之間的真實依賴。
- 最後按業務形態猜邏輯的位置:CRUD 業務系統,去請求路徑上找(handler/service);宣告式基礎設施,去控制迴圈裡找(reconcile loop);單一職責系統,去各子系統的主迴圈裡找,HTTP 層只是視窗。
五個問題的答案收攏如下:
- cmd/ 是「多二進位制」的收納慣例,internal/ 是 Go 1.4 起編譯器強制的可見性圍欄,pkg/ 是流行但有爭議的社群慣例——所謂「標準 Go 佈局」並不標準。
- etcd 沒有 cmd/,因為「一個 module 一個二進位制」讓集中收納失去了意義;internal/ 在 module 之間被 go.mod 依賴圖取代,在 module 內部依然在場(client/v3/internal 為證)。
- k8s 的 controller 是控制迴圈,不是 MVC controller;service 層不存在,職責轉移給了非同步的 reconcile;DAO 的對應物是 pkg/registry + etcd3 store。
- multica 真實存在 handler / service / db 三層(sqlc 讓 SQL 即 DAO),因為它是 CRUD 業務系統;但邊界比 Java 松,讀路徑 handler 直查 db。
- prometheus 沒有 service 層的生態位:子系統縱切自治,web 層直調功能包,裝配集中在 main.go。
一句話總結:Go 專案的目錄結構不是語言規定的,而是業務形態(同步 CRUD 還是非同步控制迴圈)和釋出形態(單 module 還是多 module)決定的;service 和 controller 的概念都在,只是住的樓層不一樣了。
參考資料
參考資料
-
this is not a standard Go project layout · Issue #117github.com ↗rsc:"the vast majority of packages in the Go ecosystem do not put the importable packages in a pkg subdirectory"https://github.com/golang-standards/project-layout/issues/117 ↩ ↩2
-
kubernetes/staging/README.mdgithub.com ↗"The code in the staging/ directory is authoritative",由 publishing-bot 單向釋出到 k8s.io 各倉庫https://github.com/kubernetes/kubernetes/blob/master/staging/README.md ↩
-
Organizing a Go modulego.dev ↗官方對伺服器專案的建議:命令放 cmd/,邏輯放 internal/;示例裡沒有 pkg/https://go.dev/doc/modules/layout ↩
-
Go 1.4 Release Notes — Internal packagesgo.dev ↗internal 包機制的引入:"may not be imported by packages outside the source subtree in which they reside"https://go.dev/doc/go1.4 ↩
-
cmd/go 文件 — Internal packagespkg.go.dev ↗"Code in or below a directory named 'internal' is importable only by code that shares the same import path above the internal directory."https://pkg.go.dev/cmd/go#hdr-Internal_packages ↩
-
Standard Go Project Layoutgithub.com ↗README 自述:"This is NOT an official standard defined by the core Go dev team"https://github.com/golang-standards/project-layout ↩
-
Organizing Go codego.dev ↗包名為內容提供上下文;最小化匯出介面("If in doubt, leave it out!")https://go.dev/blog/organizing-go-code ↩
-
Package namesgo.dev ↗"Avoid meaningless package names. Packages named util, common, or misc …"https://go.dev/blog/package-names ↩
-
etcd/go.workgithub.com ↗2026-10-31 的 main 分支:14 個 use 項,server、client/v3、api、etcdctl、etcdutl 等各為獨立 modulehttps://github.com/etcd-io/etcd/blob/main/go.work ↩
-
etcd/server/main.gogithub.com ↗檔案註釋自稱 "simple wrapper of the real etcd entrypoint",只調 etcdmain.Main(os.Args)https://github.com/etcd-io/etcd/blob/main/server/main.go ↩
-
etcd/client/v3/internalgithub.com ↗endpoint/ 與 resolver/ 兩個包:module 內部仍在使用 internal/ 的實證https://github.com/etcd-io/etcd/tree/main/client/v3/internal ↩
-
pkg/controller/deployment/deployment_controller.gogithub.com ↗informer 回撥只做 dc.queue.Add(key);worker 出隊調 syncDeployment;失敗 AddRateLimited,maxRetries=15https://github.com/kubernetes/kubernetes/blob/master/pkg/controller/deployment/deployment_controller.go ↩ ↩2
-
cmd/kube-controller-manager/app/controllermanager.gogithub.com ↗cobra Long 描述:"a controller is a control loop that watches the shared state of the cluster …"https://github.com/kubernetes/kubernetes/blob/master/cmd/kube-controller-manager/app/controllermanager.go ↩
-
cmd/kube-controller-manager/app/controller_descriptor.gogithub.com ↗NewControllerDescriptors() 註冊全部內建控制器;舊名 NewControllerInitializers 已重構https://github.com/kubernetes/kubernetes/blob/master/cmd/kube-controller-manager/app/controller_descriptor.go ↩
-
pkg/registrygithub.com ↗按 API group / 資源組織的 REST storage 層,core 下 pod、service、node、namespace 等各一個目錄https://github.com/kubernetes/kubernetes/tree/master/pkg/registry ↩
-
multica/server/internal/handler/comment.gogithub.com ↗CreateComment :1629;computeCommentAgentTriggers :2636(行號為 2026-10-31 的 main)https://github.com/multica-ai/multica/blob/main/server/internal/handler/comment.go ↩
-
multica/server/internal/service/task.gogithub.com ↗enqueueMentionTaskWithCommentPlan :1464;claimTask :3612;ErrDuplicatePendingTask :755https://github.com/multica-ai/multica/blob/main/server/internal/service/task.go ↩
-
multica/server/pkg/db/queries/agent.sqlgithub.com ↗:734
-- name: ClaimAgentTask :one,sqlc 據此生成型別安全的 Go 方法https://github.com/multica-ai/multica/blob/main/server/pkg/db/queries/agent.sql ↩ -
Classpath Scanning and Managed Components — Stereotype Annotationsdocs.spring.io ↗"@Repository, @Service, and @Controller are specializations of @Component … (persistence, service, and presentation layers)"https://docs.spring.io/spring-framework/reference/core/beans/classpath-scanning.html ↩
-
prometheus/web/api/v1/api.gogithub.com ↗97KB 裝下全部 v1 端點;NewAPI 的 40+ 個引數直接是 promql.QueryEngine、storage.Queryable 等本尊https://github.com/prometheus/prometheus/blob/main/web/api/v1/api.go ↩
-
prometheus/cmd/prometheus/main.gogithub.com ↗93KB 的手工裝配檔案:各子系統 Manager 在這裡接進全域性https://github.com/prometheus/prometheus/blob/main/cmd/prometheus/main.go ↩
-
Standard Package Layoutgobeyond.dev ↗領域型別放根包:"The root package should not depend on any other package in your application!"https://www.gobeyond.dev/standard-package-layout/ ↩
-
How to implement Clean Architecture in Go (Golang)threedots.tech ↗ports / adapters / application / domain 四層,分層規則是依賴方向https://threedots.tech/post/introducing-clean-architecture/ ↩