Golang Web项目如何组织目录结构_Web项目结构设计说明_网络技术

main.go 应放在 cmd/yourapp/ 目录下，根目录仅保留 go.mod 等工程配置；handlers 比 controllers 更符合 Go 习惯，用于 HTTP 入口；internal 子包按依赖方向划分，domain 无外部依赖，service 依赖 repository；配置需在 main() 最早阶段加载并校验。

main.go 放哪？别塞进根目录里

绝大多数新手会把 main.go 直接扔项目根目录，结果越写越乱，go run . 一执行就报错“multiple main packages”。Go 要求每个可执行程序有且仅有一个 main 包，且必须含 func main()。正确做法是单独建 cmd/yourapp 目录，把 main.go 放进去。

cmd/ 下可放多个子命令（如 cmd/api、cmd/migrate），方便后期拆分服务或加 CLI 工具
根目录下只保留 go.mod、Makefile、.gitignore 等工程级配置，不放业务代码
运行时用 go run cmd/yourapp/main.go，或 go build -o bin/yourapp cmd/yourapp

handlers 和 controllers 到底该用哪个词？

Go 社区没有强制 MVC 分层，但 handlers 是更被广泛接受的命名——它直白表达“HTTP 请求入口”，不带框架包袱。用 controllers 容易让人误以为你在套 Spring 或 Rails 那套逻辑，反而引发团队理解偏差。

handlers/ 下按业务域组织，比如 handlers/user_handler.go、handlers/order_handler.go，每个文件只负责路由绑定和请求流转
真正的业务逻辑必须下沉到 internal/service/，handlers 层禁止出现 SQL、Redis 调用或复杂判断
如果用了 Gin/Echo，handlers 里只调 c.JSON、c.Bind 这类框架原语，不封装中间件逻辑

internal/ 下怎么切子包？按依赖方向而不是功能名词

常见错误是建 internal/models、internal/repositories、internal/utils，看似整齐，实则破坏了 Go 的依赖约束。Go 的 internal 是编译期隔离机制，子包之间仍可互相 import，但外部模块无法引用 —— 所以划分依据应是「谁依赖谁」。

internal/service/ 可依赖 internal/repository/ 和 internal/domain/，但反过来绝对不行
internal/domain/ 放纯结构体（如 User、Order）和核心方法（如 user.Activate()），不引入任何外部依赖
internal/repository/ 只做数据访问，用接口定义（如 UserRepo），具体实现（如 pgUserRepo）放在 internal/infrastructure/，方便测试 mock

config 和 env 加载顺序搞错，本地能跑线上炸锅

os.Getenv 返回空字符串不报错，但下游代码可能 panic。很多项目把环境变量解析塞在

main() 开头，却没处理缺失字段，导致服务启动后才在某个 HTTP 请求里崩掉。

用 github.com/spf13/viper 或手写 config.Load() 函数，在 main() 最早阶段加载并校验全部必需字段（如 DB_URL、JWT_SECRET）

配置结构体用 struct tag 标明 required，例如：

type Config struct {
    DBURL string `mapstructure:"db_url" validate:"required,url"`
}

开发环境用 .env，生产环境用 Kubernetes ConfigMap 或 systemd EnvironmentFile，但加载逻辑统一走同一入口函数，避免分支差异

Go 的目录结构不是靠“看起来整洁”取胜，而是靠 internal 的依赖边界、cmd/ 的二进制隔离、以及配置加载时机这种细节守住底线。一旦某天要加 gRPC 接口、换数据库驱动、或者把用户服务拆成独立进程，这些设计点就会立刻决定重构成本是半天还是两周。

# redis # js # git # json # go # github # golang # app # 工具 # ai # 路由 # 环境变量 # mvc # sql # spring # 中间件 # gin # echo # 封装 # 字符串 # 结构体 # 接口 # internal # Struct # 数据库 # kubernetes # http # 重构 # 加载 # 放在 # 报错 # 就会 # 让人 # 多个 # 你在 # 半天 # 用了 # 这类

相关栏目：【网站优化151355 】【网络推广146373 】【网络技术251813 】【 AI营销90571 】