rails-dev

Ruby on Rails 开发最佳实践社区指南

面向 Ruby on Rails 应用的全面性能与可维护性优化指南，由 Community 维护。包含 8 个类别中的 45 条规则，并按影响优先级排序，为自动化重构和代码生成提供指导。

适用场景

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

• 编写新的 Rails 控制器、模型或视图
• 优化 ActiveRecord 查询和数据库访问模式
• 实现缓存策略（片段缓存、俄罗斯套娃缓存、底层缓存）
• 构建或重构 API 端点
• 为交互式 UI 添加 Turbo Frames 和 Streams
• 检查代码中的 N+1 查询和安全漏洞
• 使用 Sidekiq 或 Active Job 设计后台任务
• 编写或检查数据库迁移

按优先级划分的规则类别

优先级	类别	影响	前缀
1	数据库与 ActiveRecord	关键	db-
2	控制器与路由	关键	ctrl-
3	安全	高	sec-
4	模型与业务逻辑	高	model-
5	缓存与性能	高	cache-
6	视图与前端	中高	view-
7	API 设计	中	api-
8	后台任务与异步处理	中低	job-

快速参考

1. 数据库与 ActiveRecord（关键）

• db-eager-load-associations - 预加载关联，以消除 N+1 查询
• db-add-database-indexes - 为查询涉及的列添加数据库索引
• db-select-specific-columns - 只选择需要的列
• db-batch-processing - 使用 find_each 遍历大型数据集
• db-avoid-queries-in-loops - 避免在循环中执行数据库查询
• db-use-scopes - 在模型上定义可复用的查询作用域
• db-safe-migrations - 编写可逆且零停机的迁移
• db-exists-over-count - 检查记录是否存在时，使用 exists? 而非 count

2. 控制器与路由（关键）

• ctrl-thin-controllers - 将工作委托给模型和服务，保持控制器精简
• ctrl-strong-params - 批量赋值时始终使用强参数
• ctrl-restful-routes - 遵循 RESTful 路由约定
• ctrl-before-action-scoping - 使用 only/except 限定 before_action 回调的作用范围
• ctrl-respond-to-format - 使用 respond_to 支持多种格式的响应
• ctrl-rescue-from - 在控制器中使用 rescue_from 处理错误

3. 安全（高）

• sec-parameterized-queries - 切勿在 SQL 中插入用户输入
• sec-strong-params-whitelist - 对允许的参数进行白名单管理，切勿使用黑名单
• sec-authenticate-before-authorize - 每个请求都必须先认证，再授权
• sec-csrf-protection - 为所有表单提交启用 CSRF 防护
• sec-scope-queries-to-user - 将查询限定到当前用户，以进行授权检查

4. 模型与业务逻辑（高）

• model-validate-at-model-level - 在模型层验证数据
• model-avoid-callback-side-effects - 避免模型回调产生副作用
• model-use-service-objects - 将复杂逻辑提取到服务对象中
• model-scope-over-class-methods - 使用 scope 而非类方法组合查询
• model-use-enums - 为有限状态字段使用枚举
• model-concerns-for-shared-behavior - 使用 concern 复用模型行为
• model-query-objects - 将复杂查询提取到查询对象中

5. 缓存与性能（高）

• cache-fragment-caching - 对开销较大的视图局部模板使用片段缓存
• cache-russian-doll - 对嵌套集合使用俄罗斯套娃缓存
• cache-low-level - 使用 Rails.cache.fetch 缓存计算数据
• cache-counter-cache - 使用计数缓存统计关联记录数
• cache-conditional-get - 使用 stale? 实现 HTTP 条件 GET 缓存

6. 视图与前端（中高）

• view-collection-rendering - 使用集合渲染，而非循环渲染局部模板
• view-turbo-frames - 使用 Turbo Frames 局部更新页面
• view-turbo-streams - 使用 Turbo Streams 实时修改页面
• view-form-with - 使用 form_with，而非 form_tag 或 form_for
• view-avoid-logic-in-views - 将显示逻辑移至辅助方法或展示器中

7. API 设计（中）

• api-serializers - 使用序列化器保持 JSON 响应格式一致
• api-pagination - 始终为集合端点启用分页
• api-versioning - 从一开始就对 API 进行版本控制
• api-error-responses - 返回结构化的错误响应
• api-avoid-jbuilder-hot-paths - 避免在高流量端点使用 Jbuilder

8. 后台任务与异步处理（低至中）

• job-idempotent-design - 将任务设计为幂等
• job-small-payloads - 向任务传递 ID，而非序列化对象
• job-error-handling - 为任务配置重试和错误处理
• job-unique-jobs - 防止重复入队任务

使用方法

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

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

参考文件

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