RubyGems 中 add_dependency 与 add_runtime_dependency 的使用指南

在 Ruby 生态系统中，RubyGems 作为包管理工具的核心组件，其 gemspec 文件中的依赖声明方式一直存在两种写法：add_dependency 和 add_runtime_dependency。这两种方法在功能上完全等价，但开发者社区中对其使用却存在明显的分歧。

从历史演变来看，add_dependency 实际上是更早出现的原始方法，可以追溯到 2003 年的 RubyGems 早期版本。直到 2008 年，随着开发依赖概念的引入，才新增了 add_runtime_dependency 和 add_development_dependency 这对更明确的方法。这种演变反映了 RubyGems 对依赖管理粒度细化的需求。

在实际使用中，社区数据显示 add_dependency 的使用频率显著高于 add_runtime_dependency。根据多个代码仓库的统计分析，前者约占 65-73% 的使用比例。这种偏好可能源于几个因素：Bundler 官方文档和生成器默认使用 add_dependency；更简洁的写法符合 Ruby 社区的审美；以及在不需要区分开发依赖的场景下更直观。

从技术实现层面看，当前 RubyGems 的代码库中，add_dependency 实际上是 add_runtime_dependency 的别名。这种实现方式反映了维护团队对后者的偏重，但实际使用习惯却与之相反。

对于开发者来说，最佳实践建议如下：

1. 如果项目使用 Gemfile 管理开发依赖（现代 Ruby 项目的推荐做法），在 gemspec 中使用 add_dependency 声明运行时依赖更为合适，这保持了声明方式的一致性。

2. 当需要在 gemspec 中同时声明运行时和开发依赖时，可以考虑使用 add_runtime_dependency 和 add_development_dependency 这对对称的方法，以增强代码的可读性。

3. 对于新项目，遵循 Bundler 生成器的默认建议使用 add_dependency 是安全的选择，这符合大多数现有项目的惯例。

值得注意的是，RubyGems 核心团队近期已开始调整文档和代码生成模板，逐步确立 add_dependency 作为首选写法的地位。这种变化反映了对实际开发者习惯的尊重，同时也保持了与现有代码库的兼容性。

无论选择哪种写法，最重要的是在项目中保持一致性。团队可以根据项目特点和成员偏好制定相应的代码风格指南，确保依赖声明的统一性。随着 Ruby 生态的演进，这种微小的语法差异最终可能会通过工具链的改进而自然解决。