Cloudflare Flagship Rust SDK：HTTP、本地评估与缓存怎么选

先确认运行环境和令牌权限

Cloudflare 在 2026 年 11 月 10 日公告 Flagship 官方 Rust SDK，面向异步 Rust 服务，通过 OpenFeature 接入。OpenFeature 提供统一的功能开关接口，让应用按开关值决定某项行为是否启用。当前 Rust 文档要求 Rust 1.88 或更高版本及 Tokio runtime，并明确不支持 Cloudflare Workers binding。

官方安装命令是 cargo add cloudflare-flagship。配置使用 Flagship app ID、Cloudflare account ID 和 API token；默认 HTTP 评估要求令牌具备 Flagship Evaluate 或 Flagship App Evaluate 权限。app_id 与 account_id 配合使用，本地评估始终需要 account_id。

本文于 2026 年 11 月 12 日核对公告与 SDK 文档，文档页面标注日期为 11 月 4 日。两份资料没有给出完整套餐、价格、地区和逐账号资格，不能从 SDK 已发布推断账号必然可用或免费；实际接入仍须核对自己的 Flagship 服务权限。

HTTP 评估：注册 provider，并处理 Result

用 FlagshipClientOptions::builder() 设置 app_id、account_id、auth_token 并 build()，再创建 FlagshipServerProvider，将它注册到 OpenFeature。随后创建 client，提供 EvaluationContext 和 targeting key，再调用 get_bool_value 等方法。targeting key 用于识别评估对象；示例中的 user-42 和 new-checkout 只是官方演示标识，需要替换成自己的开关与授权上下文。

SDK 支持布尔、字符串、浮点、整数和结构体等 OpenFeature 服务端类型。Rust OpenFeature SDK 不会把默认值传给 provider，评估方法返回 Result；应用需要处理错误，再选择符合业务要求的回退值。例如官方示例的 unwrap_or(false) 在出错时返回 false，并不证明远程开关的实际值为 false。

禁用的开关会返回 Flagship 提供的值，并带有 Disabled reason；它与网络错误不同。需要分清实际值、变体、原因、元数据或错误码时，使用 get_*_details 方法，避免只记录一个布尔结果而丢失排错信息。

本地评估：先下载定义，再管理刷新生命周期

开启 local_evaluation(true) 后，provider 下载 app 的开关定义，在进程内完成评估，不会为每次评估发起网络请求。下载定义要求 Flagship Read 或 Flagship App Read 权限；不能因为 HTTP 评估令牌可用，就假定它也能下载定义。本地评估不会出现在 Flagship analytics 中，缺少这些记录不能直接解释为没有使用。

本地模式需要在注册 provider 之前显式调用 initialize_provider()，不再使用时调用 shutdown_provider()。Rust OpenFeature SDK 不会替你调用这两个方法；首次定义下载失败时，初始化会返回错误，应在服务接入流程中处理，而不是把启动成功写成必然结果。

定义会在后台刷新，refresh_interval 默认 30 秒。后台刷新失败时，provider 继续使用上次下载的定义，并报告 STALE 状态；通过 last_refresh_error() 查看原因。此时仍能返回值不代表已拿到最新配置，也不证明远程开关没有变化。

这里的本地评估不是 Wrangler 开发环境中的本地 flag store。后者涉及显式 pull 和共享数据目录，已有独立说明：https://puppyip.com/resources/cloudflare-flagship-local-defaults-dev-store-guide 。Rust 下载定义的运行方式，不能直接套用 CLI store 的排查步骤。

响应缓存：适合重复请求，接受 TTL 内的旧值

响应缓存默认关闭。把 cache_ttl 设为大于零的时长后，provider 可以缓存相同开关和上下文的评估结果，减少重复远程请求。cache_max_entries 默认 1000，超过容量使用 LRU 淘汰；官方示例的 30 秒 TTL 是示例设置，不是默认开启的缓存时间。

缓存键包含开关 key、开关类型和完整评估上下文，不同上下文不会共享同一缓存值。命中缓存的 reason 为 Cached；禁用开关、错误和类型不匹配不会被缓存。Flagship 中的变更要等该条目的 TTL 到期后才会反映到后续远程取值，不能承诺改动立即生效。

本地评估不能与响应缓存组合使用。要避免逐次远程调用、并能管理定义刷新时，考虑本地评估；只是同一上下文反复查询、并能接受明确 TTL 时，考虑响应缓存。对最新远程结果有要求时保留默认 HTTP 路径，同时按业务要求处理失败回退与延迟。

网络排错：区分上下文、单次超时与重试

只有字符串、有限数值、布尔值或日期时间的上下文通过 GET 查询参数发送；包含结构化值时使用 POST JSON 请求体。不要把上下文参数当作秘密存储：按实际数据策略选择必要属性，并核对网络日志的可见范围。值不受支持或上下文超过 Flagship 限制时，SDK 返回 INVALID_CONTEXT，不发送 HTTP 请求；此时应先查输入。

timeout 默认是每次尝试 5 秒，retries 默认 1 次，针对网络错误、超时及 HTTP 408、425、429、5xx 重试；重试次数最多 10，retry_delay 默认 1 秒、最多 30 秒。带重试和等待的完整调用不能按单次 5 秒计算，应与应用的整体等待预算配合。文档也提供 disable_timeout()，这不等于建议所有服务移除超时。

auth_token 为请求添加 Bearer 认证。static_headers 中显式设置的 Authorization 会覆盖 auth_token，异步 header_factory 生成的值又会覆盖静态请求头与 auth_token。遇到身份错误时，应核对实际请求头来源和对应权限，不能只检查最初填入的 token 选项。

默认 rustls feature 使用 Rustls 处理 TLS；需要平台 TLS 库时，官方命令为 cargo add cloudflare-flagship --no-default-features --features native-tls。选择应匹配实际运行环境。本文没有安装依赖、访问账号或执行真实评估，不能据此宣称某个平台的连通性已经验证。

按模式逐项验收，再扩大使用范围

先在获授权的测试范围内确认运行环境、app/account ID、开关类型和最小权限，使用一个已知 targeting key 核对结果与 reason，再检查失败时的 Result 处理。功能开关的回退值应由业务决定；不要把官方 false 示例机械套到每个业务操作。

选择本地评估时，分别检查首次下载、后台刷新、STALE 诊断和关闭流程；选择缓存时，分别检查命中原因、上下文隔离和 TTL 后的更新。把成功返回、读到新定义、日志或 analytics 中出现记录作为不同观察，不用其中一项代替其他验收。

保留实际 SDK 版本和所用文档日期，再按应用需求调整超时、重试或刷新间隔。SDK 发布、代码示例及文档资格都不代表实际部署、账号开通或效果；代理与网络配置也不能替代 Cloudflare 的服务权限、价格和规则。