本地跑通 golang 微服务需手动确认 go version ≥1.21、goproxy=https://goproxy.cn,direct，独立进程启动（非 docker compose），go run ./cmd/svc-name，配置用 viper 或 godotenv，日志用 logrus，健康接口为 /health，服务注册 consul 地址必须用 127.0.0.1，中间件用 docker 而 go 服务跑主机进程。
本地跑通 Golang 微服务，不靠 Docker Compose 启动 Go 服务本身，IDE 只负责编辑和调试，真正的运行环境由 go run + 独立进程 + 显式配置构成。
go version 和 GOPROXY 必须手动确认，别信安装器默认值
很多人执行 go version 报 command not found，本质是 PATH 没生效——macOS/Linux 检查 which go，Windows 用 PowerShell 运行 Get-Command go。即使安装器声称“已添加 PATH”，也得重启终端或手动 source ~/.zshrc。
GOPROXY 不设等于卡死：国内必须执行
go env -w GOPROXY=https://goproxy.cn,direct
否则 go mod download 或 go get 会超时。注意不要漏掉 ,direct，否则私有模块拉不下来。
- Go 版本必须 ≥ 1.21（微服务依赖的泛型、
net/http的路由增强、module 稳定性都依赖它） - 旧项目残留
vendor/目录或GO111MODULE=off会导致go mod init静默失败 - 别把项目建在
$GOPATH/src下，go mod 会按旧路径推导 module 名，大概率出错
VS Code / GoLand 启动调试前，先确保 gopls 和 go.tools 能跑起来
gopls 是语言服务器，不是插件装上就完事。它启动失败的三个硬条件：
-
go命令全局可用（which go有输出） - 当前目录有合法
go.mod（go mod init xxx成功生成） - 文件后缀是
.go，且不在vendor/或internal/testdata这类被忽略目录里
VS Code 中按 Cmd+Shift+P（macOS）或 Ctrl+Shift+P（Windows/Linux），输入 Go: Install/Update Tools，全选安装。其中 dlv（调试器）和 gopls 是必装项。
GoLand 用户需在 File → Settings → Go → GOROOT 中手动指定 Go 安装路径（如 /usr/local/go），不能依赖自动探测——尤其当你装了多个 Go 版本时。
go run 启动微服务时，端口、配置、日志必须显式分离
每个服务必须是独立 module，且启动逻辑收口在 cmd/svc-name/main.go。别把业务逻辑写进 main 函数里。
配置加载用 spf13/viper，支持 .env + YAML 双源：
viper.SetConfigName("config")<br>viper.SetConfigType("yaml")<br>viper.AddConfigPath("./configs")<br>_ = viper.ReadInConfig()
但开发阶段更轻量的做法是直接用 github.com/joho/godotenv 加载 .env：
godotenv.Load()<br>port := os.Getenv("PORT") // PORT=8081
日志别用 fmt.Println 打点，至少用 logrus 并设级别：
logrus.SetLevel(logrus.DebugLevel)<br>logrus.WithFields(logrus.Fields{"port": port}).Info("service started")
- 健康接口统一暴露
/health，返回 JSON，不带任何业务逻辑 - 服务间调用用完整 URL：
http.Get("http://localhost:8082/api/orders")，别幻想本地 DNS 自动解析 - 若要用域名（如
order.svc.local），改/etc/hosts，再让服务监听对应Host头，而不是依赖 consul agent
中间件用 Docker，Go 服务用主机进程：这是本地调试不崩溃的前提
Consul、Redis、PostgreSQL 这类有状态组件必须用 Docker 启动，但 Go 微服务本身一定用 go run ./cmd/user-svc 启动——否则断点失效、编译慢、环境变量混乱。
Docker 启动 Consul 时，-client=0.0.0.0 和 -bind=0.0.0.0 缺一不可，否则 Go 客户端连不上（默认只绑 127.0.0.1）；Redis 必须关 protected-mode yes，否则报 NOAUTH Authentication required；PostgreSQL 的 pg_hba.conf 要加 host all all 0.0.0.0/0 md5。
最关键的是：Go 服务注册到 Consul 的地址必须写 127.0.0.1，不是 localhost——后者在某些 DNS 配置下会被解析成 ::1（IPv6），导致服务发现失败。
还有个容易被忽略的点：go.mod 里必须显式 require 所有通信依赖。比如用了 gRPC，就得有：
require (<br> google.golang.org/grpc v1.62.1<br> google.golang.org/protobuf v1.33.0<br>)
否则运行时可能 panic：interface conversion: interface {} is nil, not *xxx.ServiceClient——类型没注册，不是代码写错了，是模块没拉全。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
