Директория документов в мобильном приложении — что это, назначение и как организовать хранение

Что такое директория документов приложения?

Директория документов — это специализированное хранилище внутри песочницы приложения, предназначенное для постоянного хранения пользовательских файлов. В отличие от кэша, файлы в этой директории считаются важными для пользователя: они не удаляются системой при нехватке места, сохраняются при обновлении приложения и резервируются при синхронизации устройства. На iOS директория Documents является частью Sandbox-контейнера и автоматически включается в резервное копирование iCloud. На Android прямого аналога нет — эквивалентом служит context.filesDir, который также предназначен для постоянных файлов, но не имеет встроенного механизма резервного копирования.

Различие между директорией документов и внутренним хранилищем (Internal Storage) на Android минимально: оба расположены в песочнице приложения, оба удаляются при деинсталляции, оба недоступны другим приложениям. Основное различие — семантическое: Documents Directory предполагает, что файлы созданы или импортированы пользователем, в то время как Internal Storage может содержать внутренние файлы приложения (базы данных, конфигурации). На iOS различие более существенное: Documents автоматически резервируется, а Library/Application Support — нет. Это влияет на стратегию хранения: в Documents помещайте только то, что пользователь хочет восстановить на новом устройстве, а в Application Support — внутренние данные, которые приложение может воссоздать.

Архитектура песочницы гарантирует, что другие приложения не имеют доступа к директории документов вашего приложения. На iOS доступ к Documents других приложений невозможен без jailbreak. На Android root-доступ позволяет читать filesDir любого приложения, поэтому конфиденциальные данные (токены, ключи шифрования) необходимо дополнительно защищать с помощью EncryptedSharedPreferences или EncryptedFile из библиотеки AndroidX Security.

Какие данные хранят в директории документов

В директорию документов следует помещать данные, которые представляют ценность для пользователя и должны быть доступны после перезапуска приложения или восстановления устройства. Не все файлы подходят для хранения в этой директории — выбор зависит от типа данных и сценария использования.

Пользовательские документы и файлы

Пользовательские файлы — основной контент директории документов. Это могут быть текстовые документы, созданные в редакторе, изображения, снятые камерой приложения, экспортированные PDF-отчёты, аудиозаписи, заметки. Каждый такой файл создан пользователем или по его запросу и должен быть доступен в любой момент. На iOS файлы из Documents отображаются в системном приложении Files, что позволяет пользователю управлять ими через стандартный файловый менеджер. На Android аналогичного отображения нет — приложение самостоятельно должно предоставить интерфейс для просмотра сохранённых файлов.

Базы данных и настройки приложения

Базы данных SQLite и файлы настроек обычно хранятся рядом с директорией документов, но не в ней самой. На iOS базы данных размещают в Library/Application Support, так как они не должны отображаться в приложении Files и резервироваться отдельно. На Android базы данных по умолчанию создаются в /data/data/<package>/databases/ через Room или SQLiteOpenHelper. Если база данных содержит пользовательский контент (заметки, дневник, финансовые записи), можно разместить её в filesDir, чтобы обеспечить резервирование через систему. Room позволяет указать кастомную директорию для хранения базы данных через callback RoomDatabase.Builder.

val dbFile = File(context.filesDir, "user_database.db")

val db = Room.databaseBuilder<AppDatabase>(
    context,
    dbFile.absolutePath
).build()

Экспортированные и импортированные данные

Файлы, которые пользователь импортирует из других приложений или экспортирует из вашего приложения, также должны сохраняться в директории документов. На iOS импорт через UIDocumentPickerViewController автоматически помещает копию файла в Documents при использовании параметра asCopy: true. На Android импорт через SAF-диалог также создаёт копию файла в песочнице приложения. При экспорте данных (например, создание CSV-файла с контактами) сохраняйте файл сначала в Documents/filesDir, а затем предлагайте пользователю поделиться им через Share Sheet. Это гарантирует, что даже если пользователь забудет сохранить файл после отправки, копия останется в приложении для последующего использования.

Как работать с директорией документов на Android

На Android функции директории документов выполняет context.filesDir. Дополнительно доступна директория context.externalFilesDir на SD-карте, но она не гарантирует сохранность данных. Рассмотрим основные приёмы работы с этими директориями.

Доступ и управление файлами через filesDir

filesDir — основная директория для постоянных файлов приложения на Android. Она находится в песочнице приложения и полностью удаляется при деинсталляции. Для получения экземпляра File используйте context.filesDir, который возвращает путь к каталогу /data/data/<package>/files/. Для создания и чтения файлов используйте стандартные Java/Kotlin File-операции или Context-методы openFileInput() и openFileOutput(), которые принимают имя файла и возвращают FileInputStream/FileOutputStream. Метод openFileOutput() автоматически создаёт файл в filesDir, если он ещё не существует, и позволяет указать режим доступа: MODE_PRIVATE (только текущее приложение), MODE_APPEND (дозапись) или MODE_WORLD_READABLE (устарел, не используется с API 24+).

val fileName = "report.pdf"
val content = "PDF content".toByteArray()

context.openFileOutput(fileName, Context.MODE_PRIVATE).use { stream ->
    stream.write(content)
}

val bytes = context.openFileInput(fileName).use { stream ->
    stream.readBytes()
}

Особенности хранения на Android 10+

На Android 10+ модель Scoped Storage не влияет на filesDir — доступ к собственной песочнице приложения остаётся полным. Все операции чтения и записи внутри filesDir не требуют дополнительных разрешений. Однако при попытке доступа к файлам другого приложения через filesDir вы получите исключение. Для обмена файлами используйте FileProvider, который создаёт временный content URI для передачи файла другому приложению. FileProvider объявляется в AndroidManifest.xml через тег <provider> и конфигурируется в XML-файле путей. Это стандартный механизм для передачи файлов между приложениями, используемый, например, при отправке изображения через Intent с ACTION_SEND.

Как работать с директорией документов на iOS

На iOS Documents Directory — это часть Sandbox-контейнера приложения с особым статусом. Файлы из этой директории автоматически включаются в резервное копирование iCloud, отображаются в приложении Files и сохраняются при обновлении приложения через App Store.

Documents Directory и резервное копирование

Автоматическое резервирование Documents — ключевое преимущество iOS. Когда пользователь подключает устройство к iTunes или включает iCloud Backup, все файлы из Documents/ копируются в резервную копию. При восстановлении на новом устройстве пользователь получает все свои файлы без дополнительных действий. Однако это преимущество становится недостатком, если приложение хранит в Documents большие объёмы данных: время резервного копирования увеличивается, а объём iCloud-хранилища может быстро закончиться. Поэтому в Documents следует хранить только те файлы, которые действительно нужны пользователю при восстановлении. Временные файлы, кэш и воссоздаваемые данные должны находиться в Caches или Library/Application Support. Apple рекомендует исключать из резервного копирования файлы, которые можно повторно загрузить из интернета, через атрибут isExcludedFromBackup.

let fm = FileManager.default
let docsURL = fm.urls(
    for: .documentDirectory,
    in: .userDomainMask
).first!

let fileURL = docsURL.appendingPathComponent("notes.txt")
let text = "Содержание заметки"
try text.write(to: fileURL, atomically: true, encoding: .utf8)

iCloud Drive и синхронизация между устройствами

iCloud Drive позволяет синхронизировать файлы из Documents между устройствами одного пользователя. Для включения синхронизации приложение должно использовать API NSDocument или UIDocument, которые автоматически управляют версионированием и разрешением конфликтов. Альтернативный подход — использование iCloud с помощью CloudKit, который предоставляет более гибкий контроль над синхронизацией, но требует настройки на CloudKit Dashboard. При использовании iCloud Drive убедитесь, что вы корректно обрабатываете конфликты редактирования (merge или last-write-wins) и информируете пользователя о состоянии синхронизации через интерфейс приложения. iCloud не гарантирует мгновенную синхронизацию — задержка может составлять от нескольких секунд до нескольких минут в зависимости от размера файла и качества соединения. Для критически важных данных используйте транзакционную запись и версионирование, чтобы при конфликте можно было восстановить предыдущую версию файла.

Отличия от Cache Directory и лучшие практики

Правильный выбор между Documents Directory и Cache Directory определяет надёжность хранения пользовательских данных. Ошибка в выборе приводит либо к потере данных (если важные файлы хранятся в кэше), либо к переполнению резервной копии (если временные файлы хранятся в Documents).

Лучшие практики использования директории документов включают несколько ключевых правил. Во-первых, всегда запрашивайте подтверждение пользователя перед удалением файлов из этой директории. В отличие от кэша, удаление документа может привести к безвозвратной потере пользовательского контента. Во-вторых, реализуйте версионирование файлов: при перезаписи существующего файла сохраняйте предыдущую версию с суффиксом _backup или используйте Snapshot-механизмы. В-третьих, предоставьте пользователю интерфейс для просмотра, переименования, удаления и экспорта файлов из директории документов. На iOS файлы из Documents автоматически отображаются в Files, на Android необходимо реализовать собственный файловый менеджер или использовать сторонние библиотеки.

Отдельное внимание уделите миграции данных при обновлении приложения. Если новая версия меняет структуру хранения файлов (например, переносит данные из одной поддиректории в другую или изменяет формат файлов), реализуйте одноразовую миграцию при первом запуске после обновления. Храните номер версии схемы данных в SharedPreferences и при несовпадении запускайте миграцию. Не удаляйте старые файлы до завершения миграции — в случае сбоя пользователь не должен потерять данные. Если миграция включает преобразование формата (например, переход с JSON на SQLite), сохраняйте исходные файлы как резервную копию в отдельной директории с датой миграции. Пользователь должен иметь возможность откатить изменения через настройки приложения в течение первых 30 дней после обновления, как рекомендует Apple Human Interface Guidelines.