Consul KV做特性开关需显式配置超时与重试、封装带熔断退避的HTTP客户端、避免并发覆盖、统一解析布尔开关值、安全处理nil响应、采用long-polling+定时轮询缓存、使用sync.Map或atomic.Value、广播变更事件确保业务实时感知。
Consul KV客户端初始化必须显式设置超时与重试
直接用 consul.NewClient 默认配置连接 Consul，在网络抖动或服务启停时极易出现 rpc error: code = Unavailable desc = connection refused 或长时间阻塞，根本不是“连不上”，而是默认的 http.Client 没设 Timeout 和 Transport 重试逻辑。实际部署中，你得自己封装一层带熔断和退避的 client。
- 必须手动创建
http.Client，设置Timeout（建议 ≤ 3s）、MaxIdleConns和MaxIdleConnsPerHost - Consul 官方 SDK 不内置重试，需在读写
kv.Get/kv.Put外层加带指数退避的 retry（例如用backoff.Retry） - 避免复用全局
*api.Client实例做并发写 ——kv.Put是非原子的，高并发下可能覆盖彼此；应按 key 粒度加 sync.Mutex 或用 etcd-style 的 CAS（即用kv.SetOptions{Flags: ...}+kv.Get校验）
特性开关值必须统一解析为布尔类型，且容忍空值和非法字符串
运维同学往 Consul KV 里填 feature.payments.enabled 的时候，可能写成 "true"、"1"、"on"，甚至误填 "yes" 或留空。Go 里直接用 strconv.ParseBool 会 panic 或返回 false，导致开关“静默失效”。
- 推荐封装一个
ParseFeatureFlag(string) bool函数，明确支持"true"/"false"、"1"/"0"、"on"/"off"，其余一律视为false - 如果 key 在 Consul 中不存在，
kv.Get返回nil, nil，不能直接解引用；要先判pair == nil || pair.Value == nil - 避免把开关值存在嵌套 JSON 里（比如
{"enabled": true, "percent": 20}）—— 增加序列化开销，且单个开关变更要整条更新，丧失原子性
本地缓存需区分 long-polling 和定时刷新两种模式
每次请求都走 Consul HTTP API，QPS 上去后 Consul server 很快吃紧，而且延迟不可控。但全靠内存 cache 又无法实时响应开关变更。折中方案是用 long-polling（Consul 支持 ?index=xxx）监听变更， fallback 到定时轮询。
- 首次加载用
kv.Get获取当前值 +pair.ModifyIndex，后续用kv.Get(&api.QueryOptions{WaitTime: 5 * time.Second, MinQueryIndex: lastIndex})长轮询 - 若 long-polling 超时或出错（如 Consul 重启），降级为每 30s 定时
kv.Get，并重置 index - 缓存结构别用
map[string]bool—— 并发读写不安全；改用sync.Map，或更稳妥地用atomic.Value存整个开关配置 struct
开关变更事件需要通知业务逻辑，而非只更新内存变量
单纯把新值写进本地 map，下游业务代码并不知道开关变了。比如支付开关关闭后，订单服务仍可能正在处理旧请求，直到下次 reload 才生效 —— 这不是“动态开关”，只是“懒加载”。
- 定义一个
FeatureChangedEvent结构体，含Key string、OldValue bool、NewValue bool - 用
chan FeatureChangedEvent或publish/subscribe模式广播变更；关键路径（如支付入口）注册 listener，收到payments.enabled → false后立即拒绝新请求 - 注意 event channel 的 buffer size 和消费速度 —— 若 Consul 频繁变更多个开关，未及时消费会导致 goroutine leak 或丢事件
Consul KV 做特性开关，真正难的不是读写 key，而是怎么让变更“可感知、可追溯、不丢不乱”。index 同步、event 分发、缓存一致性这三块，漏掉任何一环，线上就容易出现“明明关了开关，流量还在走”的情况。
