Golang项目目录结构怎么组织_Golang项目结构教程【必看】-Golang-PHP中文网

main.go 应放在 cmd/yourapp/ 下，如 cmd/api/main.go；根目录只留 go.mod 等配置文件；internal/ 用于私有包，config/ 存项目专属配置，pkg/ 存可独立 go get 的通用组件。

golang项目目录结构怎么组织_golang项目结构教程【必看】

main.go 到底该放哪？别让它在根目录“裸奔”

Go 项目里，main.go 必须放在 package main 下，但它绝不该孤零零躺在项目根目录——这是绝大多数新手踩进的第一个坑。根目录塞了 main.go，很快就会混进 config.yaml、router.go、db.go，最后 go list ./ 都可能报错 “multiple main packages”。

cmd/yourapp/main.go 是标准解法：一个服务一个子目录，比如 cmd/api/main.go 启 HTTP 服务，cmd/migrate/main.go 跑迁移
main.go 里只做三件事：加载配置、初始化依赖（DB、logger、router）、调用 server.ListenAndServe() —— 别写 SQL、别注册路由、别解析环境变量
根目录只留 go.mod、Makefile、.gitignore；运行时用 go run cmd/api/main.go，构建用 go build -o bin/api cmd/api

internal/ 不是“代码回收站”，它有明确的导入边界

internal/ 是 Go 官方约定的私有包路径，不是让你把所有“暂时不想公开”的代码都扔进去的地方。它的作用很硬：任何在 github.com/user/project/internal/xxx 下的包，外部模块（包括你自己的 cmd/ 以外的其他仓库）根本 import 不了。

正确用法：internal/handler（HTTP 入口）、internal/service（业务逻辑）、internal/repository（数据访问接口）、internal/model（领域结构体）
常见误用：internal/utils 放通用字符串函数 → 应挪到 pkg/utils 或直接拆成独立模块；internal/db 里硬编码 gorm.Open() → DB 初始化应由 cmd/ 控制，internal/repository 只依赖抽象接口
模型（如 User struct）统一放 internal/model，别在 handler 和 repository 里各自定义一份

config/ 和 pkg/ 怎么分？看它会不会被另一个项目 `go get`

配置加载逻辑和通用工具包，名字像、位置近，但职责天差地别。混淆这两者，轻则导致项目耦合变重，重则让别人误引你内部实现细节。

Golang Google Wire

在 Go 中使用 google/wire 实现编译时依赖注入——wire.NewSet、wire.Build、wire.Bind（接口→实现）、wire.Struct、wire.Value、wire.Interface

下载

config/ 是项目专属：读 config.development.yaml、绑定环境变量前缀（如 APP_）、校验 DB.URL 是否非空 —— 所有代码只在本项目跑，结构体定义在 internal/config/config.go，用 viper.Unmarshal() 绑定
pkg/ 是“可交付组件”：比如 pkg/logger 封装 zerolog 并暴露 Logger 接口；pkg/httpclient 提供带默认超时和 metrics 的 client 工厂 —— 它们必须能被 go get github.com/user/pkg/logger 独立使用
没想清楚要不要复用？先别建 pkg/。90% 的“通用工具”最后只在本项目用三次，硬塞进去反而增加维护负担

handlers/ 还是 api/？命名要让人一眼看懂它干啥

HTTP 处理层的目录名，本质是团队沟通契约。别用模糊词如 routes/、web/、controllers/ —— Go 社区没有 controller 概念，routes 又容易和路由注册逻辑混淆。

推荐用 api/ 或 handlers/：前者强调“对外暴露的接口集合”，后者更贴近 Go 原生 http.Handler 语义；两者都比 controllers 更准确
api/v1/ 可以存在，但前提是真有 v2 兼容需求；别为了“看起来专业”提前分版本
每个 handler 文件只负责一个资源或行为：比如 user_handler.go 处理 /users 相关请求，不掺杂 auth 或 file 逻辑；参数校验、响应构造在此完成，但不碰 db.QueryRow()