Unleash Python SDK 初始化必须显式传入带协议端口的 url 和合规 app_name，否则静默失败导致 is_enabled() 恒返 False；需手动 fetch_toggles() 或启用自动轮询；context 必须显式传入匹配策略的字段；多进程需独立初始化 client。
Unleash Python SDK 初始化时 url 和 app_name 必须显式传入
不填或填错 url 会导致初始化静默失败，SDK 不报错但后续所有 is_enabled() 调用都返回 False —— 这是线上最常被忽略的“假阴性”问题。
原因在于 Unleash Python SDK（unleash-client-python）默认使用内存策略，若初始化失败，它不会 fallback 到降级逻辑，而是直接停用所有开关。
-
url必须带协议和端口，例如"https://unleash.example.com:443/api"；写成"unleash.example.com"或漏掉/api会 404 -
app_name不能含空格或特殊字符，否则服务端拒绝注册，SDK 日志里只显示 “registration failed”，无具体错误码 - 建议在初始化后立刻调用
client.is_enabled("test-feature")并检查返回值，别等业务逻辑跑通才验证
Python 中用 UnleashClient 做特性开关，必须手动调用 client.fetch_toggles() 或启用自动轮询
SDK 默认不自动拉取最新开关配置，首次初始化后拿到的是内置缓存（甚至可能是空的），不是服务端当前状态。
常见现象：你在 Unleash 控制台打开了某个开关，Python 服务却始终返回 False，重启服务才生效 —— 就是因为没触发刷新。
立即学习“Python免费学习笔记（深入）”；
- 启用自动轮询：初始化时传
refresh_interval=30（单位秒），但注意这会增加 HTTP 请求量，生产环境建议 ≥60 - 手动刷新：在关键路径（如定时任务、管理接口）中调用
client.fetch_toggles()，它会阻塞直到完成，适合低频主动更新场景 - 不建议依赖
metrics_interval或disable_metrics来控制刷新节奏，它们只影响上报，不影响开关同步
is_enabled() 的 context 参数不是可选的“锦上添花”，而是策略匹配的关键输入
很多同学以为 is_enabled("feature-x") 就够了，结果基于用户 ID 或租户做分流的策略永远不命中 —— 因为默认 context 是空字典，所有基于 userId、environment、remoteAddress 的激活策略都会跳过。
Unleash 的策略匹配完全依赖 context 字段，SDK 不会自动注入请求上下文。
- 必须显式构造 context：例如
client.is_enabled("tenant-override", context={"userId": "abc123", "environment": "prod"}) -
userId字段名严格匹配（不能写成user_id），且值应为字符串，传整数会被忽略 - 如果用了自定义策略，确保 context 中包含该策略声明的所有 required 字段，缺一个就回退到默认规则（通常是
False）
Python 应用热重载或 fork 后，UnleashClient 实例不能复用
Gunicorn/Uvicorn 多 worker 模式下，若在模块顶层创建单例 client，fork 后多个进程会共享同一套内部线程和连接池，导致 fetch_toggles() 冲突、缓存错乱、HTTP 连接泄漏。
典型症状：部分 worker 返回旧开关状态，日志里出现 "Failed to refresh toggles: Connection pool is full" 或 "RuntimeError: cannot schedule new futures after shutdown"。
- 每个 worker 进程必须独立初始化 client，推荐在应用启动入口（如 FastAPI 的
startupevent）中创建 - 避免在
if __name__ == "__main__":外定义全局 client 实例 - 若用 Celery，需在每个 task 执行前检查 client 是否已初始化，或改用 per-task 初始化 + 缓存复用（注意线程安全）
