rails-hotwire

社区 Rails Hotwire 最佳实践

全面介绍如何使用 Hotwire（Turbo + Stimulus）构建交互式 Rails 应用，由社区维护。包含 9 个类别、53 条规则，并按影响程度排序，以指导自动重构和代码生成。遵循 DHH 的“单人框架”理念：服务器渲染 HTML，Turbo 让应用体验起来像 SPA，Stimulus 则在需要时添加少量 JS。

适用场景

在以下情况下参考这些指南：

• 配置 Turbo Drive 导航、预取和缓存行为
• 添加 Turbo Frames 以实现局部页面更新和延迟加载
• 使用 Turbo Streams 对 DOM 进行精准修改
• 通过 ActionCable 广播实时更新
• 启用 Turbo 8 morphing 以刷新页面
• 编写用于客户端行为的 Stimulus 控制器
• 处理 Turbo 导航、frames 和 WebSocket 连接中的错误
• 在 Drive、Frames、Streams、Morphing 和 Stimulus 之间进行选择
• 在系统测试和集成测试中测试 Hotwire 交互

按优先级划分的规则类别

优先级	类别	影响	前缀
1	导航与 Drive	严重	drive-
2	Turbo Frames	严重	frame-
3	Turbo Streams	高	stream-
4	广播与实时更新	高	bcast-
5	Morphing 与页面刷新	高	morph-
6	性能优化	中高	perf-
7	Stimulus 模式	中高	stim-
8	架构决策	中	arch-
9	Hotwire 测试	中	test-

快速参考

1. 导航与 Drive（严重）

• drive-prefetch-links - 启用链接预取，实现即时导航
• drive-form-submissions - 使用 Turbo Drive 提交表单
• drive-visit-actions - 使用访问操作控制历史记录
• drive-cache-control - 配置 Turbo 缓存，用于预览页面
• drive-selective-disable - 在不兼容的页面上禁用 Turbo Drive
• drive-progress-bar - 自定义 Turbo 进度条
• drive-confirm-dialog - 对破坏性操作使用 data-turbo-confirm
• drive-error-recovery - 妥善处理 Turbo 导航和 fetch 错误

2. Turbo Frames（严重）

• frame-lazy-loading - 等待 frame 进入视口后再加载
• frame-scope-navigation - 将导航限制在 frames 内
• frame-src-navigation - 使用 src 加载动态 frame 内容
• frame-break-out - 处理重定向时跳出 frame
• frame-promote-visits - 将 frame 导航提升为页面访问
• frame-dom-id - 使用 dom_id 标识 frame
• frame-empty-state - 提供有意义的 frame 加载状态

3. Turbo Streams（高）

• stream-progressive-enhance - 始终为 streams 提供 HTML 回退方案
• stream-action-selection - 为 DOM 修改选择合适的 stream 操作
• stream-multi-target - 使用 targets 更新多个元素
• stream-http-delivery - 通过 HTTP 发送表单响应的 streams
• stream-websocket-source - 在 body 中连接 WebSocket 来源
• stream-custom-actions - 注册自定义 stream 操作，以执行复杂的 DOM 更新

4. 广播与实时功能（HIGH）

• bcast-model-broadcasts - 使用 broadcasts_refreshes 实现简单的模型更新
• bcast-debounce-n1 - 对广播进行防抖，避免 N+1 广播风暴
• bcast-scope-streams - 将广播流限定到账号或用户
• bcast-refresh-over-replace - 优先使用广播刷新，而不是细粒度的流更新
• bcast-avoid-view-logic-in-models - 不要在模型中编写广播逻辑
• bcast-signed-stream-names - 使用签名流名称确保安全
• bcast-reconnect-handling - 处理 WebSocket 断开和重新连接

5. DOM 变形与页面刷新（HIGH）

• morph-enable-page-refresh - 启用页面刷新时的 DOM 变形
• morph-permanent-elements - 将有状态元素标记为永久元素
• morph-scroll-preservation - DOM 变形期间保留滚动位置
• morph-stimulus-reconnect - 处理 DOM 变形后 Stimulus 控制器的重新连接
• morph-frame-refresh - 在 frame 上使用 refresh='morph' 添加内容
• morph-vs-streams - 复杂的流编排场景优先选择 DOM 变形

6. 性能优化（MEDIUM-HIGH）

• perf-optimistic-ui - 在服务器确认前实现乐观 UI 更新
• perf-batch-streams - 将多个流更新批量合并到单个响应中
• perf-frame-caching - 使用片段缓存缓存 Turbo Frame 响应
• perf-prefetch-strategic - 在开销较大的端点上禁用预取
• perf-memory-leak-prevention - 清理订阅和事件侦听器

7. Stimulus 模式（MEDIUM-HIGH）

• stim-outlets-communication - 使用 outlets 实现跨控制器通信
• stim-values-reactive-state - 使用 Values API 管理控制器的响应式状态
• stim-action-descriptors - 使用声明式操作描述符，而不是 addEventListener
• stim-small-reusable-controllers - 保持 Stimulus 控制器小巧且可复用

8. 架构决策（MEDIUM）

• arch-progressive-enhancement - 遵循渐进增强层级
• arch-frame-vs-stream-decision - 使用 frame 实现限定范围的导航，使用 stream 实现多目标更新
• arch-importmap-management - 使用 import maps 固定 JavaScript 依赖
• arch-avoid-client-state - 将状态保留在服务器上，而不是客户端
• arch-stimulus-boundaries - 仅使用 Stimulus 实现客户端行为

9. 测试 Hotwire（中等）

• test-system-test-async - 在系统测试中等待 Turbo 更新
• test-stream-assertions - 在集成测试中使用 Turbo Stream 测试辅助工具
• test-broadcast-assertions - 使用 Turbo 测试辅助工具断言广播
• test-frame-navigation - 使用限定范围的断言测试框架导航
• test-websocket-timing - 处理系统测试中的 WebSocket 连接时序

使用方法

阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 - 类别结构和影响级别
• 规则模板 - 添加新规则的模板

参考文件

文件	描述
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息