Golang项目结构规范详解

本文深入解析了Go语言项目中科学、可持续的目录结构规范，强调main.go必须置于cmd/子目录下以避免多入口冲突，internal/是编译期强制私有的高内聚领域实现区而非代码垃圾桶，pkg/则严格限定为具备稳定接口、可被外部复用的成熟模块，同时澄清测试文件必须与源码同包同目录、拒绝集中式tests/目录等常见误区——所有设计都紧扣Go工具链特性与工程实践本质，不堆砌分层、不预设架构，用最小必要结构支撑项目从单体到演进的全生命周期，让目录真正成为可执行的约束而非徒增负担的装饰。

main.go 放哪？别让它在根目录裸奔

Go 项目里 main.go 必须属于 package main，但直接扔在项目根目录是高频翻车点：一加个测试工具脚本就触发 multiple main packages 错误；二来 go run . 可能意外编译到不该编译的文件；三来 IDE 和 gopls 经常识别错模块边界。

• 正确做法：新建 cmd/myapp/ 目录，把 main.go 放进去——哪怕你只做一个服务
• main.go 里只做三件事：加载配置、初始化依赖、调用 app.Run()（或类似入口函数），不写业务逻辑
• 如果未来要拆后台任务或迁移命令，直接加 cmd/migrate/main.go 或 cmd/worker/main.go，go build 路径天然隔离

internal/ 不是“代码垃圾桶”，它有访问权限锁

internal/ 是 Go 官方约定的私有包路径，不是为了“看着整齐”才加的。它的核心作用是编译期强制隔离：任何在 github.com/user/project/internal/handler 下的包，外部 module 根本 import 不了，连 go list 都查不到。

• 错误用法：internal/utils 里塞字符串处理函数——这种通用逻辑该进 pkg/utils 或独立模块
• 正确用法：internal/user 包含用户领域全部内容：DTO 结构体、service 接口实现、repo SQL 封装——它对外只暴露接口，内部高内聚
• 注意嵌套深度：internal/core/domain/user/entity 这种四层结构纯属自我感动，Go 不需要 DDD 仪式感；扁平如 internal/user/service 和 internal/user/storage 更易维护

pkg/ 和 internal/ 怎么划界？看“能不能被别人 import”

区分 pkg/ 和 internal/ 的唯一标准，不是“重不重要”，而是“有没有稳定契约、是否准备被其他项目复用”。没有这个意识，很容易把还没定型的业务逻辑硬塞进 pkg/，结果别人一依赖就踩坑。

• pkg/logger 合理：封装 zerolog，暴露 Logger 接口和 NewLogger()，有文档、有测试、不绑定具体项目配置
• pkg/config 通常不合理：每个项目的配置结构、校验规则、环境变量映射都不同，应放在 configs/ 或 internal/config
• 一个信号：如果你写的 pkg/xxx 还没单独开 GitHub repo、没写 README.md 和版本号，那它大概率还不配叫 pkg

测试文件放哪？别建 tests/ 目录

Go 工具链不认 tests/ 这种集中式测试目录。所有 *_test.go 文件必须和被测源码在同一个目录、同属一个包（package user），否则 go test ./... 找不到，ginkgo 的 RunSpecs(t, ...) 也会失效——因为测试上下文 t 和目标包生命周期脱钩了。

• 正确姿势：internal/user/user.go 和 internal/user/user_test.go 并列，都声明 package user
• 若需白盒测试（比如测 unexported 方法），测试文件仍用 package user；若需黑盒（避免循环依赖），才改用 package user_test
• 不要手动建 tests/e2e/ 或 tests/integration/ ——用子测试 t.Run("create user") + 构建标签（//go:build integration）更符合 Go 哲学

目录结构不是越深越好，也不是越早定型越好。小项目从 cmd/myapp + internal/app 开始足够；等 handler 超过三个、SQL 查询开始重复、service 逻辑交叉时，再按领域或关注点拆。关键是每次移动文件后，立刻跑一遍 go mod tidy 和 go test ./... ——工具链的报错，永远比人脑先发现路径错乱。

今天关于《Golang项目结构规范详解》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！