go微服务本地开发需用docker compose仅运行中间件，go服务以主机进程运行并配合air热重载；consul须配置-bind/-client为0.0.0.0，redis关protected-mode，postgresql配healthcheck，服务注册地址统一用127.0.0.1，go.mod须显式require所有通信依赖，连接需重试机制。
Go 微服务本地开发环境不能靠 docker-compose up 一把梭——它只管容器启停，不管 Go 服务是否真能连上 DB、是否加载了正确模块、是否支持热重载调试。真正能跑通的组合是：Docker Compose 跑中间件（PostgreSQL/Redis/Consul），Go 服务用主机进程运行 + air 热重载 + 显式配置服务发现地址。
docker-compose.yml 只该管中间件，别把 Go 服务写进去
把 Go 服务也塞进 docker-compose.yml 是新手最常踩的坑：编译慢、dlv 断点失效、环境变量和宿主机不一致、go.mod 路径错乱。真实高效的做法是：
- 只在
docker-compose.yml中定义postgres、redis、consul这类有状态或协议复杂的服务 - 为
postgres加healthcheck：用pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}，避免 Go 启动时报dial tcp ... connection refused - Consul 必须加启动参数
-client=0.0.0.0 -bind=0.0.0.0，否则 Go 客户端连不上（默认只监听127.0.0.1） - Redis 配置里关掉
protected-mode yes，否则 Go 的redis.Client会卡在NOAUTH Authentication required - Go 服务代码里连接中间件时，地址统一用
127.0.0.1（不是localhost），因为 Docker 容器内localhost指向自己，而宿主机 Go 进程要直连 Docker 网络桥接的中间件
Go 服务必须用主机进程运行，且配好 air 热重载
go run main.go 直接进容器看似简单，实则每次改代码都重启整个容器，丢状态、断调试、无法复用 go.sum 缓存。正确路径是宿主机装 air 并管理生命周期：
- 执行
go install github.com/cosmtrek/air@latest安装到$GOPATH/bin - 项目根目录放
.air.toml，关键配置：root = "."、bin = "./tmp/main"（避免每次重建二进制） -
volumes映射源码时排除node_modules、vendor、go/pkg—— 否则 inotify 事件爆炸，air卡死 - 启动命令就是
air，不是go run；它会监听文件变化、自动go build、杀旧进程、起新进程
go.mod 和 GOPROXY 必须显式对齐宿主机环境
Docker 构建阶段的 go mod download 和宿主机 go run 用的是同一套模块缓存和代理逻辑。一旦不一致，就会出现 module github.com/xxx/yyy is not active 或依赖拉不到：
- 确认
go version≥ 1.21（推荐），避免go.sum校验失败 - 运行
go env GOPROXY，若为空或不是https://proxy.golang.org,direct，用go env -w GOPROXY=https://goproxy.cn,direct设为国内可用地址 -
go mod init前确保不在$GOPATH/src下创建项目——否则模块路径与目录结构冲突，报cannot find module providing package - 所有微服务间通信的依赖（如
github.com/go-kit/kit、google.golang.org/grpc）必须显式出现在各自go.mod的require块里，不能靠隐式导入
网络和配置必须手动打通，depends_on 不顶用
depends_on 只检查容器是否 started，不等端口 ready、不等 DB 初始化完成。Go 服务启动失败十次里有八次是因为这个：
-
depends_on: [postgres]必须搭配condition: service_healthy，而后者依赖前面说的healthcheck - Go 代码里仍需实现连接池初始化重试：比如用
sql.Open后循环调db.Ping()，最多重试 30 秒，超时 panic - 配置管理用
viper+.env文件，但注意viper.AutomaticEnv()会覆盖.env里的同名变量，调试时优先查os.Getenv输出 - 服务注册地址写
http://127.0.0.1:8500（Consul）、redis://127.0.0.1:6379（Redis），别用host.docker.internal—— Linux 下默认不可用，得额外加extra_hosts才行
真正卡住人的从来不是语法或命令，而是中间件健康检查没配、Go 进程没用主机模式跑、模块代理没对齐、连接重试逻辑空缺——这些点漏掉任意一个，docker-compose up 就只是个假成功。
