rails-architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Modern Rails 8 Architecture Patterns

现代Rails 8架构模式

Overview

概述

Rails 8 follows "convention over configuration" with a layered architecture that separates concerns. This skill guides architectural decisions for clean, maintainable code.

Rails 8遵循「约定优于配置」原则，采用关注点分离的分层架构。本技能为编写整洁、可维护的代码提供架构决策指导。

Architecture Decision Tree

架构决策树

Where should this code go?
│
├─ Is it view/display formatting?
│   └─ → Presenter (see: rails-presenter skill)
│
├─ Is it complex business logic?
│   └─ → Service Object (see: rails-service-object skill)
│
├─ Is it a complex database query?
│   └─ → Query Object (see: rails-query-object skill)
│
├─ Is it shared behavior across models?
│   └─ → Concern (see: rails-concern skill)
│
├─ Is it authorization logic?
│   └─ → Policy (see: authorization-pundit skill)
│
├─ Is it reusable UI with logic?
│   └─ → ViewComponent (see: viewcomponent-patterns skill)
│
├─ Is it async/background work?
│   └─ → Job (see: solid-queue-setup skill)
│
├─ Is it a complex form (multi-model, wizard)?
│   └─ → Form Object (see: form-object-patterns skill)
│
├─ Is it a transactional email?
│   └─ → Mailer (see: action-mailer-patterns skill)
│
├─ Is it real-time/WebSocket communication?
│   └─ → Channel (see: action-cable-patterns skill)
│
├─ Is it data validation only?
│   └─ → Model (see: rails-model-generator skill)
│
└─ Is it HTTP request/response handling only?
    └─ → Controller (see: rails-controller skill)

Where should this code go?
│
├─ Is it view/display formatting?
│   └─ → Presenter (see: rails-presenter skill)
│
├─ Is it complex business logic?
│   └─ → Service Object (see: rails-service-object skill)
│
├─ Is it a complex database query?
│   └─ → Query Object (see: rails-query-object skill)
│
├─ Is it shared behavior across models?
│   └─ → Concern (see: rails-concern skill)
│
├─ Is it authorization logic?
│   └─ → Policy (see: authorization-pundit skill)
│
├─ Is it reusable UI with logic?
│   └─ → ViewComponent (see: viewcomponent-patterns skill)
│
├─ Is it async/background work?
│   └─ → Job (see: solid-queue-setup skill)
│
├─ Is it a complex form (multi-model, wizard)?
│   └─ → Form Object (see: form-object-patterns skill)
│
├─ Is it a transactional email?
│   └─ → Mailer (see: action-mailer-patterns skill)
│
├─ Is it real-time/WebSocket communication?
│   └─ → Channel (see: action-cable-patterns skill)
│
├─ Is it data validation only?
│   └─ → Model (see: rails-model-generator skill)
│
└─ Is it HTTP request/response handling only?
    └─ → Controller (see: rails-controller skill)

Layer Interaction Flow

层交互流程

┌─────────────────────────────────────────────────────────────┐
│                        REQUEST                               │
└─────────────────────────┬───────────────────────────────────┘
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                     CONTROLLER                               │
│  • Authenticate (Authentication concern)                     │
│  • Authorize (Policy)                                        │
│  • Parse params                                              │
│  • Delegate to Service/Query                                 │
└──────────┬─────────────────────────────────┬────────────────┘
           │                                 │
           ▼                                 ▼
┌─────────────────────┐           ┌─────────────────────┐
│      SERVICE        │           │       QUERY         │
│  • Business logic   │           │  • Complex queries  │
│  • Orchestration    │           │  • Aggregations     │
│  • Transactions     │           │  • Reports          │
└──────────┬──────────┘           └──────────┬──────────┘
           │                                 │
           ▼                                 ▼
┌─────────────────────────────────────────────────────────────┐
│                        MODEL                                 │
│  • Validations  • Associations  • Scopes  • Callbacks       │
└─────────────────────────┬───────────────────────────────────┘
                          │
           ┌──────────────┴──────────────┐
           ▼                             ▼
┌─────────────────────┐       ┌─────────────────────┐
│     PRESENTER       │       │    VIEW COMPONENT   │
│  • Formatting       │       │  • Reusable UI      │
│  • Display logic    │       │  • Encapsulated     │
└──────────┬──────────┘       └──────────┬──────────┘
           │                             │
           └──────────────┬──────────────┘
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                       RESPONSE                               │
└─────────────────────────────────────────────────────────────┘

ASYNC FLOWS:
┌─────────────────────┐       ┌─────────────────────┐
│        JOB          │       │      CHANNEL        │
│  • Background work  │       │  • Real-time        │
│  • Solid Queue      │       │  • WebSockets       │
└─────────────────────┘       └─────────────────────┘

EMAIL FLOWS:
┌─────────────────────┐
│       MAILER        │
│  • Transactional    │
│  • Notifications    │
└─────────────────────┘

See layer-interactions.md for detailed examples.

┌─────────────────────────────────────────────────────────────┐
│                        REQUEST                               │
└─────────────────────────┬───────────────────────────────────┘
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                     CONTROLLER                               │
│  • Authenticate (Authentication concern)                     │
│  • Authorize (Policy)                                        │
│  • Parse params                                              │
│  • Delegate to Service/Query                                 │
└──────────┬─────────────────────────────────┬────────────────┘
           │                                 │
           ▼                                 ▼
┌─────────────────────┐           ┌─────────────────────┐
│      SERVICE        │           │       QUERY         │
│  • Business logic   │           │  • Complex queries  │
│  • Orchestration    │           │  • Aggregations     │
│  • Transactions     │           │  • Reports          │
└──────────┬──────────┘           └──────────┬──────────┘
           │                                 │
           ▼                                 ▼
┌─────────────────────────────────────────────────────────────┐
│                        MODEL                                 │
│  • Validations  • Associations  • Scopes  • Callbacks       │
└─────────────────────────┬───────────────────────────────────┘
                          │
           ┌──────────────┴──────────────┐
           ▼                             ▼
┌─────────────────────┐       ┌─────────────────────┐
│     PRESENTER       │       │    VIEW COMPONENT   │
│  • Formatting       │       │  • Reusable UI      │
│  • Display logic    │       │  • Encapsulated     │
└──────────┬──────────┘       └──────────┬──────────┘
           │                             │
           └──────────────┬──────────────┘
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                       RESPONSE                               │
└─────────────────────────────────────────────────────────────┘

ASYNC FLOWS:
┌─────────────────────┐       ┌─────────────────────┐
│        JOB          │       │      CHANNEL        │
│  • Background work  │       │  • Real-time        │
│  • Solid Queue      │       │  • WebSockets       │
└─────────────────────┘       └─────────────────────┘

EMAIL FLOWS:
┌─────────────────────┐
│       MAILER        │
│  • Transactional    │
│  • Notifications    │
└─────────────────────┘

详情示例请查看 layer-interactions.md。

Layer Responsibilities

各层职责

Layer	Responsibility	Should NOT contain
Controller	HTTP, params, response	Business logic, queries
Model	Data, validations, relations	Display logic, HTTP
Service	Business logic, orchestration	HTTP, display logic
Query	Complex database queries	Business logic
Presenter	View formatting, badges	Business logic, queries
Policy	Authorization rules	Business logic
Component	Reusable UI encapsulation	Business logic
Job	Async processing	HTTP, display logic
Form	Complex form handling	Persistence logic
Mailer	Email composition	Business logic
Channel	WebSocket communication	Business logic

层级	职责	不应包含的内容
Controller	HTTP处理、参数解析、响应返回	业务逻辑、查询语句
Model	数据管理、验证、关联关系	展示逻辑、HTTP处理
Service	业务逻辑、流程编排	HTTP处理、展示逻辑
Query	复杂数据库查询	业务逻辑
Presenter	视图格式化、标识处理	业务逻辑、查询语句
Policy	授权规则	业务逻辑
Component	可复用UI封装	业务逻辑
Job	异步处理	HTTP处理、展示逻辑
Form	复杂表单处理	持久化逻辑
Mailer	邮件内容组合	业务逻辑
Channel	WebSocket通信	业务逻辑

Project Directory Structure

项目目录结构

app/
├── channels/            # Action Cable channels
├── components/          # ViewComponents (UI + logic)
├── controllers/
│   └── concerns/        # Shared controller behavior
├── forms/               # Form objects
├── helpers/             # Simple view helpers (avoid)
├── jobs/                # Background jobs (Solid Queue)
├── mailers/             # Action Mailer classes
├── models/
│   └── concerns/        # Shared model behavior
├── policies/            # Pundit authorization
├── presenters/          # View formatting
├── queries/             # Complex queries
├── services/            # Business logic
│   └── result.rb        # Shared Result class
└── views/
    └── layouts/
        └── mailer.html.erb  # Email layout

app/
├── channels/            # Action Cable 通道
├── components/          # ViewComponents（UI + 逻辑）
├── controllers/
│   └── concerns/        # 共享控制器行为
├── forms/               # Form Object
├── helpers/             # 简单视图助手（尽量避免使用）
├── jobs/                # 后台任务（Solid Queue）
├── mailers/             # Action Mailer 类
├── models/
│   └── concerns/        # 共享模型行为
├── policies/            # Pundit 授权
├── presenters/          # 视图格式化
├── queries/             # 复杂查询
├── services/            # 业务逻辑
│   └── result.rb        # 共享Result类
└── views/
    └── layouts/
        └── mailer.html.erb  # 邮件布局

Core Principles

核心原则

1. Skinny Controllers

1. 精简控制器（Skinny Controllers）

Controllers should only:

Authenticate/authorize
Parse params
Call service/query
Render response

ruby

undefined

控制器应仅负责：

身份验证/授权
参数解析
调用Service/Query
渲染响应

ruby

undefined

GOOD: Thin controller

推荐：精简控制器

class OrdersController < ApplicationController def create result = Orders::CreateService.new.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

class OrdersController < ApplicationController def create result = Orders::CreateService.new.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

BAD: Fat controller with business logic

不推荐：包含业务逻辑的臃肿控制器

class OrdersController < ApplicationController def create @order = Order.new(order_params) @order.user = current_user

if @order.valid?
  inventory_available = @order.items.all? do |item|
    Product.find(item.product_id).inventory >= item.quantity
  end

  if inventory_available
    # ... more logic
  end
end

end end

undefined

class OrdersController < ApplicationController def create @order = Order.new(order_params) @order.user = current_user

if @order.valid?
  inventory_available = @order.items.all? do |item|
    Product.find(item.product_id).inventory >= item.quantity
  end

  if inventory_available
    # ... 更多逻辑
  end
end

end end

undefined

2. Rich Models, Smart Services

2. 丰富模型，智能服务（Rich Models, Smart Services）

Models handle:

Validations
Associations
Scopes
Simple derived attributes

Services handle:

Multi-model operations
External API calls
Complex business rules
Transactions across models

模型负责：

数据验证
关联关系
作用域
简单派生属性

服务负责：

跨模型操作
外部API调用
复杂业务规则
跨模型事务

3. Result Objects for Services

3. 服务返回统一Result对象

All services return a consistent Result object:

ruby

class Result
  attr_reader :data, :error, :code

  def initialize(success:, data: nil, error: nil, code: nil)
    @success = success
    @data = data
    @error = error
    @code = code
  end

  def success? = @success
  def failure? = !@success
end

所有服务返回格式一致的Result对象：

ruby

class Result
  attr_reader :data, :error, :code

  def initialize(success:, data: nil, error: nil, code: nil)
    @success = success
    @data = data
    @error = error
    @code = code
  end

  def success? = @success
  def failure? = !@success
end

4. Multi-Tenancy by Default

4. 默认支持多租户

All queries scoped through account:

ruby

undefined

所有查询需通过账号进行范围限定：

ruby

undefined

GOOD: Scoped through account

推荐：通过账号限定范围

def index @events = current_account.events.recent end

BAD: Unscoped query

不推荐：无范围限定的查询

def index @events = Event.where(user_id: current_user.id) end

undefined

def index @events = Event.where(user_id: current_user.id) end

undefined

When NOT to Abstract (Avoid Over-Engineering)

无需抽象的场景（避免过度设计）

Situation	Keep It Simple	Don't Create
Simple CRUD (< 10 lines)	Keep in controller	Service object
Used only once	Inline the code	Abstraction
Simple query with 1-2 conditions	Model scope	Query object
Basic text formatting	Helper method	Presenter
Single model form	`form_with model:`	Form object
Simple partial without logic	Partial	ViewComponent

场景	保持简洁	无需创建
简单CRUD（少于10行）	保留在控制器中	Service Object
仅使用一次的代码	内联编写	抽象层
仅含1-2个条件的简单查询	模型作用域	Query Object
基础文本格式化	助手方法	Presenter
单模型表单	`form_with model:`	Form Object
无逻辑的简单局部视图	局部视图	ViewComponent

Signs of Over-Engineering

过度设计的表现

ruby

undefined

ruby

undefined

OVER-ENGINEERED: Service for simple save

过度设计：为简单保存操作创建服务

class Users::UpdateEmailService def call(user, email) user.update(email: email) # Just do this in controller! end end

class Users::UpdateEmailService def call(user, email) user.update(email: email) # 直接在控制器中处理即可！ end end

KEEP IT SIMPLE

保持简洁

class UsersController < ApplicationController def update if @user.update(user_params) redirect_to @user else render :edit end end end

undefined

class UsersController < ApplicationController def update if @user.update(user_params) redirect_to @user else render :edit end end end

undefined

When TO Abstract

需要抽象的场景

Signal	Action
Same code in 3+ places	Extract to concern/service
Controller action > 15 lines	Extract to service
Model > 300 lines	Extract concerns
Complex conditionals	Extract to policy/service
Query joins 3+ tables	Extract to query object
Form spans multiple models	Extract to form object

信号	操作
相同代码出现在3个及以上位置	提取为Concern/Service
控制器方法超过15行	提取为Service
模型代码超过300行	提取为Concern
复杂条件判断	提取为Policy/Service
查询关联3个及以上表	提取为Query Object
表单涉及多个模型	提取为Form Object

Pattern Selection Guide

模式选择指南

Use Service Objects When:

何时使用Service Object：

Logic spans multiple models
External API calls needed
Complex business rules
Need consistent error handling
Logic reused across controllers/jobs

→ See rails-service-object skill for details.

逻辑涉及多个模型
需要调用外部API
存在复杂业务规则
需要统一的错误处理
逻辑需在控制器/任务间复用

→ 详情请查看 rails-service-object 技能。

Use Query Objects When:

何时使用Query Object：

Complex SQL/ActiveRecord queries
Aggregations and statistics
Dashboard data
Reports

→ See rails-query-object skill for details.

复杂SQL/ActiveRecord查询
数据聚合与统计
仪表盘数据展示
报表生成

→ 详情请查看 rails-query-object 技能。

Use Presenters When:

何时使用Presenter：

Formatting data for display
Status badges with colors
Currency/date formatting
Conditional display logic

→ See rails-presenter skill for details.

为展示格式化数据
带颜色标识的状态标签
货币/日期格式化
条件展示逻辑

→ 详情请查看 rails-presenter 技能。

Use Concerns When:

何时使用Concern：

Shared validations across models
Common scopes (e.g.,
```
Searchable
```
)
Shared callbacks (e.g.,
```
HasUuid
```
)
Keep it single-purpose!

→ See rails-concern skill for details.

模型间共享验证规则
通用作用域（如
```
Searchable
```
）
共享回调（如
```
HasUuid
```
）
确保单一职责！

→ 详情请查看 rails-concern 技能。

Use ViewComponents When:

何时使用ViewComponent：

Reusable UI with logic
Complex partials
Need testable views
Cards, tables, badges

→ See viewcomponent-patterns skill for details.

带逻辑的可复用UI
复杂局部视图
需要可测试的视图
卡片、表格、标签等组件

→ 详情请查看 viewcomponent-patterns 技能。

Use Form Objects When:

何时使用Form Object：

Multi-model forms
Wizard/multi-step forms
Search/filter forms
Contact forms (no persistence)

→ See form-object-patterns skill for details.

多模型表单
分步向导表单
搜索/筛选表单
无需持久化的联系表单

→ 详情请查看 form-object-patterns 技能。

Use Policies When:

何时使用Policy：

Resource authorization
Role-based access
Action permissions
Scoped collections

→ See authorization-pundit skill for details.

资源授权
基于角色的访问控制
操作权限管理
范围限定的集合

→ 详情请查看 authorization-pundit 技能。

Rails 8 Specific Features

Rails 8专属特性

Authentication (Built-in Generator)

身份验证（内置生成器）

bash

bin/rails generate authentication

Uses

has_secure_password

with Session model, Current class, and password reset flow.

→ See authentication-flow skill for details.

bash

bin/rails generate authentication

基于

has_secure_password

实现，包含Session模型、Current类和密码重置流程。

→ 详情请查看 authentication-flow 技能。

Background Jobs (Solid Queue)

后台任务（Solid Queue）

Database-backed job processing, no Redis required.

→ See solid-queue-setup skill for details.

基于数据库的任务处理，无需依赖Redis。

→ 详情请查看 solid-queue-setup 技能。

Real-time (Action Cable + Solid Cable)

实时通信（Action Cable + Solid Cable）

WebSocket support with database-backed adapter.

→ See action-cable-patterns skill for details.

支持WebSocket，采用数据库适配器。

→ 详情请查看 action-cable-patterns 技能。

Caching (Solid Cache)

缓存（Solid Cache）

Database-backed caching, no Redis required.

→ See caching-strategies skill for details.

基于数据库的缓存，无需依赖Redis。

→ 详情请查看 caching-strategies 技能。

Other Rails 8 Defaults

Rails 8其他默认特性

Feature	Purpose
Propshaft	Asset pipeline (replaces Sprockets)
Importmap	JavaScript without bundling
Kamal	Docker deployment
Thruster	HTTP/2 proxy with caching

特性	用途
Propshaft	资源管道（替代Sprockets）
Importmap	无需打包的JavaScript管理
Kamal	Docker部署工具
Thruster	带缓存的HTTP/2代理

Anti-Patterns to Avoid

需要避免的反模式

Anti-Pattern	Problem	Solution
God Model	Model > 500 lines	Extract services/concerns
Fat Controller	Logic in controllers	Move to services
Callback Hell	Complex model callbacks	Use services
Helper Soup	Massive helper modules	Use presenters/components
N+1 Queries	Unoptimized queries	Use `.includes()` , query objects
Stringly Typed	Magic strings everywhere	Use constants, enums
Premature Abstraction	Service for 3 lines	Keep in controller

→ See performance-optimization skill for N+1 detection.

反模式	问题	解决方案
上帝模型	模型代码超过500行	提取为Service/Concern
臃肿控制器	逻辑写在控制器中	迁移至Service
回调地狱	复杂的模型回调	使用Service
助手混乱	庞大的助手模块	使用Presenter/Component
N+1查询	未优化的查询	使用 `.includes()` 、Query Object
字符串硬编码	到处都是魔法字符串	使用常量、枚举
过早抽象	为3行代码创建Service	保留在控制器中

→ 详情请查看 performance-optimization 技能中的N+1查询检测。

Testing Strategy by Layer

按层级划分的测试策略

Layer	Test Type	Focus
Model	Unit	Validations, scopes, methods
Service	Unit	Business logic, edge cases
Query	Unit	Query results, tenant isolation
Presenter	Unit	Formatting, HTML output
Controller	Request	Integration, HTTP flow
Component	Component	Rendering, variants
Policy	Unit	Authorization rules
Form	Unit	Validations, persistence
System	E2E	Critical user paths

→ See tdd-cycle skill for TDD workflow.

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

→ 详情请查看 tdd-cycle 技能中的TDD工作流。

Quick Reference

快速参考

New Feature Checklist

新功能开发检查清单

Model - Define data structure
Policy - Add authorization rules
Service - Create for complex logic (if needed)
Query - Add for complex queries (if needed)
Controller - Keep it thin!
Form - Use for multi-model forms (if needed)
Presenter - Format for display
Component - Build reusable UI
Mailer - Add transactional emails (if needed)
Job - Add background processing (if needed)

Model - 定义数据结构
Policy - 添加授权规则
Service - 复杂逻辑场景下创建（如有需要）
Query - 复杂查询场景下添加（如有需要）
Controller - 保持精简！
Form - 多模型表单场景下使用（如有需要）
Presenter - 为展示格式化数据
Component - 构建可复用UI
Mailer - 添加事务性邮件（如有需要）
Job - 添加后台处理（如有需要）

Refactoring Signals

重构信号

Signal	Action
Model > 300 lines	Extract concern or service
Controller action > 15 lines	Extract service
View logic in helpers	Use presenter
Repeated query patterns	Extract query object
Complex partial with logic	Use ViewComponent
Form with multiple models	Use form object
Same code in 3+ places	Extract to shared module

信号	操作
模型代码超过300行	提取为Concern或Service
控制器方法超过15行	提取为Service
视图逻辑写在助手中	使用Presenter
查询模式重复出现	提取为Query Object
带逻辑的复杂局部视图	使用ViewComponent
表单涉及多个模型	使用Form Object
相同代码出现在3个及以上位置	提取为共享模块

Related Skills

Category	Skills
Data Layer	rails-model-generator, rails-query-object, database-migrations
Business Logic	rails-service-object, rails-concern, form-object-patterns
Presentation	rails-presenter, viewcomponent-patterns
Controllers	rails-controller, api-versioning
Auth	authentication-flow, authorization-pundit
Background	solid-queue-setup, action-mailer-patterns
Real-time	action-cable-patterns, hotwire-patterns
Performance	caching-strategies, performance-optimization
I18n	i18n-patterns
Testing	tdd-cycle

分类	技能
数据层	rails-model-generator, rails-query-object, database-migrations
业务逻辑	rails-service-object, rails-concern, form-object-patterns
展示层	rails-presenter, viewcomponent-patterns
控制器	rails-controller, api-versioning
认证授权	authentication-flow, authorization-pundit
后台处理	solid-queue-setup, action-mailer-patterns
实时通信	action-cable-patterns, hotwire-patterns
性能优化	caching-strategies, performance-optimization
国际化	i18n-patterns
测试	tdd-cycle

References

参考资料

See layer-interactions.md for layer communication patterns
See service-patterns.md for service object patterns
See query-patterns.md for query object patterns
See error-handling.md for error handling strategies
See testing-strategy.md for comprehensive testing

层交互模式详情请查看 layer-interactions.md
Service Object模式详情请查看 service-patterns.md
Query Object模式详情请查看 query-patterns.md
错误处理策略详情请查看 error-handling.md
全面测试策略详情请查看 testing-strategy.md