active-storage-setup

用途

active-storage-setup 是一个面向 Rails 8 的技能，用于配置 Active Storage 以处理文件上传。当需要为 Rails 应用添加文件上传、图片附件、文档存储，或生成图片变体时使用。

主要能力

根据资料，Active Storage 处理 Rails 中的文件上传，包含以下方面：

云存储（S3、GCS、Azure）或本地磁盘
图片变体（缩略图、尺寸调整）
浏览器直传（Direct uploads）
多态附件（Polymorphic attachments）

使用方式

安装

# Install Active Storage (if not already)
bin/rails active_storage:install
bin/rails db:migrate

添加图片处理：

bundle add image_processing

配置

存储服务通过 config/storage.yml 定义，示例包含：

# config/storage.yml
local:
  service: Disk
  root: <%= Rails.root.join("storage") %>

test:
  service: Disk
  root: <%= Rails.root.join("tmp/storage") %>

amazon:
  service: S3
  access_key_id: <%= Rails.application.credentials.dig(:aws, :access_key_id) %>
  secret_access_key: <%= Rails.application.credentials.dig(:aws, :secret_access_key) %>
  region: eu-west-1
  bucket: <%= Rails.application.credentials.dig(:aws, :bucket) %>

google:
  service: GCS
  credentials: <%= Rails.root.join("config/gcs-credentials.json") %>
  project: my-project
  bucket: my-bucket

环境配置示例：

# config/environments/development.rb
config.active_storage.service = :local

# config/environments/production.rb
config.active_storage.service = :amazon

模型附件

单个附件：

# app/models/user.rb
class User < ApplicationRecord
  has_one_attached :avatar

  # With variant defaults
  has_one_attached :avatar do |attachable|
    attachable.variant :thumb, resize_to_limit: [100, 100]
    attachable.variant :medium, resize_to_limit: [300, 300]
  end
end

多个附件：

# app/models/event.rb
class Event < ApplicationRecord
  has_many_attached :photos

  has_many_attached :documents do |attachable|
    attachable.variant :preview, resize_to_limit: [200, 200]
  end
end

TDD 工作流

Active Storage 进度清单：

Step 1: Add attachment to model
Step 2: Write model spec for attachment
Step 3: Add validations (type, size)
Step 4: Create upload form
Step 5: Handle in controller
Step 6: Display in views
Step 7: Test upload flow

测试附件

参见 testing.md 获取模型 spec、factory traits 和 request spec。关键模式包括：

在 request spec 中使用 fixture_file_upload
使用 after(:build) 定义 :with_avatar factory traits
在模型 spec 中测试 be_attached 与 variant 是否存在

校验

可使用 active_storage_validations gem 进行声明式校验，或编写手动 validate 方法。两种方式详见 validations.md。

# Gemfile
gem 'active_storage_validations'

图片变体

在模型附件上使用 resize_to_fill、resize_to_limit 或 resize_to_cover 定义命名变体。变体操作、视图 helper 和表单示例详见 variants-and-views.md。

控制器与服务处理

单个上传 permit :avatar，多个上传 permit photos: []
使用 purge 移除附件，可选 Turbo Stream 响应
使用 rails_blob_path 或 send_data 进行下载

完整控制器示例、服务方法、直传设置和性能提示详见 controller-and-service.md。

检查清单

Active Storage installed and migrated
Storage service configured
Image processing gem added (if using variants)
Attachment added to model
Validations added (type, size)
Variants defined
Controller permits attachment params
Form handles file upload
Tests written for attachments
Direct uploads configured (if needed)

适用场景

适用于 Rails 8 应用中需要文件上传能力的场景，包括图片附件、文档存储、图片变体生成、多附件的模型（如事件照片、文档）以及需要浏览器直传的场景。

限制

资料中未提供价格、平台兼容范围的完整说明，也未说明具体的性能指标或效果数据。引用文档（testing.md、validations.md、variants-and-views.md、controller-and-service.md）的具体内容未在资料中展开，需查阅对应文件获取完整细节。