Это вторая часть из серии постов о Shrine. Цель этой серии статей – показать преимущества Shrine над существующими загрузчиками файлов.
В предыдущем посте я говорил о том что мотивировало меня на создание Shrine. В этой статье я хочу показать вам фундамент, на котором основан Shrine — хранилище, загрузчик и загруженные файлы.
Хранилище
«Хранилище» Shrine — это plain Ruby-объект, который инкапсулирует управление файлами в определенном сервисе хранения (файловая система, S3 и.т.д). Хранилище должно содержать следующие 5 методов:
class MyStorage
def upload(io, id, **options)
# выгружает `io` в указанный `id`
end
def url(id)
# возвращает URL-адрес файла с `id`
end
def open(id)
# возвращает файл по адресу `id` в качестве объекта типа IO
end
def exists?(id)
# возвращает, существование файла в хранилище
end
def delete(id)
# удаляет соответствующий файл из хранилища
end
end
Хранилища Shrine конфигурируются напрямую, передавая опции в конструктор (позаимствовано у Refile) и должны быть зарегистрированы в Shrine.storages:
Shrine.storages[:s3] = Shrine::Storage::S3.new(
access_key_id: "abc",
secret_access_key: "xyz",
region: "eu-west-1",
bucket: "my-bucket",
)
В настоящее время для Shrine имеются поддержка файловой системы, S3, Fog, Flickr, Cloudary, Transloadit, Uploadcare, Imgix, GridFS и SQL, так что выбирайте.
Вы также можете легко написать свое хранилище, для этого есть руководство и линтер, который автоматически проверит, правильно ли все работает.
Загрузчик
Загрузчики являются подклассами Shrine, они инкапсулируют логику выгрузки определенного вложения (как у CarrierWave).
class ImageUploader < Shrine
# image uploading logic goes here
end
Объекты Uploader выступают в качестве оберток вокруг хранилища, в них выполняется вся логика для загрузки, которая является общей для любого хранилища:
- Обработка
- Извлечение метаданных
- Генерация локации для файла
- Загрузка (на этом этапе происходит обращение к хранилищу)
- Закрытие загруженного файла
Создание экземпляра загрузчика с установленным параметром хранилища:
Shrine.storages[:disk] = Shrine::Storage::FileSystem.new(...)
uploader = ImageUploader.new(:disk)
uploader.upload(image) #=> #<Shrine::UploadedFile>
Загрузчики не знают о моделях; Они только работают с файлом, который будет загружен на вход, и возвращают представление загруженного файла на выходе. Поскольку это предполагает, что загрузчики являются stateless, это делает их поведение очень предсказуемым.
Загруженные файлы
Когда файл загружается через загрузчик, метод
#upload возвращает объект Shrine::UploadedFile. Этот объект является полным представлением файла, который был загружен в хранилище.
uploaded_file = uploader.upload(image) #=> #<Shrine::UploadedFile>
uploaded_file.id #=> "43ksd9gkafg0dsl.jpg"
uploaded_file.storage #=> #<Shrine::Storage::FileSystem>
uploaded_file.metadata #=> {...}
Так как этот объект знает, куда он был загружен, он может предоставить много полезных методов:
uploaded_file.url # generates the URL
uploaded_file.download # downloads the file to the disk
uploaded_file.exists? # asks the storage if file exists
uploaded_file.open { |io| ... } # opens the file for reading
uploaded_file.delete # deletes the file from the storage
Этот объект определяется только хешем. Поскольку на хранилище можно ссылаться по его установленному параметру, этот хэш теперь может быть сериализован в JSON и сохранен в столбце базы данных.
uploaded_file.data #=>
# {
# "id" => "df9fk48saflg.jpg",
# "storage" => "disk",
# "metadata" => {...}
# }
uploaded_file.to_json #=> '{"id":"df9fk48saflg.jpg","storage":"disk","metadata":{...}}'
Объекты Shrine::UploadedFile не зависят от загрузчиков. Это значительное отличие от CarrierWave и Paperclip, которые имеют такую зависимость с классами CarrierWave::Uploader::Base и Paperclip::Attachment.
Абстракция IO
Shrine может загрузить любой объект типа
IO, который отвечает на #read, #size, #rewind, #eof? И #close (как у Refile). Определяя этот строгий интерфейс, каждая функция Shrine теперь знает, что они могут полагаться только на эти методы, а это значит, что они будут работать правильно независимо от того, загружаете ли вы типы File, StringIO, ActionDispatch::Http::UploadedFile, Rack или удаленные файлы, которые загружаются стримом.
Кроме того, Shrine::UploadedFile сам по себе является объектом типа IO, обертывая любой загруженный файл под тем же унифицированным интерфейсом. Это делает перемещение файла с одного хранилища на другое действительно удобным. Кроме того, это позволяет оптимизировать некоторые закачки путем пропуска процесса скачивания и повторной загрузки, например, использовать копию S3, если оба файла из S3, или просто отправить запрос URL, если хранилище поддерживает его.
cache = ImageUploader.new(:s3_temporary)
cached_file = cache.upload(image)
store = ImageUploader.new(:s3_permanent)
store.upload(cached_file) #=> performs an S3 COPY request
Система плагинов
Shrine поставляется с небольшим ядром (<500 строк кода), которое обеспечивает необходимую функциональность. Любые дополнительные функции могут быть загружены через плагины. Это дает вам гибкость в выборе именно того, что и как должен делать для вас Shrine, и загружать код только для функционала, который вы используете.
# Loads the processing feature from "shrine/plugins/logging.rb"
Shrine.plugin :logging, logger: Rails.logger
Shrine поставляется с более чем 35 плагинами, и вы легко можете написать свои собственные. Плагиновая система Shrine — это адаптация Roda, о которой я писал в прошлом.
Кроме того, загрузчики Shrine могут наследоваться (в отличие от CarrierWave).
Shrine.plugin :logging # enables logging for all uploaders
class ImageUploader < Shrine
plugin :backup # stores backups only for this uploader (and its descendants)
end
Зависимости
Большинство библиотек для загрузки файлов, имеют довольно монструозные зависимости.
CarrierWave
- ActiveSupport – Я действительно не хочу всех этих манки-патчей
- ActiveModel – Почему бы не выполнять валидацию без библиотек?
- MIME::Types – Лучше определить MIME-тип из содержимого файла
Paperclip
- ActiveSupport – Опять же, я хочу иметь возможность не иметь никаких манки-патчей
- ActiveModel – Окей, любом случае, как ActiveModel, так и ActiveSupport требуются для ActiveRecord
- Cocaine – Open3 монструозная библиотека для запуска командной оболочки
- MIME::Types – Обнаружение подмены MIME-типа имеет проблемы
- MimeMagic – достаточно утилиты file
Refile
- RestClient – Монструозное решение для простой загрузки файлов
- Sinatra – Это нормально, хотя Roda – более легкая альтернатива
- MIME::Types – Лучше определить MIME-тип из содержимого файла
Shrine, с другой стороны, имеет только одну обязательную но легкую зависимость — Down. Down — это net/http обертка для загрузки файлов, которая улучшает open-uri и поддерживает стриминг, и используется почти всеми хранилищами Shrine.
Кроме того, Shrine в целом загружается очень быстро, потому что вы загружаете код только для функционала, который вы используете. Для других загрузчиков требуется загрузить код для всего функционала, которые может вам не понадобиться. К примеру, Shrine загружается в 35 раз быстрее CarrierWave без загруженных плагинов и в 7 раз быстрее со всеми загруженными (исходник) плагинами.
Итоги
Каждый высокоуровневый интерфейс должен иметь хороший фундамент. Таким образом, c каким бы уровнем абстракции вы не работали, вы всегда сможете понять, что происходит. Основа Shrine состоит из классов Storage, Shrine и Shrine::UploadedFile, каждый из которых имеет четко определенный интерфейс и обязанность.
Оригинал: https://twin.github.io/better-file-uploads-with-shrine-uploader/
Cтатьи из оригинальной серии в блоге автора библиотеки:
- Better File Uploads with Shrine: Attachment
- Better File Uploads with Shrine: Processing
- Better File Uploads with Shrine: Metadata
Автор: amerov
