Populator Gem 技术文档

1. 安装指南

由于 Populator gem 已经不再维护，建议用户自行 fork 该项目并进行维护。以下是安装指南：

1.1 Rails 2 安装

在 Rails 2 中，可以通过以下命令安装 Populator gem：

gem install populator

安装完成后，在 rake 任务或其他地方加载 gem：

require "populator"

1.2 Rails 3 支持

Rails 3 的支持正在开发中，请保持关注。

2. 项目使用说明

Populator gem 为所有 Active Record 模型添加了一个 populate 方法，用于批量插入数据。以下是使用说明：

2.1 基本用法

通过 populate 方法，可以指定要创建的记录数量，并在块中设置每条记录的列值。例如：

Person.populate(3000) do |person|
  person.first_name = "John"
  person.last_name = "Smith"
end

上述代码将批量插入 3000 条记录，每条记录的 first_name 为 "John"，last_name 为 "Smith"。

2.2 关联数据插入

可以在 populate 块中设置关联数据。例如：

Person.populate(3000) do |person|
  person.first_name = "John"
  person.last_name = "Smith"
  Project.populate(30) do |project|
    project.person_id = person.id
  end
end

上述代码将为每个 Person 创建 30 个 Project。

2.3 随机值生成

可以通过传递范围或数组来随机选择值。例如：

Person.populate(1000..5000) do |person|
  person.gender = ['male', 'female']
  person.annual_income = 10000..200000
end

上述代码将创建 1000 到 5000 条记录，每条记录的 gender 为 "male" 或 "female"，annual_income 在 10000 到 200000 之间随机生成。

2.4 分批插入

可以通过 :per_query 选项限制每次插入的记录数量，默认值为 1000。例如：

Person.populate(2000, :per_query => 100)

上述代码将每次插入 100 条记录，总共插入 2000 条。

2.5 生成假数据

Populator 提供了一些方法来生成假数据：

Populator.words(3) # 生成 3 个随机单词
Populator.words(10..20) # 生成 10 到 20 个随机单词
Populator.sentences(5) # 生成 5 个句子
Populator.paragraphs(3) # 生成 3 个段落

如果需要更复杂的数据生成，可以结合 Faker gem 使用。

3. 项目 API 使用文档

3.1 populate 方法

populate 方法用于批量插入数据，接受两个参数：

• count: 要插入的记录数量，可以是整数或范围。
• options: 可选参数，目前仅支持 :per_query 选项，用于指定每次插入的记录数量。

3.2 块参数

在 populate 块中，可以设置每条记录的列值。块参数为当前记录的对象，可以通过该对象设置列值。

3.3 随机值生成方法

• Populator.words(count): 生成指定数量的随机单词。
• Populator.sentences(count): 生成指定数量的随机句子。
• Populator.paragraphs(count): 生成指定数量的随机段落。

4. 项目安装方式

4.1 通过 Gem 安装

在 Rails 2 中，可以通过以下命令安装 Populator gem：

gem install populator

4.2 加载 Gem

安装完成后，在 rake 任务或其他地方加载 gem：

require "populator"

4.3 Rails 3 支持

Rails 3 的支持正在开发中，请保持关注。

5. 注意事项

由于性能原因，Populator gem 不会使用模型的实际实例，因此会绕过验证和回调。用户需要自行确保插入的数据是有效的。