action-cable-patterns

Rails 8 中的 Action Cable 模式

概述

Action Cable 将 WebSocket 与 Rails 集成：

• 无需轮询即可实时更新
• 服务器向客户端推送通知
• 聊天和消息功能
• 实时仪表盘和信息流
• 协作编辑

快速开始

Action Cable 默认已包含在 Rails 中。配置如下：

# config/cable.yml
development:
  adapter: async

test:
  adapter: test

production:
  adapter: solid_cable  # Rails 8 default
  # OR
  adapter: redis
  url: <%= ENV.fetch("REDIS_URL") %>

项目结构

app/
├── channels/
│   ├── application_cable/
│   │   ├── connection.rb      # Authentication
│   │   └── channel.rb         # Base channel
│   ├── notifications_channel.rb
│   ├── events_channel.rb
│   └── chat_channel.rb
├── javascript/
│   └── channels/
│       ├── consumer.js
│       ├── notifications_channel.js
│       └── events_channel.js
spec/channels/
├── notifications_channel_spec.rb
└── events_channel_spec.rb

连接身份验证

# app/channels/application_cable/connection.rb
module ApplicationCable
  class Connection < ActionCable::Connection::Base
    identified_by :current_user

    def connect
      self.current_user = find_verified_user
    end

    private

    def find_verified_user
      # Using Rails 8 authentication
      if session_token = cookies.signed[:session_token]
        if session = Session.find_by(token: session_token)
          session.user
        else
          reject_unauthorized_connection
        end
      else
        reject_unauthorized_connection
      end
    end
  end
end

通道模式

有四种核心模式可用。完整的 Ruby 和 JavaScript 实现请参阅 channel-patterns.md：

• 模式 1：通知通道 — 通过 stream_for current_user 按用户推送通知
• 模式 2：资源更新通道 — 为特定资源推送更新，并通过 reject 进行授权
• 模式 3：聊天通道 — 使用 speak 和 typing 操作进行双向消息传递，并跟踪在线状态
• 模式 4：仪表盘实时更新 — 向所有账户成员广播统计数据和活动信息流

每种模式都遵循相同的结构：

1. subscribed — 查找资源、检查授权，并调用 stream_for
2. 类级别的 broadcast_* 方法 — 通过 ApplicationController.renderer 渲染局部模板
3. 对应的 JavaScript 订阅处理程序，其中包含 received(data) 分支

广播

可以从服务、模型或回调触发广播。相关内容请参阅 broadcasting-and-stimulus.md：

• 从服务对象触发 — 持久化后调用 EventsChannel.broadcast_update(event)
• 从模型回调触发 — 使用 after_create_commit 触发通道广播
• Turbo Streams 集成 — 直接在模型上使用 broadcast_append_to / broadcast_remove_to 辅助方法
• Stimulus 控制器 — 将 Action Cable 订阅生命周期封装在 Stimulus 控制器中，以便清晰地管理连接和断开连接
• 性能模式 — 连接数限制、选择性广播、防抖广播

测试通道

完整的测试规范请参阅 testing.md。主要约定：

# Stub connection identity
stub_connection(current_user: user)

# Assert subscription confirmed and streaming
subscribe(event_id: event.id)
expect(subscription).to be_confirmed
expect(subscription).to have_stream_for(event)

# Assert rejection for unauthorized access
expect(subscription).to be_rejected

# Assert broadcast payload
expect {
  described_class.notify(user, notification)
}.to have_broadcasted_to(user).with(hash_including(type: "notification"))

检查清单

• 已配置连接身份验证
• 已实现通道授权
• 已设置客户端订阅
• 已从服务/模型触发广播
• 已编写通道规范
• 已设置错误处理
• 客户端已设置重新连接逻辑
• 已配置性能限制

参考资料

• channel-patterns.md — 通知、资源更新、聊天和仪表盘通道的完整实现（Ruby + JavaScript）
• broadcasting-and-stimulus.md — 从服务/模型触发广播、Turbo Streams 集成、Stimulus 控制器、性能提示
• testing.md — RSpec 通道规范、授权规范和系统测试