Golang项目目录结构规范

最近在学习Golang开发，想请教下大家关于项目目录结构的规范问题。目前看到很多开源项目都有自己的目录结构，但感觉不太统一。请问有没有比较通用的Golang项目目录结构规范可以参考？特别想知道如何处理cmd、internal、pkg这些常见目录的用法区别，以及单元测试文件和配置文件的存放位置是否有最佳实践？

2 回复

Golang项目目录结构建议遵循标准布局，如：

  • cmd/：存放可执行文件入口
  • pkg/：内部库代码
  • internal/：私有代码
  • api/：API定义文件
  • web/：Web静态资源
  • configs/：配置文件
  • scripts/：构建脚本
  • vendor/：依赖包

参考Go社区约定，保持简洁清晰。

更多关于Golang项目目录结构规范的实战系列教程也可以访问 https://www.itying.com/category-94-b0.html


在Go语言项目中，遵循良好的目录结构规范有助于提高代码的可读性、可维护性和可扩展性。以下是推荐的Go项目目录结构及说明：

1. 标准目录结构示例

myproject/
├── cmd/                    # 应用程序入口目录
│   ├── app1/              # 可执行程序1
│   │   └── main.go
│   └── app2/              # 可执行程序2
│       └── main.go
├── internal/              # 私有应用程序和库代码
│   ├── auth/             # 内部认证包
│   └── models/           # 内部数据模型
├── pkg/                  # 可被外部程序使用的库代码
│   ├── database/         # 数据库相关
│   └── utils/            # 工具函数
├── api/                  # API定义文件（如gRPC、OpenAPI）
├── web/                  # Web应用特定组件（模板、静态文件）
├── configs/              # 配置文件
├── scripts/              # 用于构建、安装的脚本
├── build/                # 打包和持续集成文件
├── deployments/          # IaaS、PaaS部署配置
├── test/                 # 额外的外部测试和测试数据
├── docs/                 # 文档文件
├── vendor/               # 项目依赖（Go modules启用后可省略）
├── go.mod                # 模块定义
├── go.sum                # 依赖校验
└── README.md             # 项目说明

2. 主要目录说明

cmd/

  • 包含应用程序的入口文件
  • 每个子目录对应一个可执行程序
  • main.go文件应尽量简单，主要做初始化工作
// cmd/myapp/main.go
package main

import (
    "myproject/internal/app"
    "myproject/pkg/config"
)

func main() {
    cfg := config.Load()
    app.Run(cfg)
}

internal/

  • 存放私有代码，外部项目无法导入
  • 按功能模块划分子目录
  • 防止项目内部实现细节被外部引用

pkg/

  • 公共库代码，可被其他项目导入使用
  • 应有清晰的API和文档
  • 按功能模块组织
// pkg/database/postgres.go
package database

import "database/sql"

type DB struct {
    *sql.DB
}

func NewPostgres(connStr string) (*DB, error) {
    db, err := sql.Open("postgres", connStr)
    if err != nil {
        return nil, err
    }
    return &DB{db}, nil
}

api/

  • 存放API定义文件
  • 如.proto文件（gRPC）或swagger.yaml（REST API）

3. 其他建议

  1. 模块管理：使用Go Modules管理依赖
  2. 命名规范：目录名使用小写，单词间用连字符
  3. 代码组织：按功能而非类型组织代码
  4. 配置管理：将配置与代码分离
  5. 测试文件：测试文件与被测试文件放在同一目录

4. 小型项目简化结构

对于小型项目，可简化为：

project/
├── cmd/
├── pkg/
├── internal/
├── go.mod
└── README.md

遵循这些规范能让项目结构更清晰，便于团队协作和后期维护。

回到顶部