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-based API-ја уместо string-based ради боље компатибилности са савременим могућностима 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-у.