Documents Directory: що це, призначення та доступ до файлів

Що таке Documents Directory в iOS?

Documents Directory — це директорія всередині пісочниці iOS-застосунку, призначена для зберігання користувацьких даних, які мають зберігатися між запусками та бути доступними користувачеві. Кожен застосунок отримує власну ізольовану пісочницю, і Documents є однією з ключових директорій поряд із Caches, tmp та Library.

iOS використовує строгу пісочницю (sandbox): застосунок не має доступу до файлової системи інших застосунків та до системних директорій без спеціальних дозволів. 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 sync.

Ключовий критерій: якщо дані можна відновити з мережі або перестворити — їм місце в 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 vs 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 МБ для даних, що не є користувацькими — це привід переглянути архітектуру зберігання.

Виключення відновлюваних файлів з бекапу

Для будь-яких файлів, які можна повторно завантажити з мережі, встанови isExcludedFromBackup = true. Це знижує навантаження на iCloud-сховище користувача та зменшує ризик відхилення застосунку App Review.

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

При зміні формату даних в Documents передбач міграцію: не видаляй старі файли, поки не переконаєшся, що нові коректно створені. Використовуй version-специфічні піддиректорії.

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.