CouchRest-Rails 技术文档

本文档旨在帮助用户安装、使用和详细了解 CouchRest-Rails 项目。以下是文档的主要内容：

1. 安装指南

在开始安装之前，请确保您的环境中已经安装了以下依赖项：

• CouchRest gem
• Validatable gem
• JSON gem
• RSpec BDD 框架（可选，用于运行插件规范）
• RSpec-Rails 库（可选，用于运行插件规范）
• Lucene（可选，用于全文搜索 CouchDB 文档）

安装 CouchRest-Rails 插件：

使用 Rails 插件安装脚本进行安装：

script/plugin install git://github.com/hpoydar/couchrest-rails.git

或者直接将其添加到 vendor/plugins 目录中，并生成所需的文件：

script/generate couch_rest_rails

安装过程将创建两个文件夹：

• db/couch/：用于存储 CouchDB 数据库信息、映射和减少函数（视图）
• test/fixtures/couch：用于存储和加载 CouchDB 固件（yaml）

这些路径可以在初始化程序或环境配置文件中进行自定义：

CouchRestRails.fixtures_path = 'custom/path/to/your/fixtures/from/app/root'
CouchRestRails.views_path     = 'custom/path/to/your/views/from/app/root'

安装过程还将创建一个 config/couchdb.yml 文件用于自定义配置。

2. 项目使用说明

配置

可以通过自定义 couchdb.yml 文件来适应您特定的 CouchDB 安装。建议指定一个 database_prefix 以便于在 CouchDB 服务器上命名数据库，这样更容易通过 Sofa 查看服务器上的数据库。

在 CouchRestRails::Document 模型中定义数据库名称。具体请参见下文 "CouchRestRails 文档模型"。

Rake 任务

使用 Rake 任务创建、删除、重置数据库、推送视图和加载固件：

rake couchdb:create[database]             # 根据当前环境的 config/couchdb.yml 创建 CouchDB 数据库（无需数据库参数即可使用所有定义在 CouchRestRails::Document 模型中的数据库）
rake couchdb:delete[database]             # 删除当前 RAILS_ENV 的 CouchDB 数据库（无需数据库参数即可使用所有定义在 CouchRestRails::Document 模型中的数据库）
rake couchdb:fixtures:load[database]      # 将固件加载到当前环境的 CouchDB 数据库中（无需数据库参数即可使用所有定义在 CouchRestRails::Document 模型中的数据库）
rake couchdb:lucene:push[database]        # 将 Lucene 视图推送到当前环境的 CouchDB 数据库中（无需数据库参数即可使用所有定义在 CouchRestRails::Document 模型中的数据库）
rake couchdb:views:push[database]         # 将视图推送到当前环境的 CouchDB 数据库中（无需数据库参数即可使用所有定义在 CouchRestRails::Document 模型中的数据库）
rake doc:plugins:couchrest-rails          # 为 couchrest-rails 插件生成文档

CouchRestRails 文档模型

对于模型，请继承 CouchRestRails::Document，它会将 CouchRest::ExtendedDocument 钩接到您的 CouchDB 后端，并包含 Validatable 模块：

class YourCouchDocument < CouchRestRails::Document
  use_database :database_name

  property  :email
  property  :question
  property  :answer
  property  :rating

  timestamps!

  view_by :email

  validates_presence_of :question
  validates_numericality_of :rating

  ...
end

确保您在模型中定义了数据库，使用 use_database :<database_name> 指令。

有关 CouchRest::ExtendedDocument 的更多信息，请参阅 CouchRest 文档和规范。

CouchDB 视图

将自定义视图（在您的 CouchRestRails::Document 模型中定义的视图之外）推送到 CouchDB 数据库/服务器实例时，应采用以下格式：

db/couch/<database_name>/views
                               |-- <design_document_name>
                                   |-- <view_name>
                                       |-- map.js
                                       `-- reduce.js

通过 Rake (rake couchdb:views:push) 或者在代码或控制台中推送视图 (CouchRestRails::Views.push)。

测试、规范和固件

对于测试或规范，使用以下帮助方法来设置和拆卸测试数据库和固件：

CouchRestRails::Tests.setup
CouchRestRails::Tests.teardown

还有一些简单的匹配器可供您在规范中使用。请参阅 spec/lib/matchers。

您可以在以下路径模式中将固件存储为 Yaml 文件：

test/fixtures/couch/<database_name>.yml

您可以在初始化程序或环境文件中自定义此路径：

CouchRestRails.fixtures_path = 'custom/path/to/your/fixtures'

Rails 集成单元测试

通过 Rake (rake couchdb:fixtures:dump[<database_name>]) 或者在代码或控制台中创建固件文件 (CouchRestRails::Fixtures.dump[<database_name>])。

将固件添加到 Rails 测试：

class RailsTest < Test::Unit::TestCase
  couchdb_fixtures :<database_name>

  ...
end

Lucene

如果您想支持 CouchDB 文档的 Lucene 全文搜索，请在初始化程序或环境配置文件中启用对它的支持：

CouchRestRails.use_lucene = true

每个数据库的 Lucene 设计文档与视图存储在一起：

db/couch/<database_name>/lucene
                               |-- <design_document_name>
                                   |-- <lucene_search>.js
                                   |-- <lucene_search>.js
                                   |-- ...

您还可以自定义此路径：

CouchRestRails.lucene_path = 'custom/path/to/your/lucene/docs/from/app/root'

通过 Rake (rake couchdb:lucence:push) 或者在代码或控制台中推送您的 Lucene 文档。

3. 项目 API 使用文档

CouchRest-Rails 提供了一系列的 API 用于操作 CouchDB。以下是一些主要 API 的简要说明：

• CouchRestRails::Document：继承此类以创建 CouchDB 文档模型。
• CouchRestRails::Views：用于推送和操作 CouchDB 视图。
• CouchRestRails::Lucene：用于推送和操作 Lucene 设计文档。
• CouchRestRails::Tests：用于测试中的设置和拆卸。

更多详细信息，请参阅项目代码和 Rake 任务。

4. 项目安装方式

CouchRest-Rails 的安装方式已在 "安装指南" 一节中进行了说明。以下是简要步骤：

1. 确保安装了所有依赖项。
2. 使用 Rails 插件安装脚本或手动添加到 vendor/plugins 目录。
3. 生成配置文件和必要文件。

请按照 "安装指南" 一节的详细步骤进行操作。