CarrierWave for Mongoid 技术文档

1. 安装指南

1.1 安装最新版本

你可以通过以下命令安装 carrierwave-mongoid 的最新版本：

gem install carrierwave-mongoid

1.2 在代码中引入

在你的代码中引入 carrierwave-mongoid：

require 'carrierwave/mongoid'

1.3 在 Rails 项目中安装

如果你使用的是 Rails 项目，可以将以下内容添加到 Gemfile 中：

gem 'carrierwave-mongoid', :require => 'carrierwave/mongoid'

注意：如果你使用的是 Rails 4，请确保 mongoid-grid_fs 的版本 >= 1.9.0。如果不确定，可以运行以下命令更新：

gem 'mongoid-grid_fs', github: 'ahoward/mongoid-grid_fs'

2. 项目的使用说明

2.1 快速开始

首先，按照 CarrierWave 主仓库 中的“快速开始”指南进行操作。

接下来，你可以通过将文件赋值给模型的属性来缓存文件，文件会在保存记录时自动存储。例如：

u = User.new
u.avatar = File.open('somewhere')
u.save!

2.2 使用 MongoDB 的 GridFS 存储

在你的上传器中，将存储设置为 :grid_fs：

class AvatarUploader < CarrierWave::Uploader::Base
  storage :grid_fs
end

你还可以配置 CarrierWave 使用 Mongoid 的数据库连接，并将所有存储默认设置为 GridFS。配置示例如下：

CarrierWave.configure do |config|
  config.storage = :grid_fs
  config.root = Rails.root.join('tmp')
  config.cache_dir = "uploads"
end

3. 项目 API 使用文档

3.1 上传文件的访问

由于 GridFS 不通过 HTTP 提供文件访问，你需要自己处理文件的流式传输。例如，在 Rails 中，你可以使用 send_data 方法：

class UsersController < ApplicationController
  def avatar
    content = @user.avatar.read
    if stale?(etag: content, last_modified: @user.updated_at.utc, public: true)
      send_data content, type: @user.avatar.file.content_type, disposition: "inline"
      expires_in 0, public: true
    end
  end
end

# 在 routes.rb 中
resources :users do
  get :avatar, on: :member
end

你可以通过设置 grid_fs_access_url 来告诉 CarrierWave 你将从哪个 URL 提供图像访问：

CarrierWave.configure do |config|
  config.grid_fs_access_url = "/systems/uploads"
end

3.2 路由配置

如果你希望使用 #url 方法来获取上传文件的 URL，你需要进行一些额外的配置。

假设你在 User 模型上挂载了一个 avatar 上传器，并且定义了一个 GridfsController。假设你的上传器定义（即 app/uploaders/avatar_uploader.rb）中的 store_dir 如下：

def store_dir
  "#{model.class.to_s.underscore}/#{mounted_as}/#{model.id}"
end

如果 grid_fs_access_url（在 config/initializers/carrierwave.rb 中）设置为：

config.grid_fs_access_url = '/uploads/grid'

你需要在 config/routes.rb 中定义如下路由：

match '/uploads/grid/user/avatar/:id/:filename' => 'gridfs#avatar'

现在，user.avatar.url 将返回一个可以在视图中使用的 URL 路径。

3.3 不同版本的上传文件

如果你需要包含不同版本的文件（例如缩略图），可以通过额外的路由来实现：

match '/uploads/grid/user/avatar/:id/:filename' => 'gridfs#thumb_avatar', constraints: { filename: /thumb.*/ }

4. 项目安装方式

4.1 通过 Gemfile 安装

在 Rails 项目中，推荐通过 Gemfile 安装 carrierwave-mongoid：

gem 'carrierwave-mongoid', :require => 'carrierwave/mongoid'

4.2 手动安装

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

gem install carrierwave-mongoid

4.3 依赖管理

确保你的项目中安装了正确版本的 mongoid-grid_fs，特别是在使用 Rails 4 时：

gem 'mongoid-grid_fs', github: 'ahoward/mongoid-grid_fs'

5. 已知问题和限制

请注意，嵌入文档中挂载的文件在保存父文档时不会被保存。默认情况下，Mongoid 不会在嵌入文档上触发回调。为了保存嵌入文档中的附件文件，你需要手动处理回调。

---

以上是 CarrierWave for Mongoid 的技术文档，涵盖了安装指南、使用说明、API 文档以及安装方式。希望这份文档能帮助你更好地理解和使用该项目。