專注于 Golang 相關文章和資料的開源項目 go-home ，歡迎關注！

在Go項目開發中，良好的目錄結構對項目的可維護性和團隊協作至關重要。本文基于社區廣泛認可的項目布局標準，介紹Go項目的目錄組織最佳實踐。

1. 核心應用目錄 - /cmd

項目的主要應用程序入口點應放在/cmd目錄下。每個應用程序都應該有自己的子目錄：

/cmd
  /myapp
    main.go     // package main
  /myworker
    main.go     // package main

每個子目錄名應該與生成的可執行文件名一致。main.go文件應該盡量簡潔，實際的業務邏輯應該導入自/internal或/pkg目錄。

2. 私有代碼目錄 - /internal

私有應用代碼和庫代碼放在/internal目錄。Go編譯器會強制執行這個目錄的訪問控制，其他項目無法導入internal目錄下的包：

/internal
  /app
    /myapp        // 應用私有代碼
  /pkg
    /database     // 內部共享庫
    /auth         // 認證模塊

這是Go語言級別的保護機制，確保內部實現不會被外部項目依賴。

3. 公共庫目錄 - /pkg

可以被外部項目導入的庫代碼放在/pkg目錄：

/pkg
  /httputil       // HTTP工具庫
  /stringutil     // 字符串處理工具
  /errors         // 錯誤處理包

使用/pkg目錄時要謹慎，確保這里的代碼確實適合對外公開，并且有良好的API設計和文檔。

4. 依賴管理 - /vendor

使用vendor目錄管理項目依賴（如果啟用了vendor模式）：

# 啟用vendor模式
go mod vendor

# 使用vendor構建
go build -mod=vendor

現代Go項目通常使用Go Modules，vendor目錄變為可選。

5. API定義目錄 - /api

API定義文件、協議文件放在/api目錄：

/api
  /openapi
    swagger.yaml     # OpenAPI規范
  /proto
    user.proto       # Protocol Buffers定義
  /graphql
    schema.graphql   # GraphQL schema

6. 配置文件目錄 - /configs

配置文件模板或默認配置：

# /configs/config.yaml
server:
  host: localhost
  port: 8080
database:
  driver: postgres
  dsn: postgres://localhost/mydb

注意：實際的配置文件（包含敏感信息）不應該提交到版本控制。

7. 部署相關目錄

部署和構建相關的文件分別組織在不同目錄：

/build
  /ci              # CI配置文件
    .travis.yml
  /package         # 打包腳本
    Dockerfile

/deployments
  /docker-compose
    docker-compose.yml
  /kubernetes
    deployment.yaml

8. 腳本目錄 - /scripts

各種構建、安裝、分析等腳本：

/scripts
  build.sh         # 構建腳本
  install.sh       # 安裝腳本
  test.sh          # 測試腳本
  lint.sh          # 代碼檢查

9. 測試目錄 - /test

額外的外部測試應用和測試數據：

/test
  /integration     // 集成測試
  /e2e            // 端到端測試
  /testdata       // 測試數據文件
  /mocks          // 模擬對象

單元測試應該與被測試的代碼在同一個包中，使用_test.go后綴。

10. 其他常用目錄

文檔和工具相關目錄：

/docs           # 項目文檔
  design.md     # 設計文檔
  api.md        # API文檔

/tools          # 項目工具
  /gen          # 代碼生成工具

/examples       # 示例代碼
  simple.go     # 基礎示例
  advanced.go   # 高級用法

/assets         # 靜態資源
  /images       # 圖片
  /templates    # 模板文件

11. 不推薦的做法

避免以下目錄結構：

# 不要使用src目錄
/src  ?

# 避免在根目錄放置過多Go文件
main.go  ? (除非是簡單的單文件項目)
server.go ?
handler.go ?

Go項目不需要Java風格的src目錄，直接在項目根目錄組織代碼即可。

12. 實際項目示例

一個典型的Web服務項目結構：

myproject/
├── cmd/
│   └── server/
│       └── main.go
├── internal/
│   ├── handler/
│   │   └── user.go
│   ├── model/
│   │   └── user.go
│   └── service/
│       └── user.go
├── pkg/
│   └── logger/
│       └── logger.go
├── api/
│   └── openapi.yaml
├── configs/
│   └── config.yaml
├── deployments/
│   └── docker-compose.yaml
├── scripts/
│   └── build.sh
├── go.mod
├── go.sum
└── README.md

總結

良好的項目結構能夠提高代碼的可維護性、可測試性和團隊協作效率。雖然這不是Go官方強制的標準，但已經被社區廣泛采用。在實際項目中，應該根據項目規模和團隊需求，選擇合適的目錄結構，避免過度設計。小型項目可以從簡單結構開始，隨著項目增長逐步完善目錄組織。