Ruby 编码风格¶

此文件使用 Ruby 和 Rails 特定内容扩展 common/coding-style.md。

标准¶

• 除非项目已固定旧的受支持运行时，否则新的 Rails 开发应针对 Ruby 3.3+。
• 在生产环境中，仅在测量启动时间、内存以及请求/作业吞吐量之后，才启用 YJIT。
• 如果项目使用该约定，则在新 Ruby 文件中添加 # frozen_string_literal: true。
• 优先选择清晰的 Ruby，而不是巧妙的元编程。大量使用 DSL 的代码应隔离在狭窄且经过测试的边界之后。

格式与 Lint¶

• 使用项目已签入的 RuboCop 配置。对于 Rails 8+ 应用，从 rubocop-rails-omakase 开始，仅当代码库中存在实际约定时才进行自定义。
• 将格式化器/linter 命令放在 binstub 或脚本之后，使 CI 与本地执行保持一致:

bundle exec rubocop
bundle exec rubocop -A

• 除非例外范围狭窄、有文档说明，并且在代码中明确表达并不困难，否则不要内联禁用 cop。

Rails 风格¶

• 在添加自定义结构之前，遵循 Rails 命名规则和目录约定。
• 控制器应聚焦于传输层：认证、授权、参数处理、响应形状。
• 可复用的领域逻辑应基于实际复杂度，而不是作为默认样板，放置在模型、concerns、服务对象、查询对象或表单对象中。
• 优先使用 bin/rails、bin/rake 以及已签入的 binstub，而不是全局安装的命令。

错误处理¶

• 捕获特定异常。避免使用宽泛的 rescue StandardError 块，除非重新抛出或为运维人员保留足够的上下文。
• 对于运维事件，使用 ActiveSupport::Notifications 或应用日志记录器。不要在已提交的 application code 中保留 puts、pp、debugger。

参考¶

• 有关服务/仓库分层指导，请参阅技能：backend-patterns。