Documents Directory: nó là gì, mục đích và truy cập tệp

Documents Directory trong iOS là gì?

Documents Directory là một thư mục bên trong sandbox của ứng dụng iOS được thiết kế để lưu trữ dữ liệu người dùng cần tồn tại giữa các lần khởi động và có thể truy cập được. Mỗi ứng dụng có sandbox riêng biệt và Documents là một trong những thư mục chính cùng với Caches, tmp và Library.

iOS sử dụng sandbox nghiêm ngặt: ứng dụng không có quyền truy cập vào hệ thống tệp của các ứng dụng khác hoặc vào các thư mục hệ thống nếu không có quyền đặc biệt. Documents Directory là thư mục duy nhất mà người dùng có thể xem nội dung qua iTunes File Sharing (khi bật khóa UIFileSharingEnabled trong Info.plist).

Theo Apple WWDC 2023, hơn 85% ứng dụng trong App Store sử dụng Documents Directory để lưu trữ ít nhất một loại dữ liệu người dùng — từ PDF đã xuất đến tệp trò chơi đã lưu và hình ảnh đã xuất.

Điều quan trọng là nhà phát triển phải hiểu: các tệp trong Documents được tự động bao gồm trong các bản sao lưu iCloud và iTunes. Nếu ứng dụng lưu trữ khối lượng lớn dữ liệu có thể khôi phục trong Documents (ví dụ: bộ nhớ đệm hình ảnh hoặc tệp tạm thời), điều này dẫn đến tiêu thụ không cần thiết dung lượng lưu trữ iCloud của người dùng.

Cách lấy đường dẫn đến Documents Directory

Trong Swift, đường dẫn đến Documents Directory được lấy qua FileManager. Apple khuyến nghị sử dụng API dựa trên URL thay vì dựa trên chuỗi để tương thích tốt hơn với các khả năng hiện đại của iOS.

import Foundation

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

// Tạo tệp trong Documents
let fileURL = documentsURL.appendingPathComponent("report.pdf")
let data = Data("Hello, world!".utf8)
try data.write(to: fileURL)

Objective-C sử dụng NSSearchPathForDirectoriesInDomains — một cách tiếp cận cũ hơn nhưng vẫn được hỗ trợ, trả về đường dẫn chuỗi thay vì URL.

@import Foundation;

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

Các dự án hiện đại trong Swift nên sử dụng FileManager.urls vì phương thức này trả về URL thay vì chuỗi, giúp giảm nguy cơ lỗi mã hóa đường dẫn và làm cho mã an toàn hơn về kiểu dữ liệu.

Dữ liệu nào nên lưu trong Documents

Documents Directory dành cho dữ liệu do người dùng tạo hoặc người dùng cần một cách rõ ràng. Apple nêu bật một số danh mục phù hợp cho thư mục này.

Tài liệu và tệp người dùng

Tệp mà người dùng tạo hoặc nhập — tài liệu văn bản, PDF, hình ảnh, báo cáo đã xuất, tệp sao lưu. Dữ liệu này có giá trị trực tiếp đối với người dùng và việc mất chúng sẽ rất nghiêm trọng.

Lưu trò chơi và trạng thái ứng dụng

Lưu trò chơi, tệp trạng thái ứng dụng, dự án đã xuất — mọi thứ người dùng mong đợi khôi phục sau khi cài đặt lại ứng dụng. Tuy nhiên, đối với dữ liệu quan trọng, nên sử dụng thêm iCloud Key-Value Storage hoặc Core Data với đồng bộ hóa iCloud.

Tiêu chí chính: nếu dữ liệu có thể được tải xuống lại từ mạng hoặc được tạo lại — vị trí của chúng là trong Caches, không phải Documents. Mỗi gigabyte trong Documents là một gigabyte trong bản sao lưu iCloud của người dùng.

Sao lưu và đồng bộ hóa

iOS tự động bao gồm nội dung của Documents Directory trong các bản sao lưu khi thiết bị được kết nối với iTunes hoặc khi đồng bộ với iCloud. Hành vi này không thể bị tắt ở cấp thư mục — chỉ theo từng tệp thông qua thuộc tính NSURLIsExcludedFromBackupKey.

Bắt đầu từ iOS 5.0, Apple bắt đầu từ chối các ứng dụng lưu trữ khối lượng lớn dữ liệu có thể khôi phục trong Documents. Khuyến nghị của Apple: các tệp có thể tải xuống lại nên được lưu trữ trong Caches Directory với cờ loại trừ sao lưu.

import Foundation

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

// Loại trừ tệp khỏi sao lưu iCloud
var resourceValues = URLResourceValues()
resourceValues.isExcludedFromBackup = true

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

Đồng bộ hóa iCloud hoạt động qua NSUbiquitousContainer nếu ứng dụng sử dụng iCloud Documents. Trong trường hợp này, các tệp từ Documents Directory tự động được đồng bộ giữa các thiết bị của người dùng. Đối với các ứng dụng không có iCloud, đồng bộ hóa chỉ giới hạn ở sao lưu.

Documents Directory vs Caches Directory

Sự khác biệt giữa Documents và Caches là một trong những quan niệm sai lầm phổ biến nhất ở các nhà phát triển iOS mới bắt đầu. Sự khác biệt chính: hệ thống có thể xóa tệp khỏi Caches bất cứ lúc nào để giải phóng dung lượng, nhưng không bao giờ động đến Documents nếu không có sự cho phép của người dùng.

Theo Tài liệu dành cho nhà phát triển Apple (2024), việc sử dụng không đúng cách Documents Directory là một trong những lý do phổ biến khiến ứng dụng bị từ chối trong quá trình xem xét: nếu ứng dụng lưu trữ hơn vài megabyte dữ liệu có thể khôi phục trong Documents, Apple khuyến nghị di chuyển chúng sang Caches hoặc áp dụng NSURLIsExcludedFromBackupKey.

Một quy tắc thực tế: nếu người dùng sẽ buồn khi mất tệp — hãy lưu trữ nó trong Documents. Nếu tệp có thể được tải xuống lại hoặc tạo lại — hãy lưu trữ nó trong Caches.

Các phương pháp hay nhất khi làm việc với Documents

Các nhà phát triển iOS giàu kinh nghiệm đã xây dựng một số quy tắc giúp tránh các vấn đề với Documents Directory ở tất cả các giai đoạn của vòng đời ứng dụng — từ phát triển đến xuất bản trên App Store.

Giám sát kích thước thư mục

Thường xuyên kiểm tra kích thước của Documents Directory qua FileManager.enumerator(at:includingPropertiesForKeys:). Nếu kích thước vượt quá 100 MB cho dữ liệu không phải của người dùng — đó là lý do để xem xét lại kiến trúc lưu trữ.

Loại trừ tệp có thể khôi phục khỏi sao lưu

Đối với bất kỳ tệp nào có thể tải xuống lại, hãy đặt isExcludedFromBackup = true. Điều này giảm tải cho bộ nhớ iCloud của người dùng và giảm nguy cơ bị từ chối trong App Review.

Di chuyển khi cập nhật

Khi thay đổi định dạng dữ liệu trong Documents, hãy lên kế hoạch di chuyển: không xóa tệp cũ cho đến khi bạn chắc chắn rằng tệp mới đã được tạo chính xác. Sử dụng các thư mục con dành riêng cho phiên bả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
)

Tuân theo các phương pháp này giúp giảm nguy cơ mất dữ liệu người dùng, giảm kích thước sao lưu iCloud và đơn giản hóa việc xem xét trên App Store.