Trucker 使用与技术文档

本文档将详细介绍如何使用 Trucker 项目迁移遗留数据到 Rails 应用程序。以下是安装指南、项目使用说明、项目 API 使用文档以及安装方式的详细说明。

1. 安装指南

首先，确保你已经安装了以下环境：

• Ruby
• Rails

以下为 Trucker 的安装步骤：

1. 安装 Trucker gem

   sudo gem install trucker
   

2. 在 environment.rb 的 config.gem 块中添加 Trucker

   config.gem "trucker"
   

3. 生成基本的 Trucker 文件

   script/generate truck
   

   这将执行以下操作：

   • 将遗留适配器添加到 database.yml
   • 在 app/models/legacy 添加目录
   • 将 app/models/legacy 添加到 Rails Initializer 配置块的 autoload_paths
   • 添加 app/models/legacy/legacy_base.rb（遗留模型将从该文件继承）
   • 为所有现有模型生成遗留子类
   • 生成示例迁移任务（使用复数形式的模型名称）

4. 在 database.yml 中更新遗留数据库适配器，填入你的遗留数据库信息

   legacy:
     adapter: mysql
     encoding: utf8
     database: app_legacy
     username: root
     password:
   

   按照约定，建议将你的遗留数据库命名为 APP_legacy，类似于你的其他数据库，如 APP_development、APP_production 等。

5. 如果遗留数据库不存在，创建它

   rake db:create:all
   

6. 将遗留数据导入遗留数据库

   mysql -u root app_legacy < old_database.sql
   

   如果不是使用 mysql，需要相应地更改此命令。

7. 为每个遗留模型自定义表名

   class LegacyPost < LegacyBase
     self.table_name = "LEGACY_TABLE_NAME_GOES_HERE"
   end
   

   由于你从旧数据库迁移数据，表名可能不符合 Rails 的数据库表名约定。如果如此，你需要为每个遗留模型设置 self.table_name = 值，以匹配你将从中导入数据的表名。

8. 更新遗留模型字段映射

   class LegacyPost < LegacyBase
     self.table_name = "LEGACY_TABLE_NAME_GOES_HERE"
   
     def map
       {
         :headline => self.title.squish,
         :body => self.long_text.squish
       }
     end
   end
   

   在这里，你将旧数据库的属性与新模型的属性连接起来。map 方法实际上只是一个哈希，使用新模型属性名作为键，旧模型属性作为值。

   注意：确保为每个旧属性名称添加 self.。

9. 如果需要调整一些数据，可以添加一些核心 Ruby 方法或辅助方法

   class LegacyPost < LegacyBase
     self.table_name = "LEGACY_TABLE_NAME_GOES_HERE"
   
     def map
       {
         :headline => self.title.squish.capitalize, # 添加 capitalize 方法
         :body => tweak_body(self.long_text.squish) # 添加 tweak_body 方法
       }
     end
   
     # 按需插入辅助方法
     def tweak_body(body)
       body = body.gsub(/<br \//,"\n") # 将 break 标签转换为正常行中断
       body = body.gsub(/teh/, "the")  # 修复常见拼写错误
     end
   end
   

10. 开始迁移

    rake db:migrate:posts
    

2. 项目的使用说明

以下是 Trucker 项目的使用说明：

• 使用 Trucker 迁移遗留数据到 Rails 应用程序。
• Trucker 会生成遗留模型和迁移任务，便于你自定义字段映射和数据迁移。

3. 项目 API 使用文档

Trucker 提供了一些命令行选项，用于在迁移记录时使用：

• rake db:migrate:posts limit=100（迁移 100 条记录）
• rake db:migrate:posts limit=100 offset=100（迁移 100 条记录，但跳过前 100 条记录）

此外，你可以使用 :label 选项自定义迁移输出的标签：

• rake db:migrate:posts 输出 Migrating posts
• rake db:migrate:posts, :label => "blog posts" 输出 Migrating blog posts

如果需要为模型执行复杂的迁移，可以使用自定义辅助方法覆盖 Trucker 的默认迁移方法。具体实现方式见下文。

4. 项目安装方式

请参考上述“安装指南”部分的步骤进行安装。

---

以上是 Trucker 项目的详细技术文档，希望对你有所帮助。