Couch Potato 技术文档

1. 安装指南

1.1 安装 Couch Potato Gem

Couch Potato 是一个用于 CouchDB 的 Ruby 持久层库。你可以通过以下命令安装 Couch Potato：

gem install couch_potato

1.2 在 Ruby 应用程序中使用

在你的 Ruby 应用程序中，首先需要引入 Couch Potato：

require 'rubygems'
require 'couch_potato'

然后配置数据库名称：

CouchPotato::Config.database_name = 'name_of_the_db'

默认情况下，服务器 URL 为 http://localhost:5984/，你可以通过以下方式指定数据库主机和名称：

CouchPotato::Config.database_host = "http://example.com:5984"
CouchPotato::Config.database_name = "name_of_the_db"

或者使用带有认证的 URL：

CouchPotato::Config.database_name = "http://username:[e-mail]:5984/name_of_the_db"

1.3 在 Rails 中使用

在 Rails 项目中，创建一个 config/couchdb.yml 文件：

default: &default
  split_design_documents_per_view: true # 可选，默认是 false
  digest_view_names: true # 可选，默认是 false
  default_language: :erlang # 可选，默认是 javascript
  database_host: "http://127.0.0.1:5984"

development:
  <<: *default
  database: development_db_name
test:
  <<: *default
  database: test_db_name
production:
  <<: *default
  database: <%= ENV['DB_NAME'] %>
  additional_databases:
    db1: db1_production
    db2: https://db2.example.com/db

在 Gemfile 中添加以下依赖：

gem 'railties'
gem 'actionpack'
gem 'actionmailer'
gem 'activemodel'
gem "couch_potato"
gem 'tzinfo'

2. 项目使用说明

2.1 保存和加载对象

首先，定义一个类：

class User
end

为了使该类的实例持久化，需要包含 CouchPotato::Persistence 模块：

class User
  include CouchPotato::Persistence
end

如果需要存储属性，必须声明它们：

class User
  include CouchPotato::Persistence

  property :name
end

属性可以指定类型：

class User
  include CouchPotato::Persistence

  property :address, :type => Address
end

2.2 数据库操作

所有数据库操作都封装在 CouchPotato::Database 类中。你可以保存对象：

user = User.new :name => 'joe'
CouchPotato.database.save_document user # 或者 save_document!

也可以加载对象：

CouchPotato.database.load_document "id_of_the_user_document" # => <#User 0x3075>

2.3 处理冲突

CouchDB 使用 MVCC 来检测写冲突。如果发生冲突，Couch Potato 会自动重新加载文档并重试保存：

CouchPotato.database.save_document user do |user|
  user.name = 'joe'
end

2.4 缓存加载请求

你可以为数据库实例添加缓存，以缓存后续的 #load 调用：

db = CouchPotato.database
db.cache = {}
db.load '1'
db.load '1' # 从缓存中获取，而不是数据库

3. 项目 API 使用文档

3.1 属性访问

你可以通过正常的属性访问器访问声明的属性：

user.name # => 'joe'
user.name = {:first => ['joe', 'joey'], :last => 'doe', :middle => 'J'}
user._id # => "02097f33a0046123f1ebc0ebb6937269"
user._rev # => "2769180384"
user.created_at # => Fri Oct 24 19:05:54 +0200 2008
user.updated_at # => Fri Oct 24 19:05:54 +0200 2008
user.new? # => false

3.2 脏跟踪

CouchPotato 跟踪属性的脏状态，类似于 ActiveRecord：

user = User.create :name => 'joe'
user.name # => 'joe'
user.name_changed? # => false
user.name_was # => nil

你可以强制设置脏状态：

user.name = 'jane'
user.name_changed? # => true
user.name_not_changed
user.name_changed? # => false
CouchPotato.database.save_document user # 不会执行任何操作，因为没有属性是脏的

3.3 深度脏跟踪

你可以选择启用更高级的脏跟踪，以便更可靠地检查数组和嵌入文档属性的变化：

class User
  include CouchPotato::DeepDirtyAttributes
end

4. 项目安装方式

4.1 通过 Gem 安装

gem install couch_potato

4.2 在 Ruby 应用程序中配置

require 'rubygems'
require 'couch_potato'

CouchPotato::Config.database_name = 'name_of_the_db'

4.3 在 Rails 中配置

创建 config/couchdb.yml 文件，并在 Gemfile 中添加依赖。