17370845950

Golang服务注册需确保健康检查端点真实可用且被注册中心持续验证，注销须显式处理信号与panic，心跳续租应独立goroutine控制，本地缓存需线程安全并监听变更。

服务注册时必须携带健康检查端点

直接调用注册接口但不提供可被发现的健康检查路径，会导致注册中心（如 Consul、Etcd 或 Nacos）误判服务为“不健康”而自动剔除。Golang 服务注册不是一次 HTTP POST 就完事，关键在于让注册中心能持续验证服务存活。

• 注册时 service.Check.HTTP 必须指向一个真实响应 200 的 endpoint（例如 /health），不能是空字符串或不存在的路径
• 该 endpoint 应返回轻量 JSON（如 {"status":"UP"}），避免耗时逻辑或数据库查询
• Consul 要求 Interval 字段（如 "10s"），且必须是合法 duration 字符串；写成 "10" 或 10 会静默失败
• 使用 consulapi 客户端时，Register() 成功只表示请求发出，不代表注册中心已接受——需配合日志或后续 Health().ServiceNodes() 主动验证

服务注销必须显式调用 Deregister 并处理 panic 风险

进程退出前不注销，注册中心会保留过期服务记录，导致客户端路由到已下线实例。Golang 的 defer 看似合适，但若主 goroutine 因 panic 退出，defer 不一定执行——必须双重保障。

• 在 os.Interrupt 和 syscall.SIGTERM 信号处理中调用注销逻辑，而非仅依赖 defer
• 注销前检查 agent.ServiceDefinition 是否已注册（可通过本地缓存 flag 或注册时返回的 ID 判断），避免重复 deregister 报错
• Consul 的 Deregister() 在连接中断时可能 panic，需用 recover() 包裹或提前设置 cfg.HttpClient.Timeout = 3 * time.Second
• 注销失败不应阻塞进程退出，但应打 error 日志，方便后续人工核对注册中心状态

心跳续租需独立 goroutine + context 控制生命周期

部分注册中心（如 Etcd）不支持内置 TTL 续租，需服务自身定时刷新；即使支持（如 Consul），网络抖动也可能导致心跳丢失，主动续租更可靠。

• 启动一个单独 goroutine 运行 time.Ticker，每 ttl/2（如 15s）调用一次 PassTTL 或更新 etcd key 的 lease
• 必须用 context.WithCancel 关联主服务生命周期，收到退出信号后调用 cancel() 停止 ticker，防止 goroutine 泄漏
• PassTTL 接口（如 Consul 的 /v1/agent/check/pass/）要求 check ID 与注册时完全一致，大小写和下划线都不能错
• 不要在 http handler 中做续租——高并发下易触发限流或超时，应与业务逻辑彻底隔离

本地服务列表缓存需监听变更并及时刷新

客户端直连注册中心拉取服务列表虽可行，但频繁轮询浪费资源；全量缓存又无法感知实时上下线。折中方案是监听注册中心事件，按需更新本地 map。

• 使用 Consul 的 Blocking Queries（带 WaitIndex 参数）长轮询 /v1/health/service/{name}，比固定间隔 polling 更高效
• 解析响应时注意 Node.Service.Address 可能为空，此时应 fallback 到 Node.Address，否则服务发现失败
• 缓存结构建议用 map[string][]*ServiceInstance（key 为 service name），更新时用 sync.RWMutex 保护读写，避免并发 panic
• 首次拉取失败不能跳过——应阻塞初始化直到获取到至少一个实例，否则服务启动即不可用

func (r *Registry) watchService(name string, ctx context.Context) {
    var lastIndex uint64
    for {
        select {
        case <-ctx.Done():
            return
        default:
        }
        opts := &consulapi.QueryOptions{WaitTime: 5 * time.Minute, WaitIndex: lastIndex}
        services, meta, err := r.client.Health().Service(name, "", true, opts)
        if err != nil {
            log.Printf("watch service %s failed: %v", name, err)
            time.Sleep(1 * time.Second)
            continue
        }
        lastIndex = meta.LastIndex
        r.updateLocalCache(name, services)
    }
}

注册中心不是“设好就忘”的黑盒，每个环节都存在隐性失败路径：健康检查路径拼错、注销时网络超时、心跳 goroutine 没被 cancel、缓存没加锁……这些细节不处理，动态上下线就会变成概率性故障。