deep_cloneable 项目技术文档

1. 安装指南

环境要求

• Ruby 2.3.0, 2.4.4, 2.5.5, 2.6.3, 2.7.5（已测试）
• TruffleRuby 21.3.0
• Activerecord 3.2, 4.0, 4.1, 4.2, 5.0, 5.1, 5.2, 6.0, 7.0（已测试）
• Rails 2.x/3.0 用户请查看 rails2.x-3.0 分支

安装步骤

1. 在项目的 Gemfile 中添加 deep_cloneable：

   gem 'deep_cloneable', '~> 3.2.0'
   

2. 运行 bundle install 安装 gem。

2. 项目使用说明

基本用法

deep_cloneable 为每个 ActiveRecord::Base 对象提供了深度克隆的功能，包括用户指定的关联。默认情况下，deep_clone 方法的行为与 ActiveRecord 的 dup 方法相同。

关联包含

可以通过 include 选项指定要包含在克隆中的关联：

# 单个关联
pirate.deep_clone include: :mateys

# 多个关联
pirate.deep_clone include: [ :mateys, :treasures ]

# 深度关联
pirate.deep_clone include: { treasures: :gold_pieces }
pirate.deep_clone include: [ :mateys, { treasures: :gold_pieces } ]

字典（对象重用）

字典确保在嵌套模型中不会多次克隆相同的模型。可以通过 use_dictionary 选项启用字典：

pirate.deep_clone include: [ :mateys, { treasures:  [ :matey, :gold_pieces ] } ], use_dictionary: true

属性排除与包含

deep_clone 方法支持 except 和 only 选项，用于指定要克隆的属性：

# 单个排除
pirate.deep_clone except: :name

# 多个排除
pirate.deep_clone except: [ :name, :nick_name ]

# 嵌套排除
pirate.deep_clone include: :parrot, except: [ :name, { parrot: [ :name ] } ]

# 单个包含
pirate.deep_clone only: :name

# 多个包含
pirate.deep_clone only: [ :name, :nick_name ]

# 嵌套包含
pirate.deep_clone include: :parrot, only: [ :name, { parrot: [ :name ] } ]

预处理器和后处理器

可以指定预处理器和后处理器来修改克隆对象：

pirate.deep_clone(include: :parrot, preprocessor: ->(original, kopy) { kopy.cloned_from_id = original.id if kopy.respond_to?(:cloned_from_id) })
pirate.deep_clone(include: :parrot, postprocessor: ->(original, kopy) { kopy.cloned_from_id = original.id if kopy.respond_to?(:cloned_from_id) })

可选块

可以通过传递块来修改克隆对象：

pirate.deep_clone include: :parrot do |original, kopy|
  kopy.cloned_from_id = original.id if kopy.respond_to?(:cloned_from_id)
end

3. 项目API使用文档

deep_clone 方法

• include: 指定要包含的关联。
• except: 指定要排除的属性。
• only: 指定要包含的属性。
• use_dictionary: 启用字典以避免重复克隆。
• dictionary: 预填充的字典。
• validate: 禁用验证以提高性能。
• preprocessor: 预处理器，用于在克隆前修改对象。
• postprocessor: 后处理器，用于在克隆后修改对象。
• skip_missing_associations: 跳过缺失的关联，避免抛出异常。

示例

pirate.deep_clone include: { treasures: :gold_pieces }, validate: false
pirate.deep_clone except: [ :name, { parrot: [ :name ] } ]
pirate.deep_clone only: [ :name, :nick_name ]

4. 项目安装方式

通过 Gemfile 安装

在 Gemfile 中添加以下内容：

gem 'deep_cloneable', '~> 3.2.0'

然后运行 bundle install 安装 gem。

手动安装

可以通过以下命令手动安装：

gem install deep_cloneable -v 3.2.0

总结

deep_cloneable 是一个强大的工具，允许你对 ActiveRecord 对象进行深度克隆，并灵活地控制关联和属性的克隆行为。通过本文档，你应该能够顺利安装和使用该 gem，并根据需要进行配置和扩展。