Like Share Discussion Bookmark Smile

J.J. Huang   2025-06-03   Getting Started Golang 07.套件   瀏覽次數:次   DMCA.com Protection Status

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

💬 簡介

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

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

圖片來源:Gophers


🔍 Go 套件與目錄結構概覽

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

  • 目錄即套件:一個資料夾代表一個套件。
  • 套件命名慣例:使用小寫字母,避免底線或駝峰,簡潔明瞭。
  • 檔案命名慣例:檔案名稱描述內容,例如 user.goorder_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 語言內建的封裝機制,限制只在本模組內引用。


🏷 命名規範細節

  • 套件名
    • 小寫字母,不使用底線或大寫。
    • 名稱要簡短但具描述性,例如 userorderpayment
  • 檔案名
    • 小寫加底線,根據職責命名,如 user_service.goorder_repository.go
  • 函式與變數命名
    • 駝峰式命名(CamelCase),公共函式首字母大寫,內部使用首字母小寫。
  • 常見保留目錄
    • cmd/:放置主程式執行入口。
    • internal/:專案內部使用的程式碼。
    • pkg/:可被外部專案引用的共用資源。
    • api/:定義 API 資料結構或介面。
    • configs/:設定檔。
    • scripts/:建置與部署腳本。

📝 雖然 Go 官方未強制結構,但這些模式已廣為社群採納。


🛠 命名一致性維護與團隊實踐

維護命名規範的一致性,對團隊合作極為重要:

  • 制定命名規範文件:明確記錄專案命名慣例與目錄結構指引。
  • 使用自動化工具:利用 lint 工具(如 golangci-lint)檢查命名與結構是否符合規範。
  • 程式碼審查規範:程式碼審查時嚴格檢查命名一致性與結構合理性。
  • 定期培訓與溝通:定期團隊內分享與溝通命名與結構標準,確保共識。
  • 範例程式碼模板:提供標準範例與骨架,讓新成員快速上手。

🚫 錯誤命名與改善建議

錯誤案例 問題說明 建議修改
utils 意義模糊,不易維護 依實際功能命名,如 stringutil
commonFunctions.go 檔名太籠統 拆分成具體功能,如 math_util.godate_helper.go
MyPackage 不符合小寫命名慣例 修改為 mypackage

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


📉 失敗案例分析與改進

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

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

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

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

案例 3:internalpkg 用法混淆

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

🛠 範例專案骨架實作

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

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