Documents Directory: nedir, amacı ve dosya erişimi

iOS'ta Documents Directory Nedir?

Documents Directory, iOS uygulama sandbox'ı içinde, başlatmalar arasında kalıcı olması ve kullanıcı tarafından erişilebilir olması gereken kullanıcı verilerini depolamak için tasarlanmış bir dizindir. Her uygulama kendi izole sandbox'ını alır ve Documents, Caches, tmp ve Library ile birlikte temel dizinlerden biridir.

iOS katı bir sandbox kullanır: bir uygulama, özel izinler olmadan diğer uygulamaların dosya sistemine veya sistem dizinlerine erişemez. Documents Directory, kullanıcının iTunes File Sharing aracılığıyla içeriğini görüntüleyebileceği tek dizindir (Info.plist'te UIFileSharingEnabled anahtarı etkinleştirildiğinde).

Apple WWDC 2023'e göre, App Store'daki uygulamaların %85'inden fazlası, dışa aktarılan PDF'lerden kaydedilmiş oyun dosyalarına ve dışa aktarılan görsellere kadar en az bir tür kullanıcı verisini depolamak için Documents Directory'yi kullanır.

Geliştiricinin anlaması önemlidir: Documents'taki dosyalar iCloud ve iTunes yedeklemelerine otomatik olarak dahil edilir. Bir uygulama Documents'ta büyük miktarda kurtarılabilir veri depoluyorsa (örneğin, görsel önbelleği veya geçici dosyalar), bu kullanıcının iCloud depolama alanının gereksiz yere tüketilmesine yol açar.

Documents Directory Yolunu Alma

Swift'te, Documents Directory yolu FileManager aracılığıyla alınır. Apple, modern iOS yetenekleriyle daha iyi uyumluluk için dize tabanlı API yerine URL tabanlı API kullanılmasını önerir.

import Foundation

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

// Documents'ta dosya oluştur
let fileURL = documentsURL.appendingPathComponent("report.pdf")
let data = Data("Hello, world!".utf8)
try data.write(to: fileURL)

Objective-C, NSSearchPathForDirectoriesInDomains kullanır — URL yerine dize yolu döndüren daha eski ancak hala desteklenen bir yaklaşım.

@import Foundation;

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

Swift'teki modern projeler FileManager.urls kullanmalıdır, çünkü bu yöntem dize yerine URL döndürür, bu da yol kodlama hataları riskini azaltır ve kodu daha tip güvenli hale getirir.

Documents'ta Hangi Veriler Saklanmalı

Documents Directory, kullanıcı tarafından oluşturulan veya kullanıcının açıkça ihtiyaç duyduğu veriler içindir. Apple bu dizin için uygun olan birkaç kategoriyi vurgular.

Kullanıcı Belgeleri ve Dosyaları

Kullanıcının oluşturduğu veya içe aktardığı dosyalar — metin belgeleri, PDF'ler, görseller, dışa aktarılan raporlar, yedek dosyaları. Bu veriler kullanıcı için doğrudan değere sahiptir ve kaybedilmeleri kritik olurdu.

Oyun Kayıtları ve Uygulama Durumu

Oyun kayıtları, uygulama durum dosyaları, dışa aktarılan projeler — kullanıcının uygulamayı yeniden yükledikten sonra geri yüklemeyi beklediği her şey. Ancak, kritik veriler için ayrıca iCloud Key-Value Storage veya iCloud senkronizasyonlu Core Data kullanılması önerilir.

Temel kriter: veriler ağdan yeniden indirilebiliyor veya yeniden oluşturulabiliyorsa — yeri Caches'tir, Documents değil. Documents'taki her gigabayt, kullanıcının iCloud yedeklemesindeki bir gigabayttır.

Yedekleme ve Senkronizasyon

iOS, cihaz iTunes'a bağlandığında veya iCloud ile senkronize edildiğinde Documents Directory içeriğini otomatik olarak yedeklemelere dahil eder. Bu davranış dizin düzeyinde devre dışı bırakılamaz — yalnızca NSURLIsExcludedFromBackupKey özniteliği aracılığıyla dosya bazında yapılabilir.

iOS 5.0'dan itibaren Apple, Documents'ta büyük miktarda kurtarılabilir veri depolayan uygulamaları reddetmeye başladı. Apple'ın önerisi: yeniden indirilebilen dosyalar, yedekleme hariç tutma bayrağıyla Caches Directory'de saklanmalıdır.

import Foundation

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

// Dosyayı iCloud yedeklemesinden hariç tut
var resourceValues = URLResourceValues()
resourceValues.isExcludedFromBackup = true

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

iCloud senkronizasyonu, uygulama iCloud Documents kullanıyorsa NSUbiquitousContainer aracılığıyla çalışır. Bu durumda, Documents Directory'deki dosyalar kullanıcının cihazları arasında otomatik olarak senkronize edilir. iCloud'u olmayan uygulamalar için senkronizasyon yedekleme ile sınırlıdır.

Documents Directory vs Caches Directory

Documents ve Caches arasındaki fark, yeni başlayan iOS geliştiricileri arasındaki en yaygın yanılgılardan biridir. Temel fark: sistem, alan boşaltmak için istediği zaman Caches'ten dosyaları silebilir, ancak kullanıcının bilgisi olmadan Documents'a asla dokunmaz.

Apple Developer Documentation (2024)'e göre, Documents Directory'nin uygunsuz kullanımı inceleme sırasında uygulama reddinin yaygın nedenlerinden biridir: bir uygulama Documents'ta birkaç megabayttan fazla kurtarılabilir veri depoluyorsa, Apple bunları Caches'e taşımayı veya NSURLIsExcludedFromBackupKey uygulamayı önerir.

Pratik bir kural: kullanıcı dosyayı kaybetmeye üzülecekse — Documents'ta saklayın. Dosya yeniden indirilebiliyor veya yeniden oluşturulabiliyorsa — Caches'te saklayın.

Documents ile Çalışmak İçin En İyi Uygulamalar

Deneyimli iOS geliştiricileri, uygulama yaşam döngüsünün tüm aşamalarında (geliştirmeden App Store yayınına kadar) Documents Directory ile ilgili sorunları önlemeye yardımcı olan birkaç kural geliştirmiştir.

Dizin Boyutunu İzleme

FileManager.enumerator(at:includingPropertiesForKeys:) aracılığıyla Documents Directory boyutunu düzenli olarak kontrol edin. Kullanıcı verisi olmayan 100 MB'ı aşarsa — depolama mimarisini yeniden gözden geçirme nedenidir.

Kurtarılabilir Dosyaları Yedeklemeden Hariç Tutma

Yeniden indirilebilen tüm dosyalar için isExcludedFromBackup = true olarak ayarlayın. Bu, kullanıcının iCloud deposundaki yükü azaltır ve App Review tarafından reddedilme riskini düşürür.

Güncellemeler Sırasında Geçiş

Documents'taki veri biçimini değiştirirken geçiş planlayın: yeni dosyaların doğru oluşturulduğundan emin olana kadar eski dosyaları silmeyin. Sürüme özel alt dizinler kullanın.

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
)

Bu uygulamaları takip etmek, kullanıcı verisi kaybı riskini azaltır, iCloud yedekleme boyutunu küçültür ve App Store incelemesini basitleştirir.