Documents Directory: τι είναι, σκοπός και πρόσβαση σε αρχεία

Τι είναι το Documents Directory στο iOS;

Documents Directory — είναι ένας κατάλογος μέσα στο sandbox της εφαρμογής iOS, προορισμένος για την αποθήκευση δεδομένων χρήστη που πρέπει να διατηρούνται μεταξύ εκκινήσεων και να είναι προσβάσιμα στον χρήστη. Κάθε εφαρμογή λαμβάνει το δικό της απομονωμένο sandbox, και το 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 συνιστά τη χρήση API βασισμένου σε URL αντί για καλύτερη συμβατότητα με τις σύγχρονες δυνατότητες του 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. Κάθε gigabyte στο Documents είναι ένα gigabyte στο αντίγραφο ασφαλείας 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 — μία από τις συχνές αιτίες απόρριψης εφαρμογών κατά την αξιολόγηση: εάν η εφαρμογή αποθηκεύει περισσότερα από λίγα megabyte αποκαταστάσιμων δεδομένων στο 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.