Go | 套件目錄結構命名規範
💬 簡介
在 Go 語言中,套件(Package)與目錄結構密切相關,良好的命名與規劃能讓專案更清晰、易於維護。
尤其在多人協作或專案逐漸擴大時,乾淨有序的結構可以大幅提升開發效率與可讀性。
本文將介紹套件與目錄的基本關係、命名規範,以及常見實務範例,協助您從一開始就打下良好基礎!
圖片來源:Gophers
🔍 Go 套件與目錄結構概覽
在 Go 中,每個目錄就是一個套件(Package),目錄名稱與套件名稱通常保持一致。
套件提供功能模組化的單位,支援跨檔案、跨目錄的引用(Import)。
- 目錄即套件:一個資料夾代表一個套件。
- 套件命名慣例:使用小寫字母,避免底線或駝峰,簡潔明瞭。
- 檔案命名慣例:檔案名稱描述內容,例如
user.go
、order_service.go
。
📝 好的結構設計,可以讓新成員快速理解專案內容,降低溝通成本。
📦 套件與目錄命名規範
📂 目錄結構設計原則
- 功能劃分清晰:每個套件目錄只負責單一功能或模組,避免一個目錄下堆疊太多不相關的檔案。
- 小而美:套件要小巧聚焦,一個套件只解決一類問題,不要過度膨脹。
- 扁平化結構:除非必要,避免過深的目錄層級(通常建議 2–3 層內)。
- 推薦結構範例:
1
2
3
4
5
6
7
8
9
10
11project/
├── cmd/ # 主程式入口
│ └── app/
│ └── main.go
├── internal/ # 專案內部使用
│ ├── user/
│ └── order/
├── pkg/ # 可供外部引用
│ └── logger/
├── go.mod
└── README.md
📝
internal
是 Go 語言內建的封裝機制,限制只在本模組內引用。
🏷 命名規範細節
- 套件名
- 小寫字母,不使用底線或大寫。
- 名稱要簡短但具描述性,例如
user
、order
、payment
。
- 檔案名
- 小寫加底線,根據職責命名,如
user_service.go
、order_repository.go
。
- 小寫加底線,根據職責命名,如
- 函式與變數命名
- 駝峰式命名(CamelCase),公共函式首字母大寫,內部使用首字母小寫。
- 常見保留目錄
cmd/
:放置主程式執行入口。internal/
:專案內部使用的程式碼。pkg/
:可被外部專案引用的共用資源。api/
:定義 API 資料結構或介面。configs/
:設定檔。scripts/
:建置與部署腳本。
📝 雖然 Go 官方未強制結構,但這些模式已廣為社群採納。
🛠 命名一致性維護與團隊實踐
維護命名規範的一致性,對團隊合作極為重要:
- 制定命名規範文件:明確記錄專案命名慣例與目錄結構指引。
- 使用自動化工具:利用 lint 工具(如
golangci-lint
)檢查命名與結構是否符合規範。 - 程式碼審查規範:程式碼審查時嚴格檢查命名一致性與結構合理性。
- 定期培訓與溝通:定期團隊內分享與溝通命名與結構標準,確保共識。
- 範例程式碼模板:提供標準範例與骨架,讓新成員快速上手。
🚫 錯誤命名與改善建議
錯誤案例 | 問題說明 | 建議修改 |
---|---|---|
utils |
意義模糊,不易維護 | 依實際功能命名,如 stringutil |
commonFunctions.go |
檔名太籠統 | 拆分成具體功能,如 math_util.go 、date_helper.go |
MyPackage |
不符合小寫命名慣例 | 修改為 mypackage |
📝 命名應具備「可讀性」與「可預測性」,能讓陌生人一眼理解用途。
📉 失敗案例分析與改進
案例 1:過度龐大的單一套件目錄
- ❌問題:一個目錄塞入上百個檔案,涵蓋多種功能,導致維護困難且理解障礙。
- ✔️改善:拆分成多個子套件,依功能模組化,例如
user
、user/profile
、user/auth
。
案例 2:命名不一致導致混淆
- ❌問題:部分檔案命名使用駝峰,部分使用底線,導致新成員摸不清規則。
- ✔️改善:統一命名規範並利用 CI 工具檢查,自動拒絕不合規命名的提交。
案例 3:internal
與 pkg
用法混淆
- ❌問題:所有共用程式碼都放在
internal
,無法被外部項目引用,限制擴展。 - ✔️改善:清晰區分內部實作與對外共用,分別放置於
internal
和pkg。
🛠 範例專案骨架實作
以電商系統為例,以下為推薦架構與基本實作:
1 | ecommerce/ |
internal/product/service.go
1 | package product |
cmd/server/main.go
1 | package main |
執行結果:
1 | Listing all products... |
📝 有條理的結構,讓大型專案也能輕鬆維護與擴展。
🎯 總結
在 Go 語言開發中,清晰一致的套件目錄結構與命名規範
至關重要。
良好的結構不僅讓自己維護方便,也能讓新加入的團隊成員快速理解專案。
記得遵循以下三大原則:
- ✅ 小而美(Small and Focused)
- ✅ 清晰一致(Clear and Consistent)
- ✅ 可讀可維護(Readable and Maintainable)
建立穩固結構,讓專案在成長時不至於混亂,是每位開發者都應具備的基礎素養。
最後建議回顧一下 Go | 菜鳥教學 目錄,了解其章節內容。
註:以上參考了
Go