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-based API вместо string-based для лучшей совместимости с современными возможностями iOS.

import Foundation

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

// Create file in 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!

// Exclude file from iCloud backup
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.