Golang微服务项目如何划分模块_Golang微服务目录结构设计

微服务模块应按业务边界划分，如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。

立即学习“go语言免费学习笔记（深入）”；

• internal/config：读取 env / yaml / viper，返回结构化配置，不暴露底层库
• internal/Logging：封装 zerolog 或 zap，提供 Logger interface，方便测试 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，它应是纯粹的生成产物，不参与模块依赖解析

真正难的不是目录怎么摆，而是每次新增字段、改接口、加模块时，能否快速判断“这个改动会影响谁”——这取决于你有没有守住业务边界、有没有让依赖流清晰可见、有没有把契约和实现彻底分开。