go微服务开发环境搭建需三步：安装go 1.21+并配置goproxy；按standard layout初始化模块与目录结构；集成grpc/http、viper配置、zap日志及docker compose本地联调。
go 版本必须 ≥ 1.21，低于这个版本会踩 go.sum 校验失败、泛型支持不全、module 机制不稳定等坑，别信系统包管理器装的旧版。
确认 Go 环境与模块模式是否就绪
执行 go version，输出应类似 go version go1.21.6 linux/amd64。若显示 1.18 或更低，直接去 https://go.dev/dl/ 下载二进制包解压安装。
运行 go env GOPATH，如果返回空或非 $HOME/go 路径，说明模块模式已生效——这是预期状态，不要强行设 GOPATH；若仍看到旧路径，检查 ~/.bashrc 或 ~/.zshrc 是否残留 export GOPATH=... 并删掉。
常见错误现象：go mod init 后报 cannot find module providing package，大概率是因为项目建在 $GOPATH/src 下，而模块路径又和目录结构不匹配。解决方案：新建空目录（如 ~/projects/order-svc），不在 $GOPATH 里初始化。
初始化项目结构并配置 GOPROXY
微服务不是单个 main.go，结构错一步，后期改起来成本翻倍。先跑：go mod init yourcompany.com/order-svc（域名前缀防包冲突）。
国内必须设代理，否则 go get 卡死或失败：go env -w GOPROXY=https://goproxy.cn,direct。验证：执行 go list -m -f {{.Dir}} golang.org/x/net，能快速返回路径即生效。
目录结构建议按最小可用原则组织：
-
cmd/order-svc/main.go：只做初始化（加载配置、注册组件、启动 server） -
internal/：放业务逻辑，外部无法 import，保证封装性 -
configs/config.yaml和.env：配置分离，.env不提交 Git，但要配.env.example -
api/：放.proto文件，后续用buf或protoc生成代码
本地依赖服务必须容器化启动
别在宿主机裸装 PostgreSQL、Redis、RabbitMQ——端口冲突、版本混杂、清理困难。用 docker-compose.yml 统一管理，但几个关键点常被忽略：
PostgreSQL 镜像启动失败？日志只写 database system is shut down，其实是 POSTGRES_PASSWORD 没设。必须显式声明：environment: POSTGRES_PASSWORD: password123。
Redis 在容器里连不上？默认 bind 127.0.0.1，得加启动参数：command: redis-server --bind 0.0.0.0:6379 --protected-mode no。
Go 服务容器内解析不到 host.docker.internal？macOS/Windows 默认可用，Linux 需手动加：extra_hosts: ["host.docker.internal:host-gateway"]。
网络别用默认 bridge，显式定义一个网络名，比如：networks: { micro-net: { driver: bridge } }，所有服务都加入它，避免 DNS 解析失败。
main.go 别硬编码配置，viper + .env 是底线
启动前读配置是刚需，但很多人直接写 os.Getenv("DB_HOST")，结果字段名大小写、下划线转点号规则全错。正确做法：
用 viper 加载：viper.SetConfigName("config"); viper.SetConfigType("yaml"); viper.AddConfigPath("configs/")，再调 viper.AutomaticEnv() 开启环境变量映射。
注意：DB_HOST 环境变量对应的是 viper.GetString("db.host")，不是 "DB_HOST"；.env 文件内容必须是 DB_HOST=localhost 这种纯 key=value，不能带空格或引号。
热重载调试时，改了 .env 却没生效？检查 air 配置：include_ext = ["go", "env"] 必须存在，否则 air 不监听 .env 变更。
最易被忽略的点：多个服务共用同一套 .env 模板但各自路径不同，viper 的 AddConfigPath 写错相对路径，导致配置加载为空——建议所有服务统一用 ./configs，并在 main.go 开头加一行日志打印 viper.AllSettings()，一眼确认配置是否真加载成功。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
