client.agent().services() 返回全部注册服务的完整映射，而非目标服务的健康实例列表；服务发现必须调用 client.health().service("service-name", "", true, opts) 并传入正确服务名、设置 passingonly: true，提取 service.address（或 fallback 到 node.address）与 service.port 拼接为可用地址。
为什么 client.Agent().Services() 不能直接用于服务发现
它返回的是 Consul 中所有已注册服务的完整映射，不是当前请求要调用的目标服务列表。真正做服务发现时，必须用 client.Health().Service()，传入目标服务名（如 "user-service"），才能拿到健康实例列表。
常见错误包括：
- 服务名写错：大小写敏感、带空格、多出前缀或后缀
- 没加
passingOnly := true参数，导致返回不健康节点 - 忽略
ServiceNode.Service.Port，误用 Gin 启动端口（r.Run(":8080")）代替 Consul 注册端口 -
ServiceEntry.Service.Address为空时没 fallback 到Node.Address，硬编码"127.0.0.1"导致跨主机调用失败
如何从 Consul 动态构建反向代理地址
动态路由中间件的核心是把请求路径映射到 Consul 中实时获取的服务地址。关键点不在“怎么转发”，而在“怎么取对地址”：
Skill Weave Chains — 技能链路由引擎
下载
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
- 调用
client.Health().Service("order-service", "", true, &consulapi.QueryOptions{AllowStale: false})获取健康节点 - 遍历返回的
[]*consulapi.ServiceEntry，对每个节点提取：node.Service.Address（非空则用）、否则用node.Node.Address；端口统一取node.Service.Port - 拼接为
http://<addr>:<port></port></addr>，再传给httputil.NewSingleHostReverseProxy() - 别在中间件里每次请求都查 Consul——应缓存结果并配合 goroutine 定时刷新（比如 5 秒轮询），避免性能瓶颈
Gin 中间件里怎么安全做负载均衡
Consul 返回的是一个健康节点切片，但中间件本身不负责选节点，得你自己实现简单策略。轮询是最稳妥的起点：
- 用原子计数器（
atomic.AddUint64(&counter, 1)）做索引，取模节点数，避免锁开销 - 节点列表为空时必须返回 503，不能 panic 或静默失败
- 代理失败（如 connection refused）后，应临时剔除该节点（加到本地黑名单），并在下一轮刷新时恢复——Consul 自身不保证瞬时一致性
- 别复用
http.Transport的默认配置：设置MaxIdleConnsPerHost = 100、IdleConnTimeout = 30 * time.Second，否则长连接耗尽会拖垮整个网关
注册端口和监听端口不一致的典型表现
现象是下游服务能从 Consul 查到节点，但 curl http://xxx 直接报 connection refused。根本原因往往是：
- Gin 启动写的是
r.Run(":8080")，但 Consul 注册时填了Port: 8081 - 注册
Address填了"0.0.0.0"或"localhost"，而容器/K8s 环境中实际可路由 IP 是eth0绑定地址 - 没用
net.ResolveTCPAddr("tcp", ":8080")提前解析监听地址，导致注册 IP 和真实监听 IP 不一致
最稳妥的做法：启动 Gin 前先调用 net.Listen("tcp", ":8080")，从返回的 Listener.Addr() 中提取端口和 IP，再同时喂给 http.Serve() 和 Consul 注册结构体。
