37signals-rails

37signals Rails 最佳实践

全面介绍 Ruby on Rails 应用的编码原则和约定，反映了 37signals（Basecamp、HEY、Fizzy）的实践经验。包含 8 个类别的 56 条规则，并按架构影响排序。内容源自 37signals 的官方资料：Fizzy 代码库、STYLE.md、AGENTS.md、Rails Doctrine、DHH 的“On Writing Software Well”系列，以及非官方的 37signals 风格指南（265 个 Fizzy PR）。

何时应用

在以下情形中参考这些指南：

• 编写新的 Rails 控制器、模型或视图
• 决定使用 gem 还是原生 Rails
• 对状态和数据库架构进行建模
• 配置后台作业、缓存或实时功能
• 按照 37signals 风格的约定审查代码
• 重构以采用丰富的领域模型
• 选择身份验证或授权方案
• 添加 Stimulus 控制器或 Turbo 模式

按优先级划分的规则类别

优先级	类别	影响	前缀
1	架构基础	CRITICAL	arch-
2	控制器与 REST	CRITICAL	ctrl-
3	领域建模	HIGH	model-
4	状态管理	HIGH	state-
5	数据库与基础设施	HIGH	db-
6	视图与前端	MEDIUM	view-
7	代码风格	MEDIUM	style-
8	测试	MEDIUM	test-

快速参考

1. 架构基础（CRITICAL）

• arch-rich-models - 优先使用丰富的领域模型，而非服务对象
• arch-vanilla-rails - 原生 Rails 已足够强大
• arch-avoid-patterns - 有意避免的模式和 gem
• arch-earn-abstractions - 遵循三次法则，让抽象物逐步显现
• arch-build-before-gems - 使用 gem 之前先尝试自行实现
• arch-ship-to-learn - 从简单做起——仅在验证后增加复杂性
• arch-domain-facades - 领域模型作为内部复杂性的门面
• arch-single-business-layer - 业务逻辑只使用单层
• arch-custom-auth - 优先使用自定义无密码身份验证，而非 Devise

2. 控制器与 REST（CRITICAL）

• ctrl-crud-only - 优先使用 CRUD 控制器，而非自定义操作
• ctrl-model-as-resources - 将非 CRUD 操作建模为独立资源
• ctrl-thin-controllers - 使用精简控制器和丰富的领域模型
• ctrl-params-expect - 使用 params.expect() 验证参数
• ctrl-controller-concerns - 使用控制器 Concern 处理横切行为
• ctrl-nested-resources - 使用 scope module 嵌套资源

3. 领域建模（HIGH）

• model-concerns - 使用 Concern 在不同层面共享代码
• model-normalizes - 使用 normalizes 宏清理数据
• model-store-accessor - 使用 store_accessor 访问 JSON 列
• model-delegated-type - 使用 delegated_type 实现多态
• model-counter-caches - 使用计数器缓存避免 N+1 计数查询
• model-touch-chains - 使用 touch 链使缓存失效
• model-callbacks-auxiliary - 使用回调处理辅助复杂性
• model-event-tracking - 使用多态事件模型跟踪活动
• model-poro-namespacing - 在父模型下为 PORO 添加命名空间

4. 状态管理（HIGH）

• state-records-over-booleans - 使用记录表示状态，而不是布尔列
• state-timestamps - 为状态转换添加时间戳
• state-enums - 使用枚举表示分类状态
• state-db-constraints - 使用数据库约束，而不是 ActiveRecord 验证
• state-write-time - 在写入时计算，而不是在读取时计算

5. 数据库与基础设施（HIGH）

• db-backed-everything - 一切由数据库支持
• db-solid-queue - 使用 Solid Queue 处理后台任务
• db-solid-cable - 使用 Solid Cable 实现实时发布/订阅
• db-solid-cache - 使用 Solid Cache 实现应用缓存
• db-multi-tenancy - 使用 Current.account 实现基于路径的多租户
• db-uuid-primary-keys - 使用 UUID 作为主键
• db-no-foreign-keys - 不使用外键约束

6. 视图与前端（MEDIUM）

• view-turbo-frames - 使用 Turbo Frames 实现页面片段范围限定
• view-turbo-streams - 使用 Turbo Streams 实现实时更新
• view-stimulus-targets - 使用 Stimulus Targets，而不是 CSS 选择器
• view-stimulus-design - Stimulus 控制器设计原则
• view-helpers-not-partials - 将逻辑提取到辅助方法中，而不是局部模板
• view-progressive-enhancement - 将渐进式增强作为主要模式
• view-fragment-caching - 使用片段缓存提升视图性能
• view-http-caching - 使用 fresh_when 和 ETags 实现 HTTP 缓存

7. 代码风格（MEDIUM）

• style-conditionals - 使用展开的条件语句，而不是守卫子句
• style-method-ordering - 按调用顺序排列方法
• style-positive-names - 为方法和作用域使用肯定式名称
• style-naming-return-values - 方法名称应体现返回值
• style-visibility-modifiers - 可见性修饰符的格式
• style-bang-methods - 仅在存在非 bang 方法时使用 bang 方法
• style-async-naming - 异步操作使用 _later 和 _now 后缀

8. 测试（MEDIUM）

• test-minitest - 使用 Minitest，而不是 RSpec
• test-fixtures - 使用数据库 fixtures，而不是 FactoryBot
• test-no-damage - 不要因测试而损害设计
• test-no-system-tests - 使用集成测试，而不是系统测试
• test-behavior - 测试行为，而不是实现

使用方法

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

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

参考文件

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