go mod init前需确认Go≥1.16且GOPATH不影响模块模式，docker-compose要配置网络与服务参数，main.go用viper+env管理配置，调试应优先使用delve连容器而非本地二进制。
用 go mod init 初始化项目前先确认 GOPATH 和 Go 版本
Go 1.11+ 默认启用模块模式，GOPATH 不再影响依赖管理，但旧脚本或 IDE（如某些版本的 Goland）仍可能读取它。执行 go mod init 前务必检查：
– 运行 go version，确保 ≥ 1.16（推荐 1.21+），避免 go.sum 校验失败或 replace 行为异常
– 运行 go env GOPATH，若输出为空或非预期路径，说明模块模式已生效；若仍需兼容老工具，可设为 go env -w GOPATH=$HOME/go，但不要把它加入微服务构建逻辑里
– 切忌在 $GOPATH/src 下新建项目再跑 go mod init，这会导致模块路径与目录结构冲突，报错如 cannot find module providing package
用 docker-compose up 启动本地依赖服务时注意端口与网络隔离
微服务通常依赖 Redis、PostgreSQL、RabbitMQ 等，直接裸装易污染宿主机环境。用 Docker 容器启动更可控，但常见疏漏有：
– 忘记在 docker-compose.yml 中显式声明 network_mode: "bridge" 或自定义网络，导致 Go 服务容器内无法解析 host.docker.internal（macOS/Windows 有效，Linux 需额外配置）
– PostgreSQL 的 POSTGRES_PASSWORD 未设置，镜像会拒绝启动，日志只显示 database system is shut down，实际是认证失败
– Redis 默认绑定 127.0.0.1，Docker 容器内访问不到，必须改配置 bind 0.0.0.0 或用 redis:alpine 镜像默认已适配
– 示例片段：
services:
redis:
image: redis:7-alpine
ports: ["6379:6379"]
command: redis-server --bind 0.0.0.0:6379 --protected-mode no
写 main.go 时别硬编码配置，优先用 viper + .env
微服务启动前要加载数据库地址、服务端口、JWT 密钥等，硬编码或全靠命令行 flag 极难维护。推荐组合：
– 用 viper 读取 .env 文件（开发期）+ config.yaml（测试/预发）+ 环境变量（生产）
– 注意 viper.AutomaticEnv() 会把 _ 转成 .，比如 DB_HOST 对应 viper.GetString("db.host")，别写成 "DB_HOST"
– .env 文件不能提交到 Git，务必加进 .gitignore；但要提供 .env.example，列清必需字段如：
DB_HOST=localhost DB_PORT=5432 REDIS_ADDR=localhost:6379 HTTP_PORT=8081
– 若用
air 热重载，需在 .air.toml 中配置 include_ext = ["go", "env"]，否则改 .env 不触发重启
调试时用 delve 连容器比 dlv exec 本地二进制更贴近真实部署
本地跑 dlv exec ./main 看起来快，但忽略容器网络、挂载路径、权限等关键差异。真正在 Docker 中调试才暴露问题：
– 构建带调试符号的镜像：Dockerfile 中加 go build -gcflags="all=-N -l"
– 启动容器时暴露 dlv 端口：docker run -p 2345:2345 -it your-service-image dlv --headless --listen=:2345 --api-version=2 --accept-multiclient exec ./service
– VS Code 调试配置里 port 改为 2345，host 改为 localhost（不是容器名）
– 常见失败：容器内 dlv 找不到源码路径，需用 --wd /app 指定工作目录，并在 VS Code 的 sourceMap 中映射 "./": "/app/"
