Golang搭建Web项目教程

Go Web项目应分层设计：HTTP层抽至cmd/web，路由与handler放internal/handler或router，配置用viper支持热加载，数据库等逻辑交由service/repository，按业务域（如internal/user）组织包，依赖通过interface隔离，严格管理go.mod依赖。

main.go 里别直接写 HTTP 处理逻辑

很多人一上手就往 main.go 里塞 http.HandleFunc 和一大堆路由，结果不到三天代码就变成面条。Go 的 Web 项目不是靠“堆逻辑”跑起来的，而是靠分层和可测试性撑住的。

建议把 HTTP 层单独抽成 cmd/web/main.go，只负责初始化服务、加载配置、启动 http.Server；实际路由注册、中间件、控制器都放在 internal/handler 或 internal/router 下。这样单元测试 handler 时，不用起 server，也不用 mock http.ResponseWriter —— 直接传个 httptest.ResponseRecorder 就行。

• main.go 应该只有 20 行以内，核心是调用 app.Run() 这类封装好的启动函数
• 路由定义别硬编码在 main() 里，用 chi.Router 或 gorilla/mux 等支持子路由的库，方便按模块拆分（比如 v1/auth/ 和 v1/user/）
• 避免在 handler 里直接操作数据库或调外部 API —— 那是 internal/service 和 internal/repository 的事

config 包必须支持多环境和热加载能力

本地开发用 config.yaml，测试环境用 config.test.yaml，上线却还在改 main.go 里的端口号？这迟早出事。Go 没有像 Spring Boot 那样的自动配置，但可以用 spf13/viper + 环境变量兜底。

关键点不是“能不能读 yaml”，而是“改了配置要不要重启”。开发阶段推荐用 viper.WatchConfig() 监听文件变化，配合 fsnotify 实现热重载；生产环境则强制走环境变量（DATABASE_URL、HTTP_PORT），避免配置文件权限或路径问题。

• 配置结构体要定义在 internal/config/config.go，字段加 mapstructure tag，比如 Port int `mapstructure:"port"`
• 不要在 init() 函数里初始化 config —— 它无法被单元测试覆盖，且依赖顺序难控制
• 数据库连接池大小、超时时间这些关键参数，必须从配置读，不能写死在 repository.NewDB() 里

internal/ 目录下按职责而非技术分包

看到有人建 internal/models、internal/handlers、internal/repositories，看起来很整齐，但很快就会发现：一个用户登录流程要横跨 4 个包，每个包又依赖其他包的内部类型，最后改个字段得同步修 6 个文件。

更靠谱的做法是按业务域划分，比如 internal/user 下放该领域全部东西：DTO（user/request.go）、领域模型（user/model.go）、service（user/service.go）、repository 接口（user/repository.go），再由 internal/user/postgres.go 实现具体 DB 逻辑。这样新增功能时，所有改动集中在同一目录，IDE 也能更好跳转。

• 跨 domain 调用只能通过 interface，比如 user.Service 依赖 auth.TokenGenerator 接口，而不是具体实现
• internal/ 外的包（如 cmd/ 或 pkg/）不能 import internal/xxx/xxx 的具体实现，只能 import internal/xxx 的公开接口
• 别为了“整洁”把所有 error 定义塞进 internal/errors —— 每个 domain 自己定义 ErrInvalidEmail 这类语义化错误更易维护

go.mod 的 replace 和 indirect 依赖要定期清理

跑 go run . 成功不代表项目干净。很多初学者加了个 SDK 就直接 go get github.com/some/sdk，结果拉进来一堆 indirect 依赖，其中某些版本还跟现有中间件冲突（比如两个库都依赖不同版的 golang.org/x/net）。更麻烦的是，本地能跑，CI 构建失败，查半天发现是 replace 指向了某个 fork 分支，而那个分支早已删库。

每次加新依赖后，执行 go mod graph | grep 'some-ambiguous-name' 查冲突；每周至少一次 go mod tidy -v，看哪些 indirect 其实没被用到；所有 replace 必须带注释说明原因（比如“fix CVE-2023-xxxx”），且目标 commit 必须是 tagged 版本，不是 master 或 main。

• 禁止在 go.mod 里写 replace github.com/a/b => ./local-fix 这种本地路径 —— CI 机器找不到
• go list -u -m all 可以列出所有可升级依赖，但别盲目升级，尤其 database/sql 相关驱动和 grpc-go 这类底层库
• 如果用了 embed 加载静态资源，注意 Go 1.19+ 对 //go:embed 路径校验更严，相对路径必须在当前包目录内

真实项目里最难的从来不是“怎么搭架子”，而是“当第 3 个业务方要复用 user 模块时，你敢不敢把 internal/user 提成独立 pkg/user 并保证不破环原有接口”—— 结构的价值，是在膨胀时还能让人看清边界。