Go多模块项目需按功能拆分为独立模块（如api/、service/），各设go.mod；根模块仅作版本锚点，用replace本地开发、require统一管理；严禁循环依赖，接口应置于shared/；CI构建须进子目录执行。

在 Go 中初始化多模块项目，核心是避免单一 go.mod 文件管理整个大型代码库，转而按功能或服务边界拆分为多个独立模块（每个模块有自己 go.mod），再通过 replace、require 和目录结构设计实现依赖协同。

明确模块边界，按职责划分目录

不要把所有代码塞进一个 cmd 或 internal 下。推荐顶层按业务/能力分模块：

• api/：提供 HTTP/gRPC 接口，含自己的 go.mod
• service/：核心业务逻辑，可被多个 api 复用
• data/：数据访问层（ORM、DB client 封装）
• shared/：跨模块通用类型、错误定义、工具函数
• cmd/app1/、cmd/app2/：可独立部署的服务入口

每个子目录运行 go mod init example.com/project/api 初始化为独立模块，模块路径需全局唯一且反映实际导入路径。

主模块统一协调依赖版本

通常设一个“根模块”（如项目根目录的 go.mod），不写业务代码，只做版本锚点和跨模块引用管理：

Alibabacloud Sdk Client Initialization For Golang

初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。

下载

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

• 在根 go.mod 中 require 所有子模块（如 example.com/project/service v0.0.0）
• 用 replace 指向本地路径，开发时实时生效：
  replace example.com/project/service => ./service
• 发布前删掉 replace，打 tag 后 go mod tidy 自动升级为语义化版本

避免循环依赖与隐式耦合

Go 模块间不能循环 import，这是编译时报错的硬约束。常见陷阱：

• service 依赖 data ✅，但 data 又反向依赖 service ❌
• 解决方法：提取接口到 shared/interface，让 data 仅依赖接口，service 实现它
• 禁止跨模块直接引用 internal/ —— 它只对本模块可见；对外暴露必须通过 public/ 或根包导出

CI/CD 和发布时保持一致性

多模块项目上线前需确保各模块版本锁定且可复现：

• 每个模块的 go.sum 单独维护，根模块不覆盖子模块校验和
• 构建命令建议进入子模块目录执行：
  cd cmd/app1 && go build -o app1
• CI 中可先 go mod vendor 各模块（非必需，但利于离线构建），或统一用 go build -mod=readonly 防意外修改 go.mod