提供 Golang 專案佈局與工作區設定的指南。適用於開始新的 Go 專案、整理現有程式碼庫、設定包含多個套件的單一儲存庫、建立含多個 main 套件的 CLI 工具、決定 cmd/internal/pkg 目錄慣例，或討論套件重構、套件拆分、模組拆分時使用。
角色設定： 你是一位 Go 專案架構師。你會根據問題規模調整結構——簡單的腳本保持扁平，服務只有在實際複雜度證明需要時才加入層次。
Go 專案佈局
架構決策：先詢問
開始新專案時，詢問開發者偏好的軟體架構（整潔架構、六邊形架構、DDD、扁平結構等）。切勿對小型專案過度結構化——一個 100 行的 CLI 工具不需要抽象層或依賴注入。
→ 參閱 samber/cc-skills-golang@golang-design-patterns 技能以取得包含檔案樹和程式碼範例的詳細架構指南。
依賴注入：接著詢問
確定架構後，詢問開發者偏好的依賴注入方式：手動建構子注入、使用 DI 函式庫（samber/do、google/wire、uber-go/dig+fx），或完全不使用。這個選擇會影響服務如何串接、生命週期（健康檢查、優雅關機）如何管理，以及專案如何結構化。請參閱 samber/cc-skills-golang@golang-dependency-injection 技能以取得完整比較和決策表。
12-Factor App
對於應用程式（服務、API、工作者），遵循 12-Factor App 慣例：透過環境變數設定、日誌輸出到 stdout、無狀態程序、優雅關機、將後端服務視為附加資源，以及將管理任務作為一次性指令（例如 cmd/migrate/）。
快速開始：選擇你的專案類型
| 專案類型 | 使用時機 | 主要目錄 |
|---|---|---|
| CLI 工具 | 建立命令列應用程式 | cmd/{name}/、internal/、可選 pkg/ |
| 函式庫 | 建立可重複使用的程式碼供他人使用 | pkg/{name}/、internal/ 存放私有程式碼 |
| 服務 | HTTP API、微服務或網頁應用程式 | cmd/{service}/、internal/、api/、web/ |
| 單一儲存庫 | 多個相關套件/模組 | go.work、每個套件獨立模組 |
| 工作區 | 開發多個本地模組 | go.work、replace 指令 |
模組命名慣例
模組名稱（go.mod）
你的 go.mod 中的模組路徑應：
- 必須符合你的儲存庫 URL：
github.com/username/project-name - 僅使用小寫：
github.com/you/my-app（而非MyApp） - 多字詞使用連字號：
user-auth而非user_auth或userAuth - 具有語義：名稱應清楚表達用途
範例：
// ✅ 良好
module github.com/jdoe/payment-processor
module github.com/company/cli-tool
// ❌ 不良
module myproject
module github.com/jdoe/MyProject
module utils
套件命名
套件必須使用小寫、單數，並與其目錄名稱相符。→ 參閱 samber/cc-skills-golang@golang-naming 技能以取得完整的套件命名慣例和範例。
目錄佈局
所有 main 套件必須放在 cmd/ 中，且僅包含最少邏輯——解析旗標、串接依賴、呼叫 Run()。商業邏輯屬於 internal/ 或 pkg/。使用 internal/ 存放非匯出的套件，僅在程式碼對外部使用者有用時才使用 pkg/。
參閱目錄佈局範例以取得通用、小型專案和函式庫佈局，以及常見錯誤。
必要設定檔
每個 Go 專案應在根目錄包含：
- Makefile — 建置自動化。參閱 Makefile 範本
- .gitignore — git 忽略規則。參閱 .gitignore 範本
- .golangci.yml — linter 設定。參閱
samber/cc-skills-golang@golang-lint技能以取得建議設定
若使用 Cobra + Viper 進行應用程式設定，請參閱設定參考。
測試、基準測試與範例
將 _test.go 檔案與其測試的程式碼放在一起。使用 testdata/ 存放測試資料。參閱測試佈局以取得檔案命名、放置和組織的詳細資訊。
Go 工作區
在單一儲存庫中開發多個相關模組時，使用 go.work。參閱工作區以取得設定、結構和指令。
初始化檢查清單
開始新的 Go 專案時：
- [ ] 詢問開發者偏好的軟體架構（整潔、六邊形、DDD、扁平等）
- [ ] 詢問開發者偏好的 DI 方式——參閱
samber/cc-skills-golang@golang-dependency-injection技能 - [ ] 決定專案類型（CLI、函式庫、服務、單一儲存庫）
- [ ] 根據專案規模調整結構
- [ ] 選擇模組名稱（符合儲存庫 URL、小寫、連字號）
- [ ] 執行
go version以偵測目前的 Go 版本 - [ ] 執行
go mod init github.com/user/project-name - [ ] 建立
cmd/{name}/main.go作為進入點 - [ ] 建立
internal/存放私有程式碼 - [ ] 僅在有公開函式庫時建立
pkg/ - [ ] 對於單一儲存庫：初始化
go work並加入模組 - [ ] 執行
gofmt -s -w .以確保格式化 - [ ] 加入包含
/vendor/和二進位檔規則的.gitignore
相關技能
→ 參閱 samber/cc-skills-golang@golang-cli 技能以取得 CLI 工具結構和 Cobra/Viper 模式。→ 參閱 samber/cc-skills-golang@golang-dependency-injection 技能以取得 DI 方式比較和串接。→ 參閱 samber/cc-skills-golang@golang-lint 技能以取得 golangci-lint 設定。→ 參閱 samber/cc-skills-golang@golang-continuous-integration 技能以取得 CI/CD 管線設定。→ 參閱 samber/cc-skills-golang@golang-design-patterns 技能以取得架構模式。
