Sure 预览功能门控(Preview Feature Gating)完整指南:从用户开关到后台任务
Sure 预览功能门控(Preview Feature Gating)完整指南:从用户开关到后台任务
Sure 将未完成的新功能通过一个位于用户级别的开关进行门控:用户可在「设置 → 偏好设置」中自行开启预览功能,开启后可见新功能,未开启的用户则完全无感知。本文基于 docs/llm-guides/gating-a-preview-feature.md 的完整指南,结合仓库源码与测试,系统讲解在 Sure 中为控制器、视图、主导航以及后台任务接入预览门控的全部方式,并给出从接入到 GA 移除的完整流程。
门控机制的工作原理
预览状态的存储位置是 users.preferences["preview_features_enabled"]——它是既有 JSONB 列 preferences 内的一个键,默认值为 false。读取该状态统一经由 User#preview_features_enabled? 谓词方法。
从源码看,User 模型 的实现是严格布尔比较:
def preview_features_enabled?
preferences&.dig("preview_features_enabled") == true
end
注意这里的 == true 是刻意为之的严格判断:即使 preferences 里存在一个字符串 "yes" 之类的值,也不会被误判为开启。与之配套的还有一个 SQL 层的 scope User.with_preview_features(app/models/user.rb):
scope :with_preview_features, -> {
where("preferences @> ?", { preview_features_enabled: true }.to_json)
}
该 scope 使用 PostgreSQL 的 @> JSONB 包含操作符,命中 users.preferences 上的 GIN 索引,一次查询即可完成过滤,且与 Ruby 谓词保持语义一致(只有 JSON 布尔 true 才算开启),供需要批量过滤用户的场景(例如后台任务)使用。
PreviewGateable:控制器的统一入口
ApplicationController 全量引入了 PreviewGateable concern(app/controllers/concerns/preview_gateable.rb),从而为每一个控制器提供两个方法:
preview_features_enabled?:返回布尔值,未登录调用方恒为false;require_preview_features!:before_action辅助方法,将无预览权限的用户重定向到/,并附带一条指向「设置 → 偏好设置」的 flash 提示。
concern 内部实现非常精简:
module PreviewGateable
extend ActiveSupport::Concern
included do
helper_method :preview_features_enabled?
end
def preview_features_enabled?
Current.user&.preview_features_enabled? == true
end
def require_preview_features!
return if preview_features_enabled?
redirect_to root_path, alert: I18n.t("preview.not_enabled")
end
end
included 块中的 helper_method :preview_features_enabled? 会把该方法注册为视图辅助方法,因此视图模板可以直接调用它。重定向文案来自 config/locales/views/preview/en.yml 中的 preview.not_enabled,通过 I18n 加载,多语言环境(config/locales 下共 2339 个 yml 文件)下可正常翻译。
相关关键文件
| 文件 | 职责 |
|---|---|
| app/controllers/concerns/preview_gateable.rb | 门控 concern:preview_features_enabled? 与 require_preview_features! |
| app/models/user.rb | preview_features_enabled? 谓词 + with_preview_features SQL scope |
| app/views/settings/preferences/show.html.erb | 用户可见的开关 UI |
| app/controllers/settings/preferences_controller.rb | 开关的写入路径 |
| app/components/DS/pill.rb | Preview / Canary 标记 pill 组件 |
| app/helpers/application_helper.rb | preview_gated_nav_item 导航辅助方法 |
开关的写入路径:设置页
用户通过「设置 → 偏好设置」页面切换开关。视图层在 app/views/settings/preferences/show.html.erb 中渲染一个 checkbox,checked 状态直接绑定 @user.preview_features_enabled?,表单字段名为 user[preview_features_enabled]。
写入由 Settings::PreferencesController#update 负责,它没有走通用的 UsersController#update(那会期望完整的用户表单载荷),而是直接在事务内锁定用户行并只更新这一个偏好键:
def update
@user = Current.user
user_params = params.permit(user: [ :preview_features_enabled ]).fetch(:user, {})
@user.transaction do
@user.lock!
updated_prefs = (@user.preferences || {}).deep_dup
if user_params.key?(:preview_features_enabled)
updated_prefs["preview_features_enabled"] =
ActiveModel::Type::Boolean.new.cast(user_params[:preview_features_enabled])
end
@user.update!(preferences: updated_prefs)
end
redirect_to settings_preferences_path
end
ActiveModel::Type::Boolean.new.cast 保证了写入 JSONB 的永远是真正的布尔值,与 == true 的严格读取语义闭环。
门控一个控制器
给控制器加门控只需在类里声明一个 before_action :require_preview_features!,全部动作都会被拦截:
class GoalsController < ApplicationController
before_action :require_preview_features!
end
路由保持原样定义——门控发生在每次请求时,而非路由层。无预览权限的用户访问 /goals 会被重定向到根路径并收到 flash 提示;有预览权限的用户直接通过。
如果只有部分动作需要门控,用 only: 限定作用域即可:
class TransactionsController < ApplicationController
before_action :require_preview_features!, only: %i[forecast scenarios]
end
如果希望被门控的控制器落到别的目标页(比如文档页或引导开启的页面),可以在控制器内覆写 require_preview_features!,或者写一个薄的 before_action 直接调用 preview_features_enabled?。
门控一个视图片段
在视图中,用 preview_features_enabled? 辅助方法包裹相关片段即可:
<% if preview_features_enabled? %>
<li>
<%= link_to t(".nav.goals"), goals_path %>
</li>
<% end %>
同样的模式适用于仪表盘 widget、记分卡卡片等任何「预览数据与非预览数据并排展示」的场景。辅助方法每次请求都会解析,实时反映当前用户的最新偏好——用户关闭开关后,下一次请求视图即恢复隐藏。
门控主导航
桌面端侧边栏和移动端底部导航都从 app/views/layouts/shared/_nav_item.html.erb 渲染。该 partial 接受一个可选的 preview: local——为 true 时,会在图标右上角叠加一个仅圆点的紫色 pill(见第 12-16 行),让已开启预览的用户一眼就能看出该导航项通往预览界面。
为此提供了 preview_gated_nav_item 辅助方法(app/helpers/application_helper.rb):
def preview_gated_nav_item(item)
return nil unless preview_features_enabled?
item.merge(preview: true)
end
一次调用同时完成门控的两半:无预览权限时返回 nil(配合 Array#compact 后该条目彻底不进入导航);有权限时打上 preview: true 标记(partial 据此绘制圆点)。
在导航数组中这样使用:
<% mobile_nav_items = [
{ name: t(".nav.home"), path: root_path, icon: "pie-chart", icon_custom: false, active: page_active?(root_path) },
{ name: t(".nav.transactions"), path: transactions_path, icon: "credit-card", icon_custom: false, active: page_active?(transactions_path) },
preview_gated_nav_item({ name: t(".nav.goals"), path: goals_path, icon: "piggy-bank", icon_custom: false, active: page_active?(goals_path) }),
{ name: t(".nav.assistant"), path: chats_path, icon: "icon-assistant", icon_custom: true, active: page_active?(chats_path), mobile_only: true }
].compact %>
你不需要手改 _nav_item.html.erb,也不需要手工设置 preview: true。新增一个预览导航项,就是在原来要写的 hash 外面套一层辅助方法调用。仓库里 bills_nav_item(app/helpers/application_helper.rb)就是真实范例:它在判断家庭未禁用周期性检测之后,把账单导航项同样用 preview_gated_nav_item 包起来,实现「无标志隐藏、有标志加紫点」。
在 UI 中标记预览功能
当预览界面为已开启用户渲染时,用设计系统里的 Pill 组件打上标记(app/components/DS/pill.rb):
<%# 页面标题旁。md 尺寸与 h1 / h2 搭配。 %>
<%= render DS::Pill.new(label: "Preview", size: :md) %>
<%# 侧边栏导航标签或区块标题旁。sm 是默认值。 %>
<%= render DS::Pill.new(label: "Preview") %>
<%# 同样的形状、fuchsia 色调,用于 canary / 实验性界面。 %>
<%= render DS::Pill.new(label: "Canary", tone: :fuchsia) %>
<%# 侧边栏图标栏放不下文字。仅圆点模式保留色调语义但不显示文字。 %>
<%= render DS::Pill.new(tone: :violet, dot_only: true, title: "Preview") %>
Pill 组件的参数体系(源码 app/components/DS/pill.rb 确认):
- 默认色调为 violet。可用色调:
violet、indigo、fuchsia、amber、green、gray、red(源码中TONES常量比指南文档多列了green与red),另有语义别名success/warning/error/destructive/info/neutral会映射到对应调色板; - 样式:
soft(默认)、filled、outline; - 尺寸:
sm(默认)、md; - 模式:
marker: true(默认)为小号大写字母的阶段标记(Beta、Canary、NEW 等);marker: false则变成普通状态/分类徽章;dot_only: true只渲染彩色圆点。
Lookbook 预览位于 /design-system(寻找 PillComponentPreview#default),可以切换每个选项直接看到调用点的渲染效果,无需往返 Rails。
测试:两种状态都要覆盖
被门控的控制器应同时测试两种状态。标准模式如下:
class GoalsControllerTest < ActionDispatch::IntegrationTest
setup do
sign_in @user = users(:family_admin)
end
test "redirects users without preview access" do
@user.update!(preferences: (@user.preferences || {}).merge("preview_features_enabled" => false))
get goals_url
assert_redirected_to root_path
assert_match(/preview/i, flash[:alert])
end
test "renders for users with preview access" do
@user.update!(preferences: (@user.preferences || {}).merge("preview_features_enabled" => true))
get goals_url
assert_response :success
end
end
两个用例的断言点:无权限时 assert_redirected_to root_path + flash 文案含 preview;有权限时 assert_response :success。如果写系统测试,在 setup 中用同样方式翻转偏好后再执行 visit。仓库的控制器测试目录 test/controllers 下有 177 个测试文件,门控相关测试可按此模式扩展。
功能 GA 后移除门控
当功能从预览进入通用可用(GA)阶段,移除门控是一个小而机械的 PR:
- 从控制器删除
before_action :require_preview_features!这一行; - 解开视图中的
if preview_features_enabled?包裹块; - 从页头与区块标题移除
DS::Pill标记,把preview_gated_nav_item(...)调用还原成普通的导航 hash; - 删除覆盖重定向行为的控制器/视图测试。
收尾时在功能附近全局搜索 require_preview_features! 与 preview_features_enabled?,确认没有残留调用点。
后台任务与门控:按需接入
门控本身对后台任务不做任何事——PreviewGateable 读取的是 Current.user,而 Sidekiq worker 里并没有这个对象。因此 cron 任务无论谁开启了预览都会照常执行。这通常是正确的:数据应当持续流动,等有人开启预览时数据已经就绪。
什么时候需要给任务加门控? 只有当任务做的是「不免费」的工作时:
- 向外发送内容(通知、邮件)——在发送点门控;
- 为每个家庭凭空制造数据而非搬运既有数据,从而消耗每家庭的计算或付费 API 调用。
GenerateInsightsJob是典型:七个生成器遍历收支表与资产负债表,加上可选的 LLM 叙述,每晚为每个家庭运行。
对于家庭级任务,把用户级标志汇总到家庭层面:
# app/models/family.rb
scope :with_preview_features, -> { where(id: User.with_preview_features.select(:family_id)) }
def preview_features_enabled?
users.with_preview_features.exists?
end
这两段在 app/models/family.rb 有完整实现与注释。用 scope 过滤扇出(User.with_preview_features 是一次命中 GIN 索引的 JSONB 包含匹配,而非加载后遍历),再在家庭路径内部用谓词复查——该路径可被控制器和 console 直接触达。两个模型保持同名谓词,这样 GA 移除时的全局搜索能找全所有调用点。GenerateInsightsJob(app/jobs/generate_insights_job.rb)是参考实现。
两个重要的语义陷阱
同名的代价:preview_features_enabled? 在 User 上表示「我本人开启了」,在 Family 上则表示「我家有人开启了」。永远只在后台工作上使用家庭形式。如果在 UI 上用它(Current.family.preview_features_enabled? 读起来很自然,这正是陷阱),会向一个明确关闭了预览的成员展示该功能,仅仅因为另一位家庭成员开启了。任何给人看的东西,都用读取 Current.user 的 PreviewGateable 辅助方法。
数据与可见性的分离:预览标志是按用户而非按家庭的。同一家庭的两个用户可以分别看到不同版本的产品——这是刻意设计:数据按家庭作用域存储,但可见性是个人偏好。如果你写的功能会创建家庭共享数据(目标、预算等),用户在关闭预览后数据依然保留,只是从他的视图中消失,而仍会展示给已开启预览的家庭成员。
结语
Sure 的预览门控是一套三层结构:控制器层用 require_preview_features! 拦截请求,视图层用 preview_features_enabled? 条件渲染,导航层用 preview_gated_nav_item 一次完成「隐藏 + 标记」两件事;而家庭级聚合与 with_preview_features scope 则为后台任务提供了索引友好的批量判断。理解「用户可见性 vs 家庭数据」的边界,遵循「任务用家庭形式、UI 用用户形式」的原则,就能让预览功能在不阻塞小 PR 的前提下安全迭代,最终以一次干净的机械 PR 平滑走向 GA。