Shrine 开源项目教程：Ruby 文件上传的终极解决方案-优快云博客

Shrine 开源项目教程：Ruby 文件上传的终极解决方案

【免费下载链接】shrine File Attachment toolkit for Ruby applications 项目地址: https://gitcode.com/gh_mirrors/sh/shrine

还在为 Ruby 应用的文件上传功能而烦恼吗？面对 CarrierWave、Paperclip、Active Storage 等各种选择，你是否感到困惑？本文将为你详细介绍 Shrine——一个现代化、模块化的 Ruby 文件上传工具包，帮助你构建高效、灵活的文件处理系统。

通过阅读本文，你将获得：

Shrine 的核心概念和架构设计
完整的安装配置指南
文件上传、处理、验证的实战示例
高级功能如直接上传、后台处理、动态处理
与其他解决方案的对比分析

什么是 Shrine？

Shrine 是一个用于 Ruby 应用程序的文件附件处理工具包，具有以下突出特点：

模块化设计 - 插件系统让你只加载需要的功能
内存友好 - 支持流式上传和下载，适合大文件处理
云存储支持 - 支持磁盘、AWS S3、Google Cloud、Cloudinary 等多种存储
灵活的持久化集成 - 支持 Sequel、ActiveRecord、ROM、Hanami、Mongoid 等
强大的处理能力 - 支持即时处理和后台处理

核心架构

Shrine 采用清晰的责任分离设计，避免了传统的 God Object（上帝对象）模式：

mermaid

快速开始

安装配置

首先在 Gemfile 中添加依赖：

# Gemfile
gem "shrine", "~> 3.0"

创建初始化文件 config/initializers/shrine.rb：

require "shrine"
require "shrine/storage/file_system"

# 配置存储
Shrine.storages = {
  cache: Shrine::Storage::FileSystem.new("public", prefix: "uploads/cache"), # 临时存储
  store: Shrine::Storage::FileSystem.new("public", prefix: "uploads")        # 永久存储
}

# 加载插件
Shrine.plugin :activerecord           # Active Record 集成
Shrine.plugin :cached_attachment_data # 跨表单重显保留缓存文件
Shrine.plugin :restore_cached_data    # 重新提取缓存文件的元数据

数据库迁移

为需要附件的表添加 <name>_data 列。例如，为 photos 表添加 image 附件：

rails generate migration add_image_data_to_photos image_data:text

创建上传器

创建上传器类 app/uploaders/image_uploader.rb：

class ImageUploader < Shrine
  # 插件和上传逻辑
end

模型配置

在模型中注册附件：

class Photo < ActiveRecord::Base
  include ImageUploader::Attachment(:image) # 添加 image 虚拟属性
end

完整示例：图片上传系统

让我们构建一个完整的图片上传系统，支持多种尺寸的缩略图生成。

上传器配置

# app/uploaders/image_uploader.rb
require "image_processing/mini_magick"

class ImageUploader < Shrine
  # 允许的文件类型
  ALLOWED_TYPES = %w[image/jpeg image/png image/webp]
  MAX_SIZE = 10 * 1024 * 1024 # 10MB
  MAX_DIMENSIONS = [5000, 5000] # 最大尺寸

  # 缩略图配置
  THUMBNAILS = {
    small:  [300, 300],
    medium: [600, 600], 
    large:  [800, 800]
  }

  # 加载插件
  plugin :remove_attachment
  plugin :pretty_location
  plugin :validation_helpers
  plugin :store_dimensions
  plugin :derivatives
  plugin :default_url

  # 文件验证
  Attacher.validate do
    validate_size 0..MAX_SIZE
    validate_extension %w[jpg jpeg png webp]

    if validate_mime_type ALLOWED_TYPES
      validate_max_dimensions MAX_DIMENSIONS
    end
  end

  # 缩略图处理
  Attacher.derivatives do |original|
    magick = ImageProcessing::MiniMagick.source(original)
    
    THUMBNAILS.transform_values do |(width, height)|
      magick.resize_to_limit!(width, height)
    end
  end

  # 默认URL
  Attacher.default_url do |derivative: nil, **|
    if derivative && THUMBNAILS.key?(derivative)
      "/images/default-#{derivative}.jpg"
    end
  end
end

控制器处理

# app/controllers/photos_controller.rb
class PhotosController < ApplicationController
  def new
    @photo = Photo.new
  end

  def create
    @photo = Photo.new(photo_params)
    
    if @photo.save
      redirect_to @photo, notice: '照片上传成功！'
    else
      render :new
    end
  end

  def show
    @photo = Photo.find(params[:id])
  end

  private

  def photo_params
    params.require(:photo).permit(:image)
  end
end

视图模板

<!-- app/views/photos/new.html.erb -->
<%= form_for @photo, html: { multipart: true } do |f| %>
  <%= f.hidden_field :image, value: @photo.cached_image_data %>
  <%= f.file_field :image %>
  <%= f.submit '上传图片' %>
<% end %>

<!-- app/views/photos/show.html.erb -->
<div class="photo-container">
  <h2>原始图片</h2>
  <%= image_tag @photo.image_url %>
  
  <h2>缩略图</h2>
  <div class="thumbnails">
    <%= image_tag @photo.image_url(:small), class: 'thumbnail' %>
    <%= image_tag @photo.image_url(:medium), class: 'thumbnail' %> 
    <%= image_tag @photo.image_url(:large), class: 'thumbnail' %>
  </div>
  
  <p>文件大小: <%= number_to_human_size(@photo.image.size) %></p>
  <p>尺寸: <%= @photo.image.width %> × <%= @photo.image.height %></p>
</div>

高级功能

直接上传到 S3

为了提高上传性能，可以配置直接上传到 AWS S3：

# config/initializers/shrine.rb
require "shrine/storage/s3"

s3_options = {
  bucket:            ENV['AWS_BUCKET'],
  region:            ENV['AWS_REGION'],
  access_key_id:     ENV['AWS_ACCESS_KEY_ID'],
  secret_access_key: ENV['AWS_SECRET_ACCESS_KEY'],
}

Shrine.storages = {
  cache: Shrine::Storage::S3.new(prefix: "cache", **s3_options),
  store: Shrine::Storage::S3.new(**s3_options)
}

# 加载直接上传插件
Shrine.plugin :presign_endpoint

后台处理

对于大文件处理，使用后台任务：

# config/initializers/shrine.rb
Shrine.plugin :backgrounding

Shrine::Attacher.promote_block do
  PromoteJob.perform_async(
    self.class.name, 
    record.class.name, 
    record.id, 
    name, 
    file_data
  )
end

# app/jobs/promote_job.rb
class PromoteJob
  include Sidekiq::Worker

  def perform(attacher_class, record_class, record_id, name, file_data)
    attacher_class = Object.const_get(attacher_class)
    record = Object.const_get(record_class).find(record_id)
    
    attacher = attacher_class.retrieve(
      model: record, 
      name: name, 
      file: file_data
    )
    attacher.create_derivatives
    attacher.atomic_promote
  end
end

动态处理

支持按需生成处理版本：

class ImageUploader < Shrine
  plugin :derivation_endpoint, secret_key: ENV['DERIVATION_SECRET']
  
  derivation :thumbnail do |file, width, height|
    ImageProcessing::MiniMagick
      .source(file)
      .resize_to_limit!(width.to_i, height.to_i)
  end
end

# 在路由中挂载
Rails.application.routes.draw do
  mount ImageUploader.derivation_endpoint => "/derivations/image"
end

功能对比

下表展示了 Shrine 与其他流行文件上传解决方案的对比：

特性	Shrine	CarrierWave	Paperclip	Active Storage
模块化设计	✅	❌	❌	✅
内存友好	✅	❌	❌	✅
云存储支持	✅	✅	✅	✅
多ORM支持	✅	❌	❌	❌
即时处理	✅	❌	❌	✅
后台处理	✅	✅	✅	✅
直接上传	✅	❌	❌	✅
校验系统	✅	✅	✅	✅

最佳实践

1. 文件验证策略

class DocumentUploader < Shrine
  plugin :validation_helpers
  
  Attacher.validate do
    # 基本验证
    validate_max_size 50 * 1024 * 1024 # 50MB
    validate_extension %w[pdf doc docx]
    
    # 条件验证
    if validate_mime_type %w[application/pdf application/msword]
      # PDF 特定验证
      if mime_type == 'application/pdf'
        validate_with -> (file) {
          # 自定义PDF验证逻辑
          PdfValidator.valid?(file)
        }
      end
    end
  end
end

2. 自定义元数据提取

class ImageUploader < Shrine
  plugin :add_metadata
  
  add_metadata :exif_data do |io|
    if image?(io)
      MiniExif.read(io.path)
    end
  end
  
  add_metadata :color_palette do |io|
    if image?(io)
      ImagePalette.extract(io.path)
    end
  end
  
  private
  
  def image?(io)
    mime_type = Marcel::MimeType.for(io)
    mime_type.start_with?('image/')
  end
end

3. 多存储策略

# 根据文件类型选择不同存储
class CustomUploader < Shrine
  plugin :default_storage
  
  def choose_storage(io, record: nil, name: nil, **)
    case name
    when :avatar
      :avatar_store
    when :document
      :document_store
    else
      :store
    end
  end
end

# 配置多个存储
Shrine.storages = {
  cache: Shrine::Storage::FileSystem.new("public", prefix: "uploads/cache"),
  store: Shrine::Storage::S3.new(bucket: 'general'),
  avatar_store: Shrine::Storage::S3.new(bucket: 'avatars'),
  document_store: Shrine::Storage::S3.new(bucket: 'documents')
}

故障排除

常见问题及解决方案

问题	原因	解决方案
文件上传失败	存储配置错误	检查存储配置和权限
缩略图未生成	处理超时	启用后台处理
验证不生效	插件未正确加载	检查插件加载顺序
直接上传失败	CORS 配置问题	配置正确的 CORS 策略

性能优化建议

启用 CDN：为云存储配置 CDN 加速访问
使用 libvips：替代 ImageMagick 获得更好的性能
合理配置缓存：设置适当的缓存策略
监控处理时间：对长时间处理启用后台任务

总结

Shrine 为 Ruby 应用程序提供了一个现代化、灵活且强大的文件上传解决方案。通过其模块化的插件系统、清晰的架构设计和丰富的功能集，Shrine 能够满足从简单图片上传到复杂文件处理管道的各种需求。

关键优势包括：

🎯 模块化设计 - 只加载需要的功能，减少内存占用
⚡ 高性能 - 流式处理和内存友好设计
🌐 多存储支持 - 从本地磁盘到各种云存储
🔧 灵活性 - 支持自定义处理和验证逻辑
📦 生态系统 - 丰富的插件和扩展支持

无论你是构建简单的博客系统还是复杂的企业应用，Shrine 都能提供可靠的文件上传解决方案。通过本文的指南和示例，你应该能够快速上手并在项目中实施 Shrine。

下一步行动：

在你的项目中安装 Shrine
根据需求配置合适的存储和插件
实现基本的文件上传功能
逐步添加高级功能如直接上传、后台处理等

开始使用 Shrine，体验现代化文件上传的便捷与强大！

【免费下载链接】shrine File Attachment toolkit for Ruby applications 项目地址: https://gitcode.com/gh_mirrors/sh/shrine

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考