consul client 初始化连不上本地 agent，因默认连接 http://127.0.0.1:8500，但 agent 可能未启用 http 接口、监听地址不匹配或 acl 未配置 token；注册服务时 healthcheck 失败常因 ttl 未更新、http 检查 url 不完整、id 重复或 name 含非法字符；watch api 需手动处理 run() 错误并确保 key 为 "services/"；结构体必须显式添加 json tag 以匹配 consul 的下划线命名。
Consul client 初始化为什么连不上本地 agent？
默认配置下 consul.NewClient 会尝试连接 http://127.0.0.1:8500，但 Consul agent 若以 -dev 模式以外方式启动（比如 systemd 或后台服务），可能没开 HTTP 接口，或监听在 127.0.0.1 而非 localhost —— Go 的 DNS 解析有时会让两者行为不一致。
- 先用
curl -v http://127.0.0.1:8500/v1/status/leader确认 agent 确实可访问，别只信consul members命令的本地输出 - 初始化 client 时显式指定地址：
cfg := consul.DefaultConfig() cfg.Address = "127.0.0.1:8500" client, _ := consul.NewClient(cfg)
- 若 Consul 启用了 ACL，
token必须设在 config 中，空 token 不等于“无认证”，而是触发默认策略拒绝
注册 service 时 HealthCheck 失败但没报错？
Consul Go client 默认对 Register 请求做静默重试，HTTP 4xx/5xx 错误可能被吞掉，日志里只看到 nil error，但服务实际没注册成功。
- 检查
ServiceDefinition中的Check字段：如果用了TTL类型，必须配套调用client.Health().UpdateTTL()，否则 30 秒后自动标记为 critical - HTTP 类型健康检查的
HTTP字段必须是完整 URL（如"http://localhost:8080/health"），不是路径；且目标服务需已就绪，Consul 不等你启动完再注册 - 常见漏配：
ID字段重复（同一节点不能有两个相同ID的 service）、Name含空格或特殊字符（虽然不报错，但后续 DNS 查询失败）
用 Watch API 监听 services 变化为什么收不到更新？
consulapi.WatchPlan 的底层依赖 long polling，一旦连接中断或超时，watch 会静默停止，不会自动重连，也不会抛出 error。
- 必须手动检查
plan.Run()的返回值 —— 它是error类型，不是布尔值；nil表示首次成功，非nil很可能是连接断了 - Watch 的
Handler函数里别做耗时操作（比如写 DB、发 HTTP），它运行在单独 goroutine，阻塞会导致下一次 watch 请求卡住 - 注意
serviceswatch 的 key 是"services/"，不是"service/"；少个 s 就永远等不到回调
Go 结构体字段名和 Consul JSON 字段对不上怎么办？
Consul client 底层用 encoding/json 解码响应，但它的 struct tag 默认是 json，而 Consul 文档里字段名常带下划线（如 service_id），Go struct 若按驼峰命名（ServiceID）又没加 tag，就会解码失败，字段为空。
- 所有传给 Consul 的结构体（如
AgentServiceRegistration）和接收响应的结构体，都得补全jsontag，例如：type MyService struct { ID string `json:"id"` Name string `json:"name"` Tags []string `json:"tags"` } - 别依赖
consulapi包里现成的 struct —— 它们只覆盖常用字段，自定义字段（如Metamap）必须自己定义并加 tag - Consul 返回的某些字段（如
Checks数组里的Node字段）在不同接口中类型不一致，强行复用 struct 会导致 panic
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
