Rails 风格指导 · Ruby China

风格是从伟大事物中萃取出的美好事物。 -- Bozhidar Batsov
这份指南目的于演示一整套 Rails 3 开发的风格惯例及最佳实践。这是一份与由现存社群所驱动的Ruby 编码风格指南互补的指南。
而本指南中测试 Rails 应用小节摆在开发 Rails 应用之后，因为我相信行为驱动开发 (BDD) 是最佳的软体开发之道。铭记在心吧。
Rails 是一个坚持己见的框架，而这也是一份坚持己见的指南。在我的心里，我坚信 RSpec 优于 Test::Unit，Sass 优于 CSS 以及 Haml，(Slim) 优于 Erb。所以不要期望在这里找到 Test::Unit, CSS 及 Erb 的忠告。
某些忠告仅适用于 Rails 3.1+ 以上版本。
你可以使用 Transmuter 来产生本指南的一份 PDF 或 HTML 复本。
相应调整配置开发、测试及生产环境（在 config/environments/ 下对应的文件）
将所有环境皆通用的配置档放在 config/application.rb 文件。
构建一个与生产环境 (production enviroment) 相似的，一个额外的 staging 环境。
当你需要加入一个或多个动作至一个 RESTful 资源时（你真的需要吗？），使用 member and collection 路由。
若你需要定义多个 member/collection 路由时，使用替代的区块语法 (block syntax)。
使用嵌套路由 (nested routes) 来更佳地表达与 ActiveRecord 模型的关系。
不要在控制器里使用留给后人般的疯狂路由 (legacy wild controller route)。这种路由会让每个控制器的动作透过 GET 请求存取。
如果你需要模型有著 ActiveRecord 行为的对象，比方说验证这一块，使用 ActiveAttr gem。
更完整的示例，参考 RailsCast on the subject。
偏好 has_many :through 胜于 has_and_belongs_to_many。使用 has_many :through 允许在 join 模型有附加的属性及验证
使用新的 "sexy" validation。
当一个惯用的验证使用超过一次或验证是某个正则表达映射时，创建一个惯用的 validator 文件。
所有惯用的验证器应放在一个共享的 gem。
自由地使用命名的作用域 (scope)。
将命名的作用域包在 lambda 里来惰性地初始化。
当一个由 lambda 及参数定义的作用域变得过于复杂时，更好的方式是建一个作为同样用途的类别方法，并返回一个 ActiveRecord::Relation 对象。你也可以这么定义出更精简的作用域。
注意 update_attribute 方法的行为。它不运行模型验证（不同于 update_attributes ）并且可能把模型状态给搞砸。
使用用户友好的网址。在网址显示具描述性的模型属性，而不只是 id 。 有不止一种方法可以达成：
覆写模型的 to_param 方法。这是 Rails 用来给对象建构网址的方法。缺省的实作会以字串形式返回该 id 的记录。它可被另一个具人类可读的属性覆写。
为了要转换成对网址友好 (URL-friendly) 的数值，字串应当调用 parameterize 。对象的 id 要放在开头，以便给 ActiveRecord 的 find 方法查找。
使用此 friendly_id gem。它允许藉由某些具描述性的模型属性，而不是用 id 来创建人类可读的网址。
查看 gem 文档获得更多关于使用的信息。
当 HTTP 响应是一个与存在的格式不同的格式时（XML 和 JSON），需要某些额外的格式解析，创一个你惯用的格式，并在类别中使用它。惯用的格式应当实作下列方法：extension, mime_type, encode 以及 decode。
若 HTTP 请求应当不扩展发送时，覆写 ActiveResource::Base 的 element_path 及 collection_path 方法，并移除扩展的部分。
如有任何改动网址的需求时，这些方法也可以被覆写。
避免在表里设置缺省数据。使用模型层来取代。
然而 self[:attr_name] 的使用被视为相当常见的，你也可以考虑使用更罗嗦的（争议地可读性更高的） read_attribute 来取代：
当编写建设性的迁移时（加入表或栏位），使用 Rails 3.1 的新方式来迁移 - 使用 change 方法取代 up 与 down 方法。
加入 client side validation 至惯用的 validators。要做的步骤有：
声明一个由 ClientSideValidations::Middleware::Base 而来的自定 validator
建立一个新文件 public/javascripts/rails.validations.custom.js.coffee 并在你的 application.js.coffee 文件加入一个它的参照：
当 ActiveRecord 模型的标签需要被翻译时，使用activerecord 作用域：
然后 User.model_name.human 会返回 "Member" ，而 User.human_attribute_name("name") 会返回 "Full name"。这些属性的翻译会被视图作为标签使用。
把在视图使用的文字与 ActiveRecord 的属性翻译分开。把给模型使用的语言文件放在名为 models 的文件夹，给视图使用的文字放在名为 views 的文件夹。