Cloudflare Flagship 支持结构化上下文:全栈灰度发布该如何迁移

从嵌套字段到稳定分桶,梳理 Flagship 新能力的适用边界,并给出跨端数据契约、可信输入与迁移测试的落地思路。

一次上下文升级,为什么值得全栈团队关注

2026 年 10 月 23 日,Cloudflare 宣布 Flagship 的评估上下文支持嵌套对象、数组和 null。应用可以直接传入用户资料与标签集合,再按内部属性定向投放功能,不必先把业务数据压平成字符串键值对。这项能力覆盖 Workers binding、接收 JSON 请求体的评估接口,以及从 0.6.0 起的 TypeScript、Python、Go OpenFeature SDK。官方更新

对同时维护网页、边缘接口和后端服务的团队,这个变化提供了一个整理发布逻辑的机会。下文先说明已确认的行为,再给出工程判断;示例是设计说明,并非生产环境验证结果。

官方行为:结构可以保留,语义仍须读清

嵌套属性与数组成员是两种操作

例如,一个团队希望让专业版账户中的预览用户尝试新版工作台,可以构造如下上下文。这里假设 env.FLAGS 已完成 binding 配置:

const context = {
  targetingKey: accountUser.id,
  account: { id: account.id, tier: "pro" },
  cohorts: ["preview", "dashboard-v2"],
};

const enabled = await env.FLAGS.getBooleanValue(
  "dashboard-refresh",
  false,
  context,
);

规则可以读取 account.tier,并用 cohorts has "preview" 判断成员关系。需要区分:in 的数组在规则一侧,检查某个标量是否属于候选集合;has 的数组在上下文一侧,检查集合是否包含指定标量。把标签数组当作字符串使用 contains,会偏离文档规定的类型语义。操作符说明

点分路径最多包含五段;如果顶层恰好存在名为 "account.tier" 的键,它优先于嵌套路径解析。规则还按顺序求值,先匹配者生效。因此,字段形状和规则顺序都影响结果,不能只看某一条条件是否写对。定向规则说明

传输方式和空值不是实现细节

直接调用 REST 接口时,结构化上下文应放入 POST 的 JSON 请求体。GET 查询参数中的 JSON 文本仍然是字符串,不会自动变成对象;无效上下文会返回 400。SDK 会在需要传输结构化上下文时自动采用 POST。评估 API;SDK 上下文支持

文档还明确区分缺失和空值:缺失属性不会匹配任何条件,包括否定操作符;null 属性只匹配 not_equals 和 not_in 条件。迁移时若把“没有提供字段”统一改成“显式空值”,某些否定规则的结果就可能变化,不能把这种替换视为纯格式调整。操作符的上下文行为

工程分析:共享数据契约,比共享一段判断更重要

在可信边界组装最小上下文

以下是工程建议。可以由服务端维护一个独立的上下文构造器,只输出发布规则需要的账户等级、稳定标识和试用分组。不要直接把完整用户对象交给评估服务:资料字段会增加隐私暴露面,也会让无关的业务模型变动波及发布逻辑。

前端、服务端和后台任务最好遵守同一份字段约定,明确字段类型、来源、是否可缺失,以及更新时机。尤其要区分用户级标签和账户级标签,否则同一个组织的不同成员可能看到不一致的入口。结构化数据减少了人工扁平化,却没有替团队定义领域含义。

对付费等级、组织身份等字段,应从经过认证的服务端数据生成,不能接受浏览器随意提交的值。功能开关适合控制体验发布,但不能替代接口鉴权。即使按钮被隐藏,敏感操作仍应独立检查权限。

把一次页面体验绑定到同一份决策

服务端渲染页面时,可以先完成评估,再将页面所需的最小结果传给前端,而不是让浏览器用另一份用户资料立即重新推导。这样更容易排查首屏和交互状态不同的问题。需要客户端重新评估的场景,则应约定账户切换、登录状态变化和上下文刷新的时点。

这不是本次公告承诺的自动一致性能力,而是应用需要落实的协调策略。特别是在多语言服务中,类型检查通过并不代表数据含义一致:一个服务把等级写成枚举名,另一个写成显示名称,同一条规则就可能得到不同结果。

给字段变化设置明确的兼容窗口

上下文同样需要版本管理。若准备把 account.tier 改成另一条路径,先让新旧客户端在过渡期都能工作,再切换规则,最后删除旧字段。不要把客户端发版、服务端部署和规则更新当作必然同时发生的动作。移动端或长期运行的任务尤其容易继续使用旧格式,兼容窗口应根据实际调用方确定。

规则评审还应写清负责人、目标人群、回退值和结束条件。一个开关上线后长期保留两条业务路径,会增加测试组合和排障成本;结构化上下文越容易表达复杂条件,团队越需要约束临时规则的寿命。

灰度发布:先确认分桶单位,再调整流量

官方支持使用嵌套标识作为百分比发布的分桶属性。稳定分桶要求解析结果是字符串、数字或布尔值;路径缺失或结果为 null 时,每次评估会随机分桶;若结果为对象或数组,该规则失败并继续后续规则。百分比发布文档

据此,协作型产品通常应先决定按用户还是按工作区发布,再选择对应标识。按用户发布便于个人试用;按工作区发布更适合同一组成员需要协作的新流程。不要用请求编号替代稳定身份,否则刷新页面就可能改变体验。监控时也应按所选单位统计,避免把大量请求误当作大量独立参与者。

迁移建议:用一组反例验证,而非只看成功样本

建议先选一个低风险开关迁移,并保留旧路径的回退能力。测试至少覆盖正常对象、缺失字段、显式空值、空数组、错误类型、带点顶层键冲突,以及旧客户端仍发送标量上下文的情况。对百分比规则,要重复请求验证身份稳定性,还要检查未命中时会进入哪条后续规则。

可以在不改变用户结果的前提下,对新旧上下文进行并行比对,记录差异原因;日志只保留排查必要的信息,避免复制整份用户资料。观察错误率、评估失败和实际功能体验之后,再扩大范围。迁移完成后清理旧字段与临时兼容层,让字段约定、规则配置和应用代码重新保持一致。

此外,测试报告应区分“规则未命中”和“评估发生错误”。两者都可能让页面维持旧体验,但修复方向不同:前者检查字段与人群定义,后者检查请求、配置或调用链。只有布尔结果的日志,很难解释发布比例为何偏离预期。给测试用例保存脱敏后的上下文快照,也有助于复现问题。

这次更新最有价值的使用方式,是借机把发布决策变成一个可测试的应用接口:数据从哪里来、何时更新、失败如何处理,都有明确答案。对象可以直接传输之后,这些原本藏在拼接代码里的问题反而更值得写进设计和测试。

相关文章

评论

登录后即可参与讨论

暂无评论。