go modules的replace指令仅用于本地开发调试，必须避免提交至生产go.mod；正确做法是用go mod edit -replace临时添加、ci中用go mod edit -dropreplace清除，并通过go list -m all | grep replace检查残留。
Go Modules 的 replace 指令必须用在本地开发期，不能进生产 go.mod
当你在单仓库里拆出 service/user、service/order、pkg/util 等多个逻辑模块，又想让它们互相引用最新代码（而非已发布的 tag），replace 是唯一安全的本地调试手段。但很多人把 replace 直接提交进 go.mod，导致 CI 构建失败或依赖不一致。
正确做法是：只在本地开发时用 go mod edit -replace 临时覆盖，CI 流水线中必须确保 GO111MODULE=on 且不设 replace —— 否则 go build 会静默跳过远程模块校验，上线后可能拉不到真实版本。
-
go mod edit -replace github.com/yourorg/pkg/util=../pkg/util（路径必须是相对当前模块根的） - CI 脚本开头加
go mod edit -dropreplace ./...清除所有 replace - 用
go list -m all | grep replace快速检查是否残留
internal/ 不是模块隔离工具，它只控制导入可见性
有人以为把 service/user 放进 internal/service/user 就能“隔离模块”，这是误解。internal/ 只阻止外部 module 导入，对同一仓库内其他包完全不设防——service/order 仍可直接 import internal/service/user/repo，破坏边界。
真正实现模块解耦靠的是显式接口定义和依赖倒置：
- 每个业务模块对外只暴露 interface，比如
user.UserService - 跨模块调用必须通过
pkg/contract这类共享接口包，禁止直连internal/下的具体实现 - 用
go list -f '{{.Deps}}' ./service/order | grep user定期扫描非法依赖
多 cmd 入口共用 internal 逻辑，但构建产物必须独立
单仓库常有 cmd/api、cmd/worker、cmd/cli 多个入口，它们共享 internal/config、internal/server，但构建时若共用一个 go build 命令，会因 CGO_ENABLED=0 等参数冲突导致静态链接失败。
解决方案是分步构建，且每个二进制明确指定输出路径：
CGO_ENABLED=0 go build -o bin/api ./cmd/apiCGO_ENABLED=0 go build -o bin/worker ./cmd/worker- 不要用
go build ./...批量构建，它会尝试编译internal/下的非 main 包，报错 “no Go files in …”
Docker 多阶段构建必须按二进制粒度切分
一个 Dockerfile 里试图 COPY 多个二进制（api、worker）进同一个镜像，看似省事，实则埋下部署隐患：Kubernetes 无法单独滚动更新某个服务，健康检查端点也容易混淆。
应该为每个 cmd/ 入口写独立 Dockerfile 或用 Makefile 控制构建上下文：
-
Dockerfile.api只 COPYbin/api，ENTRYPOINT 是["./api"] -
Dockerfile.worker只 COPYbin/worker，ENTRYPOINT 是["./worker"] - CI 中用
docker build -f Dockerfile.api -t myapp/api:latest .分别打标
最容易被忽略的是：所有二进制必须用相同 Go 版本、相同 CGO_ENABLED 设置构建，否则 Alpine 镜像里混入动态链接库，运行时报 not found 错误。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
