Flagship 将功能标志组织到应用程序中。您定义带有变体和目标定位规则的标志,然后在 Cloudflare 的全球网络中评估它们。
Flagship 的功能标志从创建到评估经历三个阶段:
- Configuration(配置) — 在 Cloudflare 仪表板 ↗ 或通过 API 创建标志和目标定位规则。
- 传播 — Flagship 自动在几秒钟内将您的标志配置分布到 Cloudflare 的全球网络中。
- 评估 — 您的 Worker(或 SDK)使用传播的配置在本地评估标志。无需往返中心服务器。
标志更改将在保存后的几秒钟内全球生效。您不需要重新部署您的 Worker 或重新启动您的应用程序。如果仪表板暂时不可用,标志评估将继续使用最后一次传播的配置进行。
应用程序 (App) 是 Flagship 中的顶层组织单元。它将相关的标志组合在一起。
一个应用程序通常映射到单个项目、服务或产品界面。每个 Cloudflare 账户可以拥有多个应用程序。例如,您可以为您的营销网站创建一个应用程序,并为您的 API 后端创建另一个应用程序。
Flag 是一个命名的功能开关。每个 Flag 都有键、一组变体、定向规则以及启用/停用状态。
标志键必须在应用程序内是唯一的。键可以包含字母、数字、连字符和下划线。
当标志被禁用时,无论任何目标定位规则如何,它都会始终返回默认变体。请选择一个对您的应用程序来说是安全的默认变体,以防 Flagship 无法评估该标志。
变体是标志可以返回的可能值。每个标志必须至少有一个变体,并且指定其中一个变体作为默认变体。
Flagship 支持四种变体类型:
| 类型 | 示例 |
|---|---|
| 布尔值 | on: true, off: false |
| 字符串 | v1: "old-checkout", v2: "new-checkout" |
| 数字 | low: 100, high: 1000 |
| JSON | premium: { "tier": "premium", "features": ["analytics", "export"] } |
对于简单的开/关切换,请使用布尔标志。当您需要分发配置值或结构化数据时,请使用字符串、数字或 JSON 标志。JSON 变体可以包含对象或数组。
目标定位规则控制标志对于给定请求返回哪个变体。规则按顺序评估,匹配的第一条规则获胜。如果没有规则匹配,则返回默认变体。
每条规则包含:
- 条件:使用运算符,将评估上下文中的属性与某个值进行比较。
- 可选的percentage rollout(百分比部署):在各变体之间分配流量。
- 匹配规则时要提供的一个variant(变体)。
规则内的条件可以使用 AND/OR 运算符进行分组。
有关运算符和配置选项的完整列表,请参阅目标定位规则和运算符。
评估上下文描述当前用户或请求。它是一个对象,顶层键为属性名称。
每个值可以是字符串、有限数字、布尔值、null、数组或嵌套对象。数组和对象可以递归地包含相同类型的值。
您将上下文作为第三个参数传递给绑定上的评估方法:
const value = await env.FLAGS.getBooleanValue("new-checkout", false, {
userId: "user-42",
profile: { plan: "enterprise" },
tags: ["beta"],
});const value = await env.FLAGS.getBooleanValue("new-checkout", false, {
userId: "user-42",
profile: { plan: "enterprise" },
tags: ["beta"],
});当使用 OpenFeature SDK 时,您通过 OpenFeature 评估上下文对象传递上下文。
Flagship 使用上下文属性来匹配目标定位规则并确定百分比部署的存储桶划分 (bucketing)。一致的上下文(例如相同的 userId)会在每次评估时产生相同的部署结果。
评估上下文是评估的输入,与评估返回的 JSON Flag 变体相互独立。
避免在评估上下文中发送敏感数据。仅包含目标定位规则或部署分桶所需的属性。
在您更改标志后,更新的值最多可能需要 30 秒才能在全球范围内反映出来。在这个传播窗口期,一些评估可能仍会返回先前的标志值。