微服务模块应按业务边界划分，如auth、payment、notification，每个模块独立编译部署，拥有专属数据库、API前缀，且上线不牵连其他模块。
模块划分要按业务边界，不是按技术分层
微服务里最常见错误是把 user 服务拆成 user-api、user-service、user-repo 三个子模块——这本质还是单体思维。Golang 微服务的模块应该对应真实业务能力，比如 auth（认证）、payment（支付）、notification（通知），每个模块独立编译、部署、扩缩容。
判断模块是否合理，就看它能否回答这三个问题：有没有自己专属的数据库表？有没有独立的 API 路由前缀？上线/回滚时能不能不牵连其他模块？
- 一个模块通常对应一个 Go module（
go.mod文件），module path 如github.com/org/project/auth - 避免跨模块直接 import 另一个模块的
internal/包，必须通过定义好的 interface + wire 注入，或走 HTTP/gRPC - 共享实体（如
User结构体）不要放在公共pkg/下，而应由调用方按需定义 DTO，或通过 proto 定义统一 schema
根目录下不放业务代码，只放 glue 和 infra
项目根目录不是放 main.go 的地方，更不该塞满 handler、service、model。它只该有三类东西：cmd/（启动入口）、internal/（纯基础设施抽象）、api/（proto 定义）。
cmd/ 下按服务名分目录，例如 cmd/auth 和 cmd/payment，每个目录里是极简的 main.go，只做配置加载、wire 注入、server 启动。这样构建时可精确指定服务：go build -o auth ./cmd/auth。
-
internal/config：读取 env / yaml / viper，返回结构化配置，不暴露底层库 -
internal/logging：封装zerolog或zap，提供Loggerinterface，方便测试 mock -
internal/metrics：初始化 prometheus registry，暴露Counter/Gauge等接口，不耦合具体 exporter
每个业务模块内部用 functional options + wire 构建依赖树
别在 service.New() 里硬编码 DB 实例或 cache client。Golang 微服务依赖管理的核心是「显式传递」和「延迟绑定」。用 wire 生成初始化代码，配合 functional option 模式控制可选依赖。
例如 auth/service.go 的构造函数应长这样：
func NewService(
opts ...Option,
) *Service {
o := &options{}
for _, opt := range opts {
opt(o)
}
return &Service{db: o.db, cache: o.cache, logger: o.logger}
}
对应的 wire.go 在模块根目录，声明如何从 config.Config 和 redis.Client 组装出 *Service。这样测试时可传入内存 cache 和 mock db，生产时 wire 自动注入真实依赖。
- 所有外部依赖（DB、Redis、HTTP client）必须作为参数传入，不能在函数内 new
- 避免
init()全局注册，wire 生成的InitializeXXX()函数才是唯一
初始化入口
- 模块间若需轻量通信（如 auth 需查 user 状态），优先用
http.Get调用对方公开 API，而非引入对方 module
proto 文件统一放在 api/，生成代码进各模块 pb/
微服务之间通信靠 gRPC，但 proto 不该散落在各模块里。所有 .proto 文件集中放在项目根目录的 api/ 下，按领域组织，如 api/auth/v1/auth.proto、api/user/v1/user.proto。生成的 Go 代码则各自放入对应模块的 pb/ 目录（非 gen/ 或 generated/）。
这样做能强制接口契约先行，也避免循环依赖：当 payment 需要引用 auth 的 token 类型时，它 import 的是 github.com/org/project/api/auth/v1 这个独立 module，而不是 github.com/org/project/auth 这个服务实现。
- proto package 名必须带版本号，如
package auth.v1;，避免升级 breaking change - 生成命令建议封装进 Makefile，例如
make proto-gen-auth，确保所有开发者用同一套 protoc 插件版本 - 不要把
pb/加进 go.mod replace，它应是纯粹的生成产物，不参与模块依赖解析
