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

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

Директорията за документи — специализирано хранилище в пясъчника на приложението, предназначено за постоянно съхранение на потребителски файлове. За разлика от кеша, файловете в тази директория се считат за важни за потребителя: не се изтриват от системата при липса на място, запазват се при актуализация на приложението и се архивират при синхронизация на устройството. На 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 позволява да се посочи персонализирана директория за съхранение на базата данни чрез обратното извикване 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/. За създаване и четене на файлове използвайте стандартни File операции в Java/Kotlin или 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.