rails-architecture

Modern Rails 8 架构模式

架构决策树

Where should this code go?
|
+- View/display formatting?       -> Presenter (@presenter-agent)
+- Complex business logic?        -> Service Object (@service-agent)
+- Complex database query?        -> Query Object (@query-agent)
+- Shared behavior across models? -> Concern (/rails-concern skill)
+- Authorization logic?           -> Policy (@policy-agent)
+- Reusable UI with logic?        -> ViewComponent (@viewcomponent-agent)
+- Async/background work?         -> Job (@job-agent, /solid-queue-setup skill)
+- Complex form (multi-model)?    -> Form Object (@form-agent)
+- Transactional email?           -> Mailer (@mailer-agent)
+- Real-time/WebSocket?           -> Channel (/action-cable-patterns skill)
+- Data validation only?          -> Model (@model-agent)
+- HTTP request/response only?    -> Controller (@controller-agent)

各层职责

层	职责	不应包含
Controller	HTTP、参数、响应	业务逻辑、查询
Model	数据、验证、关联	显示逻辑、HTTP
Service	业务逻辑、编排	HTTP、显示逻辑
Query	复杂数据库查询	业务逻辑
Presenter	视图格式化、徽章	业务逻辑、查询
Policy	授权规则	业务逻辑
Component	可复用的 UI 封装	业务逻辑
Job	异步处理	HTTP、显示逻辑
Form	复杂表单处理	持久化逻辑
Mailer	邮件编写	业务逻辑
Channel	WebSocket 通信	业务逻辑

何时不应抽象

情况	保持简单	不要创建
简单 CRUD（少于 10 行）	保留在控制器中	Service 对象
只使用一次	内联代码	抽象
只有 1-2 个条件的简单查询	Model 作用域	Query 对象
基本文本格式化	Helper 方法	Presenter
单一 Model 表单	form_with model:	Form 对象
无逻辑的简单局部模板	Partial	ViewComponent

何时应抽象

信号	操作
相同代码出现在 3 个以上位置	提取为 concern/service
Controller 操作超过 15 行	提取为 Service
Model 超过 300 行	提取 concerns
复杂条件判断	提取为 Policy/Service
查询连接 3 个以上表	提取为 Query 对象
表单涉及多个 Model	提取为 Form 对象

有关详细的抽取指南，请参阅 /extraction-timing skill。

核心模式

精简的控制器

# GOOD: Thin controller delegates to service
class OrdersController < ApplicationController
  def create
    result = Orders::CreateService.call(user: current_user, params: order_params)
    if result.success?
      redirect_to result.data, notice: t(".success")
    else
      flash.now[:alert] = result.error
      render :new, status: :unprocessable_entity
    end
  end
end

Service 使用 Result 对象

所有 Service 都返回一致的 Result 对象：

Result = Data.define(:success, :data, :error) do
  def success? = success
  def failure? = !success
end

默认采用多租户

# GOOD: Scoped through account
def index
  @events = current_account.events.recent
end

Rails 8 特有功能

功能	用途	Skill/Agent
身份验证	has_secure_password 生成器	/authentication-flow
后台作业	Solid Queue（由数据库支持）	/solid-queue-setup, @job-agent
实时功能	Action Cable + Solid Cable	/action-cable-patterns
缓存	Solid Cache（由数据库支持）	/caching-strategies
资源	Propshaft + Import Maps	（内置）
部署	Kamal 2 + Thruster	（内置）

按层划分的测试策略

层	测试类型	重点
Model	单元测试	验证、作用域、方法
Service	单元测试	业务逻辑、边界情况
Query	单元测试	查询结果、租户隔离
Presenter	单元测试	格式化、HTML 输出
Controller	请求测试	集成、HTTP 流程
Component	组件测试	渲染、变体
Policy	单元测试	授权规则
System	端到端测试	关键用户路径

新功能检查清单

1. Model - 定义数据结构（@migration-agent、@model-agent）
2. Policy - 添加授权规则（@policy-agent）
3. Service - 为复杂逻辑创建（@service-agent）
4. Query - 为复杂查询添加（@query-agent）
5. Controller - 保持精简（@controller-agent）
6. Presenter - 格式化以供显示（@presenter-agent）
7. Component - 构建可复用的 UI（@viewcomponent-agent）
8. Mailer - 添加事务性邮件（@mailer-agent）
9. Job - 添加后台处理（@job-agent）

参考资料

• 有关各层通信模式，请参阅 layer-interactions.md
• 有关 Service 对象模式，请参阅 service-patterns.md
• 有关 Query 对象模式，请参阅 query-patterns.md
• 有关错误处理策略，请参阅 error-handling.md
• 有关全面的测试，请参阅 testing-strategy.md