ECC Ruby/Rails 架构模式指南：从 Rails Way 到 Solid Queue、Hotwire 与认证选型的工程决策手册

ECC Ruby/Rails 架构模式指南：从 Rails Way 到 Solid Queue、Hotwire 与认证选型的工程决策手册

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC

导读

本文基于 ECC 仓库中 Ruby 语言规则集的核心文件 patterns.md，系统讲解在 Ruby on Rails 项目中如何做出可持续的架构决策：从"先用 Rails Way"的分层演进原则，到持久化选型（PostgreSQL 与 Rails 8 SQLite 默认值）、后台任务（Solid Queue 与 Sidekiq）、前端方案（Hotwire 与 SPA）以及认证体系（Rails 8 认证生成器与 Devise）的取舍标准。读完本文，你将获得一套可直接用于 Rails 8 项目评审与架构设计的决策框架，并理解 ECC 如何通过"公共规则 + 语言专属规则"的分层结构把这些工程准则落地为 Agent 可执行的规范。

一、规则定位：Ruby 专属层如何扩展公共模式

在 ECC 的规则体系中，rules/目录采用"公共层 + 语言层"的分层结构（见 rules/README.md）：

rules/ ├── common/ # 语言无关的通用原则（总是安装） │ └── patterns.md # 骨架项目、仓库模式、API 响应格式等 └── ruby/ # Ruby / Rails 专属 ├── coding-style.md ├── patterns.md # 本文主体 ├── hooks.md ├── security.md └── testing.md

patterns.md 的文件头明确声明："This file extends common/patterns.md with Ruby and Rails specific content."也就是说，通用模式（如 Repository 模式、API 响应信封格式）在 common/patterns.md 中定义，而 Ruby 层只补充 Rails 语境下特有的架构决策点。规则优先级上，语言专属规则优先于公共规则（类似于 CSS 特指度或.gitignore优先级），因此 Ruby 团队在架构评审时以本文为最高优先依据。

该文件通过 YAML frontmatter 声明其生效范围，Agent 在以下文件上会自动激活这套规则：

paths: - "**/*.rb" - "**/*.rake" - "**/Gemfile" - "**/app/**/*.erb" - "**/config/routes.rb"

二、Rails Way First：从约定俗成到有节制地抽象

规则的第一条铁律是"先走 Rails Way（Rails Way First）"，它包含三个递进的原则：

1. 中小功能先用纯 Rails MVC 与 Active Record 约定

对中小规模功能，不急于引入任何自定义架构层。控制器处理请求、模型处理领域逻辑、Active Record 处理持久化，这是 Rails 生态被验证过的最短路径，也符合 coding-style.md 中"先遵循 Rails 命名与目录约定，再考虑自定义结构"的要求。

2. 分层抽象的唯一触发条件：职责过载

只有当模型/控制器边界承载了多重职责时，才引入以下对象：

这条规则的本质是"按需抽象而非默认仪式"——这与 coding-style.md 中的表述完全一致："Put reusable domain behavior in models, concerns, service objects, query objects, or form objects based on actual complexity, not as default ceremony."

3. 命名要反映业务操作，而非通用层名

提取出的对象必须按其所执行的业务操作命名，严禁使用Manager、Processor这类泛化层名。例如：

# 不推荐：无法传达业务语义 class OrderManager def process; end end # 推荐：直接表达业务操作 class OrderCheckout def call(order, payment_params); end end class InvoiceGenerator def call(order); end end

这种命名约束的价值在于：类名即文档，评审代码时一眼就能看出该对象承担的具体业务职责，避免出现一个什么都做的"上帝 Manager"。

三、持久化选型：PostgreSQL 优先与 Rails 8 SQLite 默认值的边界

1. 多主机生产环境优先 PostgreSQL

对于多主机（multi-host）生产 Rails 应用，除非现有平台有明确理由使用 MySQL 或 SQLite，否则优先 PostgreSQL。理由包括：PostgreSQL 的事务、索引能力、JSON 支持以及与 Rails 生态（如全文搜索、几何类型）的深度整合。

2. Rails 8 的 SQLite 默认值适用边界

Rails 8 将 SQLite 设为默认数据库，规则对此给出了清醒的边界判断：

Rails 8 的 SQLite 默认配置适合单主机或小规模部署，但不会自动适配共享多服务系统。

这意味着：若你的应用是单体小部署、并发写入压力不大，SQLite 的开箱即用体验极具吸引力；但一旦涉及多服务共享数据库、高并发写入或集群部署，就必须迁移到 PostgreSQL 这类服务端数据库。

3. 原始 SQL 的封装纪律

规则要求：所有原始 SQL 都必须放在查询对象（Query Object）或模型作用域（model scope）背后，且所有动态值必须参数化。

# 推荐：封装在模型 scope 中，动态值参数化 class Order < ApplicationRecord scope :paid_since, ->(since) { where("paid_at >= ?", since) # 参数化，杜绝字符串拼接 } end # 推荐：复杂查询封装为 Query Object class MonthlyRevenueQuery def initialize(relation = Order.all) @relation = relation end def call(year:, month:) @relation .where(status: :paid) .where("paid_at >= ? AND paid_at < ?", Date.new(year, month), Date.new(year, month).next_month) .sum(:amount_cents) end end

这条纪律与 security.md 中"绝不将请求、Cookie、Header、Job 或 Webhook 值插值进 SQL 字符串"的硬性要求互为表里，是防 SQL 注入的第一道防线。

四、后台任务与运行时服务：Solid Queue 与 Sidekiq 的取舍

规则给出了清晰的二选一决策树：

Solid Queue —— 绿地 Rails 8 项目的默认选择

对于吞吐量适中、部署要求简单的绿地 Rails 8 应用，使用Solid Queue。

Solid Queue 是 Rails 8 自带的数据库驱动后台任务系统，其核心优势是无需额外基础设施——直接复用应用数据库，部署模型与 Rails 应用完全一致，符合"简单部署"的诉求。

Sidekiq —— 需要成熟能力时的升级路径

当应用需要成熟的可观测性、高吞吐量、已有 Redis 基础设施，或Pro/Enterprise 功能时，使用Sidekiq。

Sidekiq 基于 Redis 的架构决定了它适合以下场景：

• 需要成熟的监控、重试统计、批量任务等 Pro/Enterprise 能力；
• 已经运维 Redis，不希望再引入新的存储组件；
• 任务吞吐量高，需要独立于主数据库的任务队列。

缓存与实时通道：Solid Cache / Solid Cable vs Redis

类似的决策逻辑也适用于缓存与 WebSocket：

核心判据是"部署模型是否匹配"：如果你的应用是多服务共享 Redis 的体系，单独为 Rails 应用引入数据库驱动缓存反而割裂了基础设施；反之，简单单体应用用 Redis 则引入了不必要的运维负担。

五、前端策略：Hotwire 优先，SPA 按需引入

1. 服务端渲染优先 Hotwire

对于服务端渲染的 Rails 应用，规则明确推荐Hotwire全家桶：

• Turbo：Turbo Drive 加速页面导航，Turbo Frames 局部更新，Turbo Streams 通过 WebSocket 推送增量 DOM 变更；
• Stimulus：轻量级 JavaScript 框架，为 HTML 添加渐进增强行为；
• Importmap：无 Node 构建步骤的 JavaScript 依赖管理；
• Propshaft：Rails 8 默认的资产管道，替代 Sprockets。

这四件套让 Rails 团队无需引入独立前端构建链即可获得接近 SPA 的交互体验，与 Rails 的"约定优于配置"哲学一脉相承。

2. 何时引入 React / Vue / Inertia.js / 独立 SPA

规则给出三个引入客户端前端的正当理由：

• 交互复杂度：页面存在复杂的状态管理、拖拽、实时协作等高交互需求；
• 既有产品架构：公司已有成熟的 React/Vue 前端体系与组件库；
• 团队所有权：前端团队独立维护前端代码库。

3. 视图层的职责边界

规则对视图层提出明确约束：视图组件（View Component）、局部模板（partial）、Presenter 只负责渲染决策，持久化与授权逻辑严禁进入模板。

<%# 错误示范：模板内直接操作持久化与鉴权 %> <% if current_user.can?(:admin) && User.dangerous_operation!(current_user) %> ... <% end %> <%# 正确示范：模板只做渲染判断 %> <% if render_admin_panel? %> <%= render AdminPanelComponent.new(user: current_user) %> <% end %>

这条规则保证了模板的可测试性与安全性，与 security.md 中"转义模板输出、将html_safe/raw视为安全敏感代码"的要求配套。

六、认证方案：Rails 8 生成器与 Devise 的边界

认证选型同样遵循"简单优先，复杂再升级"的原则：

场景一：简单会话认证 → Rails 8 认证生成器

对简单的会话认证与密码重置需求，使用Rails 8 认证生成器。

Rails 8 内置的认证生成器（bin/rails generate authentication）会生成基于会话的认证、密码重置所需的最小代码集，无额外 Gem 依赖，代码完全透明可控，适合新项目的默认起点。

场景二：复杂认证需求 → Devise 或其他成熟认证系统

当需求包含OAuth、MFA、confirmable/lockable 流程、多模型认证，或已有大规模 Devise 使用痕迹时，使用 Devise 或其它成熟认证系统。

具体触发条件包括：

这与 security.md 的认证章节完全同源，且 security 规则补充了配套要求：登录及权限变更后轮换会话、账户恢复流程使用带过期时间的单次令牌 + 限流 + 审计日志。

七、规则体系的配套延伸

本文档并非孤立存在，它与 Ruby 规则集的其他文件形成完整闭环：

• rules/ruby/coding-style.md：Ruby 3.3+ 运行时目标、YJIT 启用前提（先度量启动时间、内存与吞吐再开）、# frozen_string_literal: true约定、RuboCop 配置（Rails 8+ 从rubocop-rails-omakase起步）；
• rules/ruby/testing.md：Minitest/RSpec 二选一不混用、测试金字塔（模型/服务测试 → 请求测试 → Capybara 系统测试）、fixtures 与 factory_bot 的选用；
• rules/ruby/security.md：CSRF 保持开启、强参数防批量赋值、凭据管理、bundle-audit/brakeman依赖检查；
• skills/backend-patterns/SKILL.md：本文档"参考"章节指向的服务边界与适配器模式深度参考，涵盖 Repository 模式、Service Layer、Middleware、缓存策略（Cache-Aside）、错误处理（指数退避重试）、限流（必须使用 Redis 等共享存储，禁止进程内计数器）等通用实现模式。

规则与技能的分工正如 rules/README.md 所述：Rules 告诉你"做什么"（what），Skills 告诉你"怎么做"（how）。

八、落地实践：如何将本文规则应用到项目

1. 通过 ECC 安装脚本安装 Ruby 规则集

./install.sh ruby # 或与其他语言规则集组合安装 ./install.sh ruby typescript python

2. 手动安装（保留目录结构）

重要提示：必须复制整个目录，切勿用/*拍平。公共层与语言层存在同名文件（如patterns.md），拍平会导致语言专属文件覆盖公共规则，并破坏../common/相对引用。

mkdir -p ~/.claude/rules/ecc cp -r rules/common ~/.claude/rules/ecc/ cp -r rules/ruby ~/.claude/rules/ecc/

项目级规则同理，复制到项目根目录的.claude/rules/ecc/下。

3. 用规则做架构评审清单

当你评审一个 Rails 8 项目或为 Agent 编写 Ruby 代码任务时，可以逐条对照本文作为检查清单：

1. 分层是否过度/不足：中小功能是否仍保持 Rails MVC 原味？抽象是否仅在职责过载时引入？
2. 对象命名：Service/Query 对象是否以业务操作命名（OrderCheckout而非OrderManager）？
3. 持久化：多主机是否选了 PostgreSQL？原始 SQL 是否封装且参数化？
4. 后台任务：绿地应用是否默认 Solid Queue？需要 Redis 生态时才上 Sidekiq？
5. 前端：服务端渲染是否优先 Hotwire？模板里有没有混入持久化/鉴权？
6. 认证：简单会话用 Rails 8 生成器，OAuth/MFA 等多模型需求才用 Devise？

这套清单既是代码评审的抓手，也是 Agent 在 Ruby 文件（*.rb、*.rake、Gemfile、*.erb、config/routes.rb）上自动激活的上下文规则，确保 AI 辅助开发与人工评审遵循同一套架构标准。

结语

ECC 的 Ruby 模式规则提供了一个极具操作性的工程哲学：默认相信框架约定，抽象必须由真实复杂度驱动，选型以部署模型与运维现实为准绳。从 Rails Way First 到 Solid Queue/Sidekiq、Hotwire/SPA、Rails 8 认证/Devise 的三组决策边界，本质上都在回答同一个问题——"当前应用的复杂度与部署现实，配得上什么样的架构？" 将这套规则固化进 Agent 的路径触发条件（frontmatter 中的paths），即可让每一次 Ruby 代码生成与评审都自动对齐团队的最佳实践。

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC