Sure 预览功能门控(Preview Feature Gating)完整指南:从用户开关到后台任务

原创2026-09-23 10:56:371,965 阅读
文章标签:金融科技后端前端移动开发桌面应用人工智能AI 应用

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:

  1. 从控制器删除 before_action :require_preview_features! 这一行;
  2. 解开视图中的 if preview_features_enabled? 包裹块;
  3. 从页头与区块标题移除 DS::Pill 标记,把 preview_gated_nav_item(...) 调用还原成普通的导航 hash;
  4. 删除覆盖重定向行为的控制器/视图测试。

收尾时在功能附近全局搜索 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。

登录后查看全文
sure