Go多服务项目Docker部署架构选型咨询

两种架构的选择对比 #

单go.mod（项目级统一依赖） #

• 适合服务间共享大量内部代码（比如公共工具库、模型定义）的个人项目，不用重复维护依赖版本，内部代码直接用相对路径引用，省心省力。
• 缺点是所有服务共享同一依赖树，某服务升级依赖可能影响其他服务；构建时若处理不当，容易把整个项目打包进镜像，导致体积偏大。

多go.mod（每个服务独立模块） #

• 适合服务间耦合度低、各自依赖差异大的场景，每个服务可独立升级依赖，构建上下文小，最终镜像更精简。
• 缺点是内部共享代码需要单独抽成模块（要么放项目内独立子模块，要么传私有仓库），跨服务引用要走模块导入流程，维护成本稍高。

单go.mod下的Docker构建方案（解决你遇到的构建失败问题） #

很多开源项目用单go.mod照样实现独立部署，核心是正确设置构建上下文+多阶段构建，既保证依赖能正确解析，又避免冗余文件打包。

举个典型项目结构：

my-project/
├── go.mod
├── go.sum
├── common/          # 公共代码目录
│   └── utils.go
├── service-a/       # 服务A
│   └── main.go
└── service-b/       # 服务B
    └── main.go

针对service-a的Dockerfile写法（多阶段构建，最小化镜像体积）：

# 第一阶段：编译二进制文件
FROM golang:1.22-alpine AS builder

WORKDIR /app
# 先复制依赖文件，利用Docker缓存，避免代码变动就重新下载依赖
COPY go.mod go.sum ./
RUN go mod download

# 复制整个项目代码（单go.mod需要完整模块上下文）
COPY . .

# 编译服务二进制，关闭CGO减小体积，指定输出路径
RUN CGO_ENABLED=0 GOOS=linux go build -o /bin/service-a ./service-a

# 第二阶段：生成轻量运行镜像
FROM alpine:latest

# 从构建阶段复制编译好的二进制
COPY --from=builder /bin/service-a /bin/service-a

# 暴露服务端口
EXPOSE 8080

# 启动服务
CMD ["/bin/service-a"]

构建命令注意：必须在项目根目录执行，用-f指定服务目录下的Dockerfile：

docker build -t service-a:v1 -f ./service-a/Dockerfile .

关键要点：

• 根目录执行构建才能让Docker读取到项目级的go.mod和完整模块代码
• 多阶段构建只保留运行所需的二进制，抛弃Go SDK等冗余内容
• 先复制go.mod/go.sum再下载依赖，最大化利用Docker层缓存，加快构建速度

多go.mod下的Docker构建方案 #

如果选择给每个服务单独建go.mod，调整项目结构如下：

my-project/
├── common/          # 公共代码也做成独立模块
│   ├── go.mod
│   └── utils.go
├── service-a/
│   ├── go.mod
│   ├── go.sum
│   └── main.go
└── service-b/
    ├── go.mod
    ├── go.sum
    └── main.go

service-a的Dockerfile可以直接在服务目录下构建，无需依赖项目根目录：

FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o /bin/service-a .

FROM alpine:latest
COPY --from=builder /bin/service-a /bin/service-a
EXPOSE 8080
CMD ["/bin/service-a"]

构建命令直接在service-a目录执行：

cd service-a && docker build -t service-a:v1 .

如果要引用common模块，需在service-a的go.mod里添加本地替换指令（开发阶段）：

replace github.com/yourname/common => ../common
require github.com/yourname/common v0.0.0-00010101000000-000000000000

给Docker新手的实操建议 #

• 个人项目初期优先选单go.mod方案，减少维护成本，共享代码更方便
• 务必用多阶段构建，这是Go项目做Docker镜像的标准操作，能把镜像体积从几百M压到几M
• 严格注意构建上下文路径：单go.mod必须在根目录构建，多go.mod可以在服务目录单独构建
• 等后续服务间依赖差异变大、需要独立发布依赖版本时，再考虑拆分多go.mod

内容的提问来源于stack exchange，提问作者petar dragnev