应使用 Gin + Viper + Go Modules 搭建微服务骨架，禁用已归档的 go-micro；Nacos 注册需显式带 /nacos 路径、开启鉴权配置；Kitex/gRPC 客户端与服务端均须添加 WithInsecure() 禁用 TLS；HTTP 请求体为空需检查结构体字段大小写及 json tag 和 api 文件中 requestBody 声明。
直接用 Gin + Viper + Go Modules 搭，别碰过时的 go-micro
现在拉 github.com/micro/go-micro 会失败，不是你网络问题，是这个库早在 2023 年就归档了，v2/v3 分支全删，go get 直接报错；就算侥幸下载成功，也会因依赖已废弃的 golang/protobuf 导致编译失败。
- 别试
replace指向某个 fork 仓库——这些 fork 缺乏测试、不兼容 Go Modules 校验规则，CI 环境里静默失败是常态 - 别降级 Go 版本去迁就——Go 1.16+ 的
embed和io/fs已成标配，倒退得不偿失 - 真实项目中，这类错误往往源于交接老项目时没清理
go.mod里残留的 micro 依赖项
正确姿势：从零开始用 Gin（HTTP 层）、Viper（配置）、go mod init（模块隔离）搭骨架，再按需加 grpc-go 或 kitex 做内部通信。
服务注册失败？先查 Nacos 地址格式和鉴权开关
register to nacos failed 这类日志背后，90% 不是网络不通，而是配置对不上。Nacos 2.x 默认开启鉴权，而 nacos.NewDefaultNacosConfig() 不带账号密码，请求直接被 403 拦截。
-
Nacos地址必须显式带/nacos前缀，比如http://127.0.0.1:8848/nacos；kitex 默认不加，写成http://127.0.0.1:8848就注册失败 - 服务名只允许小写字母、数字、短横线，含下划线（如
user_rpc）会被拒绝注册 - 启动时加
-v参数看真实 HTTP 状态码：kitex -service user-rpc -I idl -o ./pkg idl/user.thrift -v
真正麻烦的从来不是“怎么连上”，而是“连上之后，当 Nacos 重启、网络抖动、实例闪退时，你的重试逻辑有没有覆盖所有超时分支”。
立即学习“go语言免费学习笔记（深入）”；
RPC 客户端调用超时？大概率是 TLS 没关干净
context deadline exceeded 看似是超时设置太短，其实是底层 gRPC 连接根本没建起来。go-zero、kitex 默认启用 TLS，但本地开发环境通常没配证书。
- 客户端初始化必须显式禁用 TLS：
client := NewUserClient("user-rpc", etcdConf, client.WithNonBlock(), client.WithInsecure()) - 服务端
server.NewServer也得加server.WithInsecure()，否则两端握手失败 - 别用
localhost当注册中心地址——Docker 容器里解析不了，换成宿主机 IP 或host.docker.internal - 用
etcdctl get --prefix ""确认 etcd 里真有对应服务节点，路径通常是/go-zero/或/kitex/开头
很多团队卡在这一步好几天，其实就差一行 WithInsecure()。
HTTP 接口收不到 JSON body？检查结构体字段和 API 定义是否匹配
用 goctl api go 生成的 HTTP handler，如果请求体始终是空结构体，不是框架 bug，而是两个地方没对齐：
-
AddReq结构体字段必须首字母大写 + 显式jsontag，比如Name string `json:"name"`；小写字段不会被反序列化 -
.api文件里路由定义必须显式声明requestBody，写成post /user/add (AddReq)，漏掉括号里的AddReq就不会注入绑定逻辑 - 生成后检查 handler 文件里是否有
c.ShouldBind(&req)这行；没有说明goctl版本太低（v1.5+ 才默认加）
微服务脚手架最脆弱的地方，往往不在架构图里，而在第一行 json.Unmarshal 调用失败却没打日志的那一刻。
