Go | 套件目錄結構命名規範

💬 簡介

在 Go 語言中，套件（Package）與目錄結構密切相關，良好的命名與規劃能讓專案更清晰、易於維護。
尤其在多人協作或專案逐漸擴大時，乾淨有序的結構可以大幅提升開發效率與可讀性。

本文將介紹套件與目錄的基本關係、命名規範，以及常見實務範例，協助您從一開始就打下良好基礎！

圖片來源：Gophers

🔍 Go 套件與目錄結構概覽

在 Go 中，每個目錄就是一個套件（Package），目錄名稱與套件名稱通常保持一致。
套件提供功能模組化的單位，支援跨檔案、跨目錄的引用（Import）。

• 目錄即套件：一個資料夾代表一個套件。
• 套件命名慣例：使用小寫字母，避免底線或駝峰，簡潔明瞭。
• 檔案命名慣例：檔案名稱描述內容，例如 user.go、order_service.go。

📝 好的結構設計，可以讓新成員快速理解專案內容，降低溝通成本。

📦 套件與目錄命名規範

📂 目錄結構設計原則

1. 功能劃分清晰：每個套件目錄只負責單一功能或模組，避免一個目錄下堆疊太多不相關的檔案。
2. 小而美：套件要小巧聚焦，一個套件只解決一類問題，不要過度膨脹。
3. 扁平化結構：除非必要，避免過深的目錄層級（通常建議 2–3 層內）。

• 推薦結構範例：

  1 2 3 4 5 6 7 8 9 10 11

  project/ ├── 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）檢查命名與結構是否符合規範。
• 程式碼審查規範：程式碼審查時嚴格檢查命名一致性與結構合理性。
• 定期培訓與溝通：定期團隊內分享與溝通命名與結構標準，確保共識。
• 範例程式碼模板：提供標準範例與骨架，讓新成員快速上手。

🚫 錯誤命名與改善建議

📝 命名應具備「可讀性」與「可預測性」，能讓陌生人一眼理解用途。

📉 失敗案例分析與改進

案例 1：過度龐大的單一套件目錄

• ❌問題：一個目錄塞入上百個檔案，涵蓋多種功能，導致維護困難且理解障礙。
• ✔️改善：拆分成多個子套件，依功能模組化，例如 user、user/profile、user/auth。

案例 2：命名不一致導致混淆

• ❌問題：部分檔案命名使用駝峰，部分使用底線，導致新成員摸不清規則。
• ✔️改善：統一命名規範並利用 CI 工具檢查，自動拒絕不合規命名的提交。

案例 3：internal 與 pkg 用法混淆

• ❌問題：所有共用程式碼都放在 internal，無法被外部項目引用，限制擴展。
• ✔️改善：清晰區分內部實作與對外共用，分別放置於 internal 和 pkg。

🛠 範例專案骨架實作

以電商系統為例，以下為推薦架構與基本實作：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

ecommerce/
├── cmd/
│   └── server/
│       └── main.go
├── internal/
│   ├── product/
│   │   └── service.go
│   ├── user/
│   └── order/
├── pkg/
│   └── logger/
├── configs/
│   └── config.yaml
├── api/
│   └── v1/
│       └── user.proto
├── scripts/
│   └── migrate.sh
├── go.mod
└── README.md

internal/product/service.go

1
2
3
4
5
6
7

package product

import "fmt"

func ListProducts() {
	fmt.Println("Listing all products...")
}

cmd/server/main.go

1
2
3
4
5
6
7

package main

import "ecommerce/internal/product"

func main() {
	product.ListProducts()
}

執行結果：

1

Listing all products...

📝 有條理的結構，讓大型專案也能輕鬆維護與擴展。

🎯 總結

在 Go 語言開發中，清晰一致的套件目錄結構與命名規範至關重要。
良好的結構不僅讓自己維護方便，也能讓新加入的團隊成員快速理解專案。

記得遵循以下三大原則：

• ✅ 小而美（Small and Focused）
• ✅ 清晰一致（Clear and Consistent）
• ✅ 可讀可維護（Readable and Maintainable）

建立穩固結構，讓專案在成長時不至於混亂，是每位開發者都應具備的基礎素養。

最後建議回顧一下 Go | 菜鳥教學 目錄，了解其章節內容。

註：以上參考了
Go