优先选 go-feature-flag（自托管/多语言/规则丰富）或 unleash-client-go（云服务集成/策略成熟），若仅需少数内部开关则用 atomic.Bool；二者均要求 flag key 全小写连字符、严格匹配 YAML 结构，且必须传入合法上下文实例才能正确评估。
用 go-feature-flag 还是 unleash-client-go？看这三点选准
别纠结 API 漂亮不漂亮，先看你的灰度场景是否需要「用户上下文感知」和「规则动态生效」。如果只是几个内部开关（比如 enableMetrics、isDebugMode），atomic.Bool 就够了；但凡涉及按用户 ID、地域、套餐等级分流，就得上带规则引擎的 SDK。
常见错误现象：unleash.IsEnabled("search-v2", ctx) 传了空 ctx 或没填 user.Key，结果永远返回 false，而你还在查 YAML 配置有没有写错；go-feature-flag 里把 flag key 写成 "searchV2"（驼峰），但 YAML 里是 search-v2，评估永远 fallback 到默认值。
-
go-feature-flag更适合自托管、要统一管控多语言客户端的团队，它通过 Relay Proxy 提供 OpenFeature 标准接口，支持 S3/Kafka 数据导出，配置全靠 YAML + 文件/HTTP/GitHub retriever -
unleash-client-gov4 要求 Go 1.20+，初始化时默认同步拉取 toggles，若网络不通会卡住几秒——必须用 goroutine 异步加载，并配好fallback值 - 两者都要求：flag key 全小写 + 连字符（
new-payment-flow），嵌套结构严格匹配 YAML（features.payment_v2对应features: { payment_v2: true }）
ffclient.BoolVariation 为什么总返回 false？检查这三个地方
ffclient.BoolVariation 不是“读配置”，而是“做一次实时评估”——它的返回值由用户标识、规则、当前时间三者共同决定。返回 false 很可能不是开关关了，而是评估失败了。
常见错误现象：在循环里反复调用 ffcontext.NewEvaluationContext("uid-123")，导致 GC 压力飙升；或者传了字符串 ID 却漏掉 ffcontext.Context 类型，SDK 直接走兜底逻辑。
立即学习“go语言免费学习笔记（深入）”；
- 第一个参数是 flag key，大小写敏感，且必须和 YAML 中定义的完全一致（
test-flag≠testFlag） - 第二个参数必须是
ffcontext.Context实例，不能是字符串或 map；建议提前构造好并复用，或用ffcontext.NewEvaluationContextWithUserKey("uid-123")简化 - 第三个参数是 SDK 层 fallback 值，仅在初始化失败、网络超时、key 不存在时生效，**不参与任何规则计算**；业务层必须检查
err != nil后主动降级
自己手写 atomic.Bool 开关，这些坑千万别踩
如果你只控制两三个核心开关（比如支付链路开关、搜索新算法开关），手写比引入 SDK 更轻量、更可控。但 map[string]bool + sync.Mutex 是典型反模式——写少读多场景下，它带来锁竞争和 GC 开销，还容易 panic。
常见错误现象：声明 var features map[string]bool，然后在多个 goroutine 里直接 features["payment"] = true，运行时 panic: concurrent map read and map write。
- 每个开关声明独立
var enableNewSearch atomic.Bool，不要塞进一个 map - 写操作统一用
enableNewSearch.Store(true)，读用enableNewSearch.Load() - HTTP handler 中禁止闭包捕获变量（如
func() { return enableNewSearch.Load() }），goroutine 并发访问可能看到陈旧值；所有路径必须走同一.Load()调用 - 环境变量开关别在
init()里硬编码解析，改了变量重启也不生效；要用os.Getenv每次读取，且只认"true"/"false"，别用strconv.ParseBool
YAML 配置加载失败？路径、编码、结构三处最容易卡住
go-feature-flag 的 file.Retriever 看似简单，但本地开发时 80% 的报错都出在这三处：路径解析错、BOM 头干扰、YAML 结构不合法。
常见错误现象：启动时报 invalid character '\ufeff' looking for beginning of value，其实是 Windows 记事本保存的 UTF-8 with BOM；或者 YAML 里写了数组形式的 flags，但 go-feature-flag 要求顶层必须是 map。
- 路径用绝对路径最稳，或用
filepath.Abs("flag-config.goff.yaml")动态拼接，避免依赖当前工作目录 - YAML 文件必须是 UTF-8 编码（无 BOM），推荐用 VS Code 或 Vim 编辑，保存时选 “UTF-8” 而非 “UTF-8 with BOM”
- 顶层必须是 key-value map，不能以
-开头的 list；字段名大小写敏感（defaultRule≠defaultrule），percentage下的 key 必须和variations定义完全一致
