用途:为 Rails 应用设计、评审 Hotwire 与实时界面架构,提供 Turbo、Stimulus、ActionCable 的落地模式。
主要能力:
- 实时架构选型。两种已验证拓扑:仅用 Streams(Fizzy 式,无自定义 ActionCable 频道,用 turbo_stream_from、broadcasts_refreshes + morph、带 ETag 的懒加载 frame,适合 CRUD 类应用);Cable 增强(Campfire 式,自定义频道只传轻量 JSON 信号如在线、输入中、未读提醒,DOM 状态仍走 Turbo Streams)。原则:改 DOM 用 Turbo Streams,瞬时小信号才用裸 ActionCable。
- Turbo 默认实践。服务端渲染局部更新;布局中设 turbo_refreshes_with method: :morph, scroll: :preserve;用多目标 stream 模板原子更新多个区域;turbo_frame_tag ..., src:, loading: :lazy 配 fresh_when ETag;data-turbo-permanent 保护需跨导航存活的元素;用 turbo:before-morph-attribute + preventDefault() 阻止 morph 覆盖客户端状态;turbo_exempts_page_from_cache 让实时页避开页面缓存;用带 $placeholder$ 的 template 实现乐观 UI。
- 广播模式。广播逻辑放模型 concern(如 broadcast_create)而非控制器;流名按租户/用户隔离([board.account, :all_boards]、[user, :notifications]);需要时用 broadcasts_refreshes_to 做双流;用 before_update 标志位配合 if: 限制噪声广播;后台任务用 suppressing_turbo_broadcasts;render_to_string 一次后按收件人 broadcast_replace_to;必要时用 broadcast_*_later 异步;广播渲染的局部模板缺请求上下文,需包装 URL 助手。
- 重连与补偿。重连或回到标签页时拉取 turbo-stream 差异(?since=<epoch_ms>);空 HeartbeatChannel 提供可靠连接回调;Stimulus connect() 需检查 turbo-preview 以免缓存预览开 socket。
- Stimulus 默认实践。控制器单一职责、可组合;优先 targets/values;disconnect 中清理定时器与订阅(cable 退订延后一帧并判断是否重连);用事件或 outlets 解耦;复杂界面用 Ruby 助手集中接线;从 meta 读页面上下文;用 targetConnected 处理动态插入元素。
- 滚动与交互契约。用自定义属性 maintain_scroll: true 配合 turbo:before-stream-render 保持滚动;用 promise 队列串行化滚动变更;turbo:submit-start 时移除 stream target 的 id 防竞态;无限流用 IntersectionObserver 哨兵,限制 DOM 大小,仅在最新页自动滚动。
- ActionCable 安全。Connection#connect 用与 HTTP 一致的身份解析;频道订阅按所有权限定(current_user.rooms.find_by(id: params[:room_id]));用 remote_connections 断开被停用用户;在线状态用带 TTL 的引用计数连接;路径租户下用 request.script_name 生成 cable URL。
- 缓存与实时。缓存键与输出影响因素对齐,用 touch: true 链式失效;个性化片段在客户端按 data-creator-id 切换;表单页避免 HTTP 缓存。
- Web Push。只推给离线用户且排除操作者,尊重用户参与级别,用线程池与持久连接投递,异步清理失效订阅,登出时清理客户端订阅。
- 测试。模型广播用 assert_turbo_stream_broadcasts 与 assert_no_turbo_stream_broadcasts;控制器响应用 as: :turbo_stream 与 assert_turbo_stream;DOM 级断言可读 ActionCable.server.pubsub.broadcasts 配合 assert_select;系统测试用 using_session 并等待 turbo-cable-stream-source[connected]。
使用方式:作为技能/规范在编写或评审 Rails 实时界面时参照执行,具体安装与调用命令资料未提供。
适用场景:Rails 应用的实时聊天、看板、通知、无限流等界面开发与代码评审。
限制:内容为实践建议,未提供版本要求、依赖、性能数据或收费信息;需结合具体项目验证。