Documents Directory: какво е, предназначение и достъп до файлове

Какво е Documents Directory в iOS?

Documents Directory — е директория вътре в пясъчницата на iOS приложението, предназначена за съхраняване на потребителски данни, които трябва да се съхраняват между пускането и да са на разположение на потребителя. Всяко приложение получава собствена изолирана пясъчница, а Documents е един от ключовите директории наред с Caches, tmp и Library.

iOS използва строга пясъчница: приложението няма достъп до файловата система на други приложения и системните директории без специални разрешения. Documents Directory — единствената директория, чието съдържание потребителят може да прегледа чрез iTunes File Sharing (при активиране на съответния ключ UIFileSharingEnabled в Info.plist).

Според данните на Apple WWDC 2023, над 85% от приложенията в App Store използват Documents Directory за съхраняване на поне един тип потребителски данни — от експортирани PDF до запазени игровни файлове и експортирани изображения.

Разработчикът трябва да разбира: файловете в Documents се включват автоматично в резервното копиране на iCloud и iTunes. Ако приложението съхранява в Documents големи обеми данни, които могат да бъдат възстановени (например, кеш на изображения или временни файлове), това ще доведе до неоправдано използване на пространство в iCloud хранилището на потребителя.

Как да получим пътя до Documents Directory

В Swift пътят до Documents Directory се получава чрез FileManager. Apple препоръчва използването на URL-базиран API вместо низово-базиран за по-добра съвместимост с съвременните възможности на iOS.

import Foundation

let fileManager = FileManager.default
guard let documentsURL = fileManager.urls(
    for: .documentDirectory,
    in: .userDomainMask
).first else { return }

// Създаване на файл в Documents
let fileURL = documentsURL.appendingPathComponent("report.pdf")
let data = Data("Hello, world!".utf8)
try data.write(to: fileURL)

Objective-C използва NSSearchPathForDirectoriesInDomains — по-стар подход, който все още се поддържа и връща низов път вместо на URL.

@import Foundation;

NSArray *paths = NSSearchPathForDirectoriesInDomains(
    NSDocumentDirectory,
    NSUserDomainMask,
    YES
);
NSString *documentsPath = paths.firstObject;
NSString *filePath = [documentsPath stringByAppendingPathComponent:@"report.pdf"];

Съвременните проекти на Swift трябва да използват FileManager.urls, тъй като този метод връща URL, а не низ, което намалява риска от грешки с кодирането на пътищата и прави кода по-типово безопасен.

Какви данни да съхраняваме в Documents

Documents Directory е предназначена за данни, създадени от потребителя или необходими на потребителя в явен вид. Apple отделя няколко категории, които са подходящи за тази директория.

Потребителски документи и файлове

Файловете, които потребителят създава или импортира — текстови документи, PDF, изображения, експортирани отчети, файлове за резервно копиране. Тези данни имат прека стойност за потребителя и тяхната загуба би била критична.

Запазени игри и състояние на приложението

Запазенията на игри, файловете със състоянието на приложението, експортираните проекти — всичко, което потребителят очаква да възстанови след преинсталиране на приложението. За критични данни обаче се препоръчва допълнително използване на iCloud Key-Value Storage или Core Data с iCloud синхронизация.

Ключов критерий: ако данните могат да бъдат възстановени от мрежата или пресъздадени — тяхното място е в Caches, а не в Documents. Всеки гигабайт в Documents е гигабайт в iCloud резервното копиране на потребителя.

Резервно копиране и синхронизация

iOS автоматично включва съдържанието на Documents Directory в резервното копиране при свързване на устройството към iTunes или при синхронизация с iCloud. Това поведение не може да се изключи на ниво директория — само по файлове чрез атрибута NSURLIsExcludedFromBackupKey.

От iOS 5.0 насамо, Apple започна да отказва приложения, които съхраняват в Documents големи обеми от възстановими данни. Препоръка на Apple: файловете, които могат да бъдат изтеглени отново, трябва да се съхраняват в Caches Directory с флаг за изключване от резервното копиране.

import Foundation

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

// Изключване на файл от iCloud резервно копиране
var resourceValues = URLResourceValues()
resourceValues.isExcludedFromBackup = true

var fileURL = documentsURL.appendingPathComponent("cached_data.json")
try fileURL.setResourceValues(resourceValues)

iCloud синхронизацията работи чрез NSUbiquitousContainer, ако приложението използва iCloud Documents. В този случай файловете от Documents Directory се синхронизират автоматично между устройствата на потребителя. За приложения без iCloud синхронизацията е ограничена до резервно копиране.

Documents Directory срещу Caches Directory

Разликата между Documents и Caches — едно от най-често срещаните неразбирателства сред начинаещите iOS разработчици. Основната разлика: системът може по всяко време да изтрие файлове от Caches, за да освободи пространство, но никога не пипа Documents без знаението на потребителя.

Според Apple Developer Documentation (2024), неправилното използване на Documents Directory — една от честите причини за отказ на приложения при преглед: ако приложението съхранява в Documents повече от няколко мегабайта възстановими данни, Apple препоръчва да ги преместите в Caches или да приложи NSURLIsExcludedFromBackupKey.

Практическо правило: ако потребителят ще бъде тъжен от загубата на файла — съхранявай в Documents. Ако файлът може да се изтегли отново или да се генерира — съхранявай в Caches.

Най-добри практики за работа с Documents

Опитните iOS разработчици са разработили няколко правила, които помагат да се избегнат проблемите с Documents Directory на всички етапи от жизнения цикъл на приложението — от разработката до публикуването в App Store.

Мониторинг на размера на директорията

Редовно проверявай размера на Documents Directory чрез FileManager.enumerator(at:includingPropertiesForKeys:). Ако размерът надвишава 100 MB за данни, които не са потребителски — това е повод да преоцениш архитектурата на хранилището.

Изключване на възстановими файлове от резервното копиране

За всички файлове, които могат да бъдат изтеглени отново от мрежата, задай isExcludedFromBackup = true. Това намалява натоварването на iCloud хранилището на потребителя и намалява риска от отказ на приложението от App Review.

Миграция при обновяване

При промяна на формата на данните в Documents, предвиждай миграция: не изтривай старите файлове, докато не си сигурен, че новите са създадени правилно. Използвай поддиректории, специфични за версията.

import Foundation

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

let versionDir = documentsURL.appendingPathComponent("v2")
try FileManager.default.createDirectory(
    at: versionDir,
    withIntermediateDirectories: true
)

Спазването на тези практики намалява риска от загуба на потребителски данни, намалява размера на iCloud резервното копиране и улеснява преминаването през преглед в App Store.