Go微服务项目结构应按业务域划分包，internal下设internal/user等限界上下文，包内分domain/application/infrastructure；cmd只做flag解析、配置加载与NewServer.Run；pkg须满足可复用且无业务语义；go mod replace用于提前模拟模块边界。
Go 微服务项目结构不是“怎么好看怎么来”，而是直接影响你三个月后敢不敢动登录逻辑、新同事两天内能不能改订单状态、CI 失败时能不能 30 秒定位到问题模块——结构错了，重构成本不是线性上升，是指数爆炸。
internal/ 下按业务域建包，别按 handler/service/repo 拆目录
看到 internal/handler、internal/service、internal/repository 这种顶层目录，基本说明项目已开始技术债累积。所有用户相关的 handler、service、repo 全挤在一个目录里，改个密码重置逻辑得横跨三个目录翻文件，还容易误改其他业务的同名函数。
正确做法是每个限界上下文一个包：internal/user、internal/order、internal/payment，包内再按职责组织文件：
-
internal/user/domain/：放User结构体、PasswordHasher接口、UserCreated领域事件 -
internal/user/application/：只暴露CreateUser函数和CreateUserRequest类型，不导出数据库模型 -
internal/user/infrastructure/http/：HTTP handler 只调用application层函数，不碰domain实现细节 - 跨业务调用必须走 domain event 或 async pub/sub，禁止
import "xxx/internal/order/application"
cmd/ 目录只留 main.go，且只做三件事
常见错误是把配置加载、中间件组装、gRPC server 初始化全塞进 cmd/api/main.go。结果新增一个 cmd/worker 就得复制粘贴大段逻辑，稍有改动就不同步。
立即学习“go语言免费学习笔记（深入）”；
cmd/api/main.go 应该极薄，只干三件事：
- 解析命令行 flag（如
-port、-env） - 加载
internal/config并验证必填项 - 构造
internal/app.NewServer()实例并调用.Run()
所有路由注册、健康检查端点、中间件链构建，都下沉到 internal/app 或更下层。这样 cmd/worker/main.go 只需复用同一套 internal/ 逻辑，换入口函数即可。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
pkg/ 和 internal/ 的边界必须卡死
很多人把 pkg/ 当成“工具函数垃圾桶”，塞进 UserValidator、OrderHelper 这类带业务名词的代码，结果导致服务间强耦合，一改就崩。
判断一个包该不该进 pkg/，只看两条硬标准：
- 能否脱离当前项目，在另一个完全无关的 Go 项目中直接
go get使用？比如pkg/health（通用健康检查 HTTP handler）、pkg/trace（OpenTelemetry 封装） - 是否不含任何业务语义？
pkg/uuid合法，pkg/userid不合法；pkg/httpx合法，pkg/apiclient不合法（除非它封装的是通用 REST client，而非某服务专属 client）
一旦发现 pkg/ 下某个包被 3 个以上业务模块强依赖，立刻警惕——它正在演变成“上帝工具包”，该按场景拆分了。
go mod replace 不是临时补丁，是模块化演进的起点
初期不想拆服务？没关系。先用 replace 在 go.mod 里模拟模块边界：
replace github.com/yourorg/user-service => ./internal/user
这样做的好处是：
- 强制
internal/order不能直接 importinternal/user/repo，只能通过github.com/yourorg/user-service接口调用 - 单元测试可真实验证接口契约，而不是靠 mock
- 未来真要拆成独立 repo，只需删掉
replace行，改用真实远程地址
别等“业务稳定了再重构结构”——结构设计滞后一天，技术债就滚雪球一天。真正难的从来不是写代码，而是让别人能放心改你的代码。
