go mod init 模块路径必须全局唯一且与 import 路径一致，不可用短名如 user-svc，而应使用域名前缀如 example.com/user-svc，否则多服务协作时 import 冲突；初始化须在项目根目录执行，避免 gopath 干扰。
go mod init 时模块路径不能照抄项目名
微服务模块路径不是随便起的，它直接影响 import 路径和依赖解析。用 go mod init user-svc 这种短名会导致其他服务 import 时写 import "user-svc/internal/service" —— 这在多服务协作中必然冲突，因为所有服务都可能叫 user-svc。
正确做法是用域名前缀，比如公司官网是 example.com，就初始化为 go mod init example.com/user-svc。这样别人引用你服务的包时，路径明确且全局唯一：import "example.com/user-svc/internal/service"。
- 别在
$GOPATH/src下初始化，否则 go mod 会报cannot find module providing package - 如果已有旧项目迁移，先删掉
vendor/和go.sum，再go mod init，避免残留影响 -
go mod tidy后检查go.sum是否干净——若出现大量// indirect且无对应 require，说明有未声明的隐式依赖，得补上或删掉不用的 import
本地调试时别把 Go 服务也塞进 docker-compose
很多团队图省事，把 user-svc 的 build 步骤也写进 docker-compose.yml，结果改一行代码就要 rebuild 镜像、重启容器、等日志刷出来——根本没法高效调试。
真正高效的本地流是：Docker 只跑中间件（PostgreSQL、Redis、Consul），Go 服务用主机进程跑，靠 air 或 dlv 热重载或断点调试。
- Consul 必须加
-client=0.0.0.0 -bind=0.0.0.0，否则 Go 客户端连不上（默认只监听127.0.0.1） - PostgreSQL 要在
pg_hba.conf加host all all 0.0.0.0/0 md5，不然sql.Open("postgres", ...)直接超时 - Go 服务里注册中心地址写
http://127.0.0.1:8500，别写localhost（Docker 容器内localhost指自己）
proto 生成代码前必须确认 protoc 插件版本对齐
goctl rpc proto 或 protoc --go-grpc_out=. 报错，十有八九不是语法问题，而是 protoc-gen-go 和 protoc-gen-go-grpc 版本跟项目里用的 gRPC 库不匹配。
比如项目 go.mod 里是 google.golang.org/grpc v1.63.0，但你装的是 @latest 插件，新插件已移除某些字段（如 XXX_unrecognized），导致生成的 struct 编译失败。
- 查清项目依赖的 gRPC 版本：
grep "google.golang.org/grpc" go.mod - 对应安装插件：
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.63.0 - 验证是否可用：
protoc-gen-go-grpc --version输出应含v1.63.0，而非dev或空 - Windows 用户注意：下载的
protoc.exe右键“属性”→勾选“解除锁定”，否则权限被系统拦截
多阶段 Dockerfile 里 CGO_ENABLED=0 不是可选项
Go 编译产物默认静态链接，但一旦用了 cgo（比如 net 包调 DNS、sqlite 驱动），镜像运行时就会依赖宿主机的 libc。用 alpine 基础镜像一跑就报 standard_init_linux.go:228: exec user process caused: no such file or directory —— 实际是 libc 找不到。
所以构建阶段必须显式关掉 cgo：CGO_ENABLED=0 GOOS=linux go build -a -o main .。这个 -a 参数现在虽已非必需，但保留更稳妥。
- 别用
FROM golang:latest，固定版本如golang:1.22-alpine，避免 CI 环境突然升级导致构建失败 - 运行镜像用
scratch最小，但需确保你的代码没调任何 C 库；若用了zlib或openssl，改用alpine:latest并apk add ca-certificates -
Dockerfile里COPY --from=builder要写绝对路径，比如/app/main，别写./main，否则 copy 失败静默忽略
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
