标准golang项目布局

标准的 Go 语言项目布局旨在提高代码的可维护性和协作效率，以下是核心目录和文件的说明及最佳实践：

1. 核心目录结构

📁 cmd/

• 用途：存放项目所有可执行入口（main 包）
• 规范：
  • 每个子目录对应一个独立应用（如 cmd/api、cmd/cli）
  • 目录内仅保留 main.go 和轻量级启动逻辑
  • 避免将业务代码直接写入此目录

示例：

cmd/
  ├── server/   # Web 服务入口
  │   └── main.go
  └── cli/      # 命令行工具入口
      └── main.go

📁 internal/

• 用途：存储项目私有代码（仅允许当前模块内部导入）
• 特点：
  • Go 编译器强制禁止外部模块导入此目录代码
  • 适合放置核心业务逻辑和敏感实现
• 规范：
  • 按功能划分子包（如 internal/auth、internal/database）

📁 pkg/

• 用途：存放可供外部项目导入的公共库代码
• 适用场景：
  • 计划开源或跨项目复用的通用组件
  • 对外暴露清晰的 API 接口
• 示例：

  pkg/
    ├── utils/     # 通用工具函数
    └── logger/    # 日志库封装
  

2. 依赖管理

📄 go.mod & go.sum

• 作用：
  • go.mod：定义模块路径、Go 版本及直接依赖
  • go.sum：记录依赖项的加密哈希值，确保一致性
• 最佳实践：
  • 使用 go mod init 初始化模块
  • 通过 go get 管理依赖版本
  • 提交二者到版本控制

3. 其他重要文件

📄 README.md

• 必备内容：
  • 项目简介和核心功能
  • 快速安装指南 (go install 或构建步骤)
  • 基础使用示例
  • 贡献指南和许可证信息
• 增强项：
  • 架构图、API 文档链接、CI/CD 状态徽章

4. 可选目录（按需添加）

• 📁 api/：Protobuf/gRPC 接口定义文件
• 📁 configs/：配置文件模板（YAML/TOML）
• 📁 scripts/：构建/部署脚本
• 📁 test/：集成测试或测试数据
• 📁 vendor/：本地依赖副本（通过 go mod vendor 生成）

5. 典型项目示例

myproject/
├── cmd/
│   ├── api/
│   │   └── main.go
│   └── worker/
│       └── main.go
├── internal/
│   ├── service/
│   └── repository/
├── pkg/
│   └── httputils/
├── go.mod
├── go.sum
└── README.md

6. 关键原则

1. 关注点分离：cmd 只处理启动，业务逻辑在 internal/pkg
2. 访问控制：通过 internal 保护核心代码不被外部误用
3. 依赖透明：使用 Go Modules 替代手工管理 vendor/
4. 文档驱动：通过 README 降低新成员上手成本

这种结构被 Kubernetes、Docker 等知名项目采用，能有效支撑从微型服务到大型企业级应用的开发。