106

我想创建一个包含 10 ~ 20 个类/文件的小型 Rub​​y 项目。我需要一些宝石，我想使用 RSpec 作为测试框架。

我以后可能想构建一个 gem，但这并不确定。

是否有一些方法或指南向我展示如何设置项目的基本结构？

我的问题是：

  • 我将所有自定义错误/异常放在哪里？
  • 是否有一些命名目录的约定，如 lib、bin、src 等？
  • 我在哪里放置测试数据或文档？
  • 我在哪里需要我的所有文件，以便我可以在我的项目中访问它们？

我知道我可以从头开始做所有事情，但我想要一些指导。那里有一些我可以复制的好宝石，但我不确定我真正需要什么以及我可以删除什么。

我查看了http://gembundler.com/，但在设置 Bundler 后它停止了。

4

4 回答 4

159

为了获得良好的开端，您可以使用bundle gem命令和rspec --init.

~/code $ bundle gem my_lib
      create  my_lib/Gemfile
      create  my_lib/Rakefile
      create  my_lib/LICENSE.txt
      create  my_lib/README.md
      create  my_lib/.gitignore
      create  my_lib/my_lib.gemspec
      create  my_lib/lib/my_lib.rb
      create  my_lib/lib/my_lib/version.rb
Initializating git repo in /Users/john/code/my_lib
~/code $ cd my_lib/
~/code/my_lib $ git commit -m "Empty project"
~/code/my_lib $ rspec --init
The --configure option no longer needs any arguments, so true was ignored.
  create   spec/spec_helper.rb
  create   .rspec
  • 代码进入lib
  • 规格进入spec
  • 测试数据或文件进入spec/fixtures/
  • 要求所有 ruby​​ 文件在lib/my_lib.rb. 您也可以在该文件中或在他们自己的文件中定义您的例外——根据您自己的偏好。
  • C源文件进入ext/my_lib
  • shell脚本和可执行文件进入bin

如有疑问，请查看其他宝石的布局方式。

更多信息：

您应该在 gemspec 中添加 rspec 作为开发依赖项，以使其他开发人员更容易

  1. 编辑 my_lib.gemspec，在底部附近添加gem.add_development_dependency 'rspec'和。gem.add_development_dependency 'rake'
  2. 添加Bundler.setup和require 'my_lib'到 spec/spec_helper.rb 的顶部，以确保在运行规范时加载您的 gem 依赖项。
  3. require "rspec/core/rake_task"将和添加task :default => :spec到您的 Rakefile，以便运行rake将运行您的规范。

在您处理最新创建时，guard-rspec可以通过在文件更改时自动运行您的规范，提醒您规范失败，从而节省您的时间和麻烦。

~/code/my_lib $ git add spec/spec_helper.rb
~/code/my_lib $ git commit -am "Add RSpec"
~/code/my_lib $ vim my_lib.gemspec # add guard development dependency
~/code/my_lib $ bundle
~/code/my_lib $ bundle exec guard init
~/code/my_lib $ vim Guardfile # Remove the sections below the top one
~/code/my_lib $ git add Guardfile
~/code/my_lib $ git commit -am "Add Guard"

在你对你的创作感到满意之后，将它推送到 github

# create a github repository for your gem, then push it up
~/code/my_lib $ curl -u myusername https://api.github.com/user/repos -d '{"name":"my_lib"}' 
~/code/my_lib $ git remote add origin git@github.com:myusername/my_lib.git
~/code/my_lib $ git push

然后，当您准备好在 Rubygems.org 上发布您的 gem 时，运行rake release，它将引导您完成这些步骤。

~/code/my_lib $ rake release

更多参考资料

于 2012-03-03T20:17:18.343 回答
11

rubygems.org上有一些不错的指南，它们将向您介绍约定以及其中一些背后的推理。通常，大多数 Ruby 开发人员都遵循Rubygems 命名和目录约定。

如果我无法在标准库中找到任何符合错误描述的类，我只会创建自定义异常类。将您的错误类嵌套在引发它的类或模块下：

class Parser::Error < RuntimeError; end

begin
  Parser.new(:invalid).parse!
rescue Parser::Error => e
  puts e.message
end

单元测试要么进入/test，如果你正在使用Test::Unit，或者进入，/spec如果你正在使用RSpec。我推荐后者。

Bundler是管理加载路径的好方法。它将自动设置您的环境，仅使用指定的依赖项Gemfile和可选的gemspec. 它还允许您轻松require编写代码，而无需使其成为 gem。

但是，由于您将来可能会将代码捆绑到 gem 中，因此我建议您研究如何创建 gem 规范。您应该手动编写规范。不要使用某些工具来自动生成它——在我看来，它们是蛮力方法，在与源代码控制一起使用时会不必要地复制信息并造成严重破坏。

我创建了一个您可能会觉得有用的 gem。给定一个gemspec文件，它定义了许多使用Rakegem 的有用任务，包括构建、安装和发布 gem 到rubygems带有git自动版本标记的存储库的任务。它还提供了一种在会话中加载代码irb的简单方法。pry

# Rakefile
require 'rookie'

# Run `rake -T` for the complete task list
Rookie::Tasks.new('your_gem.gemspec').define_tasks!
于 2012-03-03T20:32:22.100 回答
6

以下是我最常看到的约定（假设您的项目名称是“foo”）：

  • /lib/foo.rb - 定义项目的顶级命名空间及其版本；需要所需的文件。
  • /lib/foo/ - 包含项目的所有类，包括与错误相关的类。
  • /test/ - 包含项目的测试。
  • /spec/ - 包含项目的规范。
  • /bin/ - 如果您的项目依赖于二进制文件（JAR 文件等），它们通常会放在那里。

在 lib/ 中，约定通常是为顶级命名空间中的每个子命名空间创建一个文件夹。例如，类 Foo::Bar::Baz 通常位于 /lib/foo/bar/baz.rb 下。

有些人喜欢创建一个 /lib/foo/version.rb 文件来设置 Foo::VERSION 常量，但我经常看到 /lib/foo.rb 文件中定义了这个。

此外，如果您正在创建 gem，您将需要以下文件：

  • /Rakefile - 定义 rake 任务（例如用于测试、构建和推送 gem 的任务）。
  • /Gemfile - 定义 gem 的来源（以及其他可能的东西）。
  • /foo.gemspec - 描述您的 gem 并提供依赖项列表。
于 2012-03-03T20:16:33.980 回答
6

互联网上有一些关于如何构建 Ruby 项目的指南。此外，我认为解决这个问题的最佳方法是前往 github 并寻找一些著名的 Ruby 项目，并检查“他们的”结构。

除了一般的 ruby​​ gem 要求外，我推荐以下工具以获得更好的工作流程：

  • editorconfig，帮助开发人员在不同的编辑器和 IDE 之间定义和维护一致的编码风格。
  • rubocop，用于 ruby​​ 的静态代码分析器，在 ruby​​ 社区中用于 linter 的 defac。
  • 守卫，加上一堆插件，你可以在代码更改时自动运行任何你喜欢的命令。
  • rake，用于各种项目任务的通用驱动程序，例如：
    • package: 构建 gem 包
    • clean: 清理生成的文件
    • test: 运行测试
  • yard，流行的 ruby​​ 文档工具。

除了上述所有工具之外，它们还有一些用于 ruby​​ 项目的在线服务：

您甚至可以通过http://shields.io/为您的开源项目生成徽章。

以上是我的经验，希望对大家有所帮助。

于 2016-01-05T08:59:15.047 回答