多模块项目通过独立go.mod划分服务，降低耦合，提升可维护性。建议根目录不设go.mod，按cmd、internal、pkg、modules分层，用replace本地调试，版本发布后替换为require，结合Makefile与CI实现高效构建测试。

理解单模块与多模块的区别

在Go早期实践中，常采用单一模块（即一个go.mod）管理整个项目。这种结构适合中小型项目，但随着功能拆分、服务独立部署需求增加，单一模块会带来耦合度高、构建慢、版本管理混乱等问题。

多模块项目则将不同子系统或服务划分为独立的模块，每个模块拥有自己的go.mod文件。这种方式更适合大型项目，例如：

• 微服务架构中，每个服务是一个独立模块
• 工具库被多个项目复用，单独作为一个模块发布
• 前端、后端、CLI工具分离管理

项目结构设计建议

合理的目录结构是多模块管理的基础。推荐以下布局：

myproject/
├── go.mod
├── cmd/
│   ├── service-a/
│   │   └── main.go
│   └── service-b/
│       └── main.go
├── internal/
│   ├── servicea/
│   └── serviceb/
├── pkg/
│   └── common/
├── modules/
│   ├── auth/
│   │   └── go.mod
│   └── payment/
│       └── go.mod
└── tools/
    └── generator/
        └── go.mod

说明：

• 根目录不设go.mod：避免误用根模块导致依赖冲突
• cmd/ 存放可执行程序入口，每个服务对应一个子目录
• internal/ 放私有代码，仅当前项目使用
• pkg/ 存放可复用的公共包
• modules/ 或 services/ 下每个子目录为独立模块

模块间的依赖管理

当模块A需要引用模块B时，可通过本地相对路径或版本化方式引入。

在开发阶段，推荐使用replace指令指向本地路径：

// modules/auth/go.mod
module example.com/auth

require (
    example.com/payment v0.0.0
)

replace example.com/payment => ../payment

这样可以在不发布版本的情况下进行联调。待稳定后，通过git tag发布版本，并移除replace语句：

require example.com/payment v0.1.0

注意：所有模块应遵循统一的模块命名规范，如公司域名/项目名/模块名，便于后期统一管理。

构建与测试策略

多模块项目构建需灵活处理。可编写Makefile统一调度：

build-all:
  cd cmd/service-a && go build -o bin/service-a
  cd cmd/service-b && go build -o bin/service-b

test-all:
  go test ./... -race

也可以使用golangci-lint等工具统一做静态检查。

对于CI流程，建议按模块粒度运行测试，避免全量构建拖慢流水线。关键点：

• 修改某个模块时，只触发相关服务的测试和构建
• 公共库变更应触发所有依赖它的服务回归测试
• 利用缓存机制加速重复构建