FileManager — چیست، کار با سیستم فایل iOS

FileManager چیست

FileManager — کلاس singleton از فریمورک Foundation است که API یکپارچه‌ای برای تعامل با سیستم فایل در تمام پلتفرم‌های Apple فراهم می‌کند. از طریق FileManager.default یا با ایجاد یک نمونه با دلیگیت سفارشی قابل دسترسی است.

قابلیت‌های اصلی کلاس شامل: بررسی وجود فایل (fileExists)، ایجاد دایرکتوری (createDirectory)، کپی و جابجایی (copyItem، moveItem)، حذف (removeItem)، دریافت ویژگی‌ها (attributesOfItem) و محتویات دایرکتوری (contentsOfDirectory) است. FileManager برای سریالایز کردن داده‌ها با NSData، String و JSONEncoder/Decoder ارتباط نزدیک دارد.

FileManager thread-safe است: Apple ایمنی فراخوانی متدها از threadهای مختلف را تضمین می‌کند. با این حال، عملیات سیستم فایل ممکن است روی فایل‌های بزرگ کند باشند، بنابراین Apple توصیه می‌کند آنها را در صف پس‌زمینه (DispatchQueue.global) اجرا کرده و متدهای FileManagerDelegate را برای اطلاع از پیشرفت فراخوانی کنید.

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

let fileURL = documentsURL.appendingPathComponent("data.plist")

if fileManager.fileExists(atPath: fileURL.path) {
    print("File exists at \(fileURL.path)")
}

دایرکتوری‌های اصلی برنامه iOS

هر برنامه iOS دارای سه دایرکتوری اصلی است که از طریق FileManager در چارچوب Sandbox قابل دسترسی هستند: Documents، Library و tmp. هر کدام هدف و قوانین پشتیبان‌گیری خاص خود را دارند که رعایت آنها برای قبولی در بازبینی App Store حیاتی است.

Documents — برای داده‌های کاربر که باید بین راه‌اندازی‌ها حفظ شوند و در iCloud پشتیبان‌گیری شوند. Library — برای فایل‌های برنامه: کش‌ها (Caches)، تنظیمات (Preferences)، پایگاه‌های داده (Application Support). tmp — برای فایل‌های موقتی که ممکن است توسط سیستم در هر لحظه بین راه‌اندازی‌های برنامه حذف شوند.

قانون Apple: اگر فایل را می‌توان از اینترنت بازیابی یا دوباره ایجاد کرد — باید در Caches ذخیره شود (بدون پشتیبان‌گیری). اگر فایل حاوی داده‌های کاربر است — Documents (با پشتیبان‌گیری). قرار دادن نادرست فایل‌ها یکی از دلایل رایج رد برنامه است، زیرا Apple سازگاری با Storage & iCloud Backup Guidelines را بررسی می‌کند.

خواندن و نوشتن فایل‌ها

FileManager خود متدهایی برای خواندن محتوای فایل‌ها فراهم نمی‌کند — برای این کار از NSData(contentsOf)، String(contentsOf) یا متدهای FileHandle استفاده می‌شود. FileManager مسئول مدیریت فایل‌ها است: بررسی وجود، جابجایی، کپی، حذف.

برای نوشتن داده‌ها از متد createFile(atPath:contents:attributes:) یا APIهای سطح بالا — data.write(to:)، JSONEncoder.encode و PropertyListEncoder استفاده می‌شود. FileManager همچنین FileHandle را برای خواندن و نوشتن جریانی فایل‌های بزرگ فراهم می‌کند که کل فایل را در حافظه بارگذاری نمی‌کند.

struct UserSettings: Codable {
    let username: String
    let isDarkMode: Bool
    let fontSize: Int
}

let settings = UserSettings(
    username: "developer",
    isDarkMode: true,
    fontSize: 16
)

// نوشتن JSON در Documents
let encoder = JSONEncoder()
encoder.outputFormatting = .prettyPrinted
let data = try encoder.encode(settings)
let url = documentsURL.appendingPathComponent("settings.json")
try data.write(to: url, options: .atomic)

// خواندن JSON
let loadedData = try Data(contentsOf: url)
let loadedSettings = try JSONDecoder()
    .decode(UserSettings.self, from: loadedData)

هنگام نوشتن از options: .atomic استفاده کنید — این تضمین می‌کند که فایل در صورت خرابی نوشتن آسیب نبیند: داده‌ها ابتدا در یک فایل موقت ذخیره می‌شوند، سپس به صورت اتمی به مسیر مقصد منتقل می‌شوند. برای خواندن فایل‌های بزرگ از FileHandle با .readingMode استفاده کنید و داده‌ها را به صورت تکه‌تکه بخوانید و مصرف حافظه را کنترل کنید.

مدیریت دایرکتوری‌ها

FileManager متدهایی برای مدیریت کامل دایرکتوری‌ها فراهم می‌کند: createDirectory (ایجاد همه پوشه‌های میانی با withIntermediateDirectories)، contentsOfDirectory (دریافت لیست فایل‌ها)، enumeratorAt (پیمایش بازگشتی) و subpathsOfDirectory (همه مسیرهای داخل دایرکتوری).

متد enumeratorAt یک DirectoryEnumerator برمی‌گرداند که امکان پیمایش کارآمد دایرکتوری‌های بزرگ را بدون بارگذاری کل محتوا در حافظه فراهم می‌کند. این متد از فیلتر کردن از طریق skipDescendants پشتیبانی می‌کند و ویژگی‌های هر عنصر را بدون درخواست اضافی به سیستم فایل ارائه می‌دهد.

// پیمایش بازگشتی دایرکتوری
if let enumerator = fileManager.enumerator(
    at: documentsURL,
    includingPropertiesForKeys: [.fileSizeKey, .isDirectoryKey]
) {
    for case let fileURL as URL in enumerator {
        let attrs = try fileURL.resourceValues(
            for: [.fileSizeKey, .isDirectoryKey]
        )
        if attrs.isDirectory == false {
            let size = attrs.fileSize ?? 0
            print("File: \(fileURL.lastPathComponent), Size: \(size) bytes")
        }
    }
}

برای حذف دایرکتوری از removeItem(at:) استفاده کنید. توجه: حذف دایرکتوری در iOS غیرقابل بازگشت است — فایل‌ها مانند macOS به سطل زباله نمی‌روند. قبل از حذف مطمئن شوید که دیگر از فایل‌های این دایرکتوری استفاده نمی‌کنید و عملیات را در thread پس‌زمینه اجرا کنید، زیرا حذف تعداد زیادی فایل ممکن است UI را مسدود کند.

FileManager و iCloud

FileManager از طریق متد URLForUbiquityContainerIdentifier با iCloud Drive یکپارچه می‌شود که URL دایرکتوری iCloud برنامه را برمی‌گرداند. برای کار نیاز به فعال کردن iCloud capability در پروژه و افزودن entitlement مربوطه است.

فایل‌های iCloud به صورت خودکار همگام‌سازی می‌شوند، اما FileManager متدهایی برای کنترل دستی فراهم می‌کند: startDownloadingUbiquitousItem دانلود را اجباری شروع می‌کند، evictUbiquitousItem کپی محلی را حذف می‌کند، و urlOfItem(at:) URL محلی فایل iCloud را برمی‌گرداند. NSMetadataQuery برای جستجوی فایل‌ها در iCloud استفاده می‌شود.

محدودیت بحرانی: iCloud Drive برای فایل‌های موجود در دایرکتوری Documents پشتیبانی نمی‌شود — فقط برای فایل‌های موجود در ubiquityContainer. سعی نکنید Documents را از طریق iCloud همگام‌سازی کنید؛ برای این کار از NSUbiquitousKeyValueStore برای حجم‌های کوچک داده یا Core Data با CloudKit برای ساختارهای پیچیده استفاده کنید.

عملکرد FileManager

عملیات FileManager ممکن است پرهزینه باشند، به خصوص در دستگاه‌هایی با حافظه flash کند. توصیه‌های اصلی Apple شامل اجرای تمام عملیات فایل در صف‌های پس‌زمینه، به حداقل رساندن تعداد فراخوانی‌های fileExistsAtPath و استفاده از ذخیره‌سازی نتایج است.

متد fileExists فراخوانی سیستمی stat() را انجام می‌دهد که نسبتاً کند است. اگر وجود فایل را قبل از خواندن آن بررسی می‌کنید، بهتر است مستقیماً آن را بخوانید و خطا را مدیریت کنید — این همان stat را انجام می‌دهد اما از فراخوانی سیستمی مضاعف جلوگیری می‌کند. برای بررسی‌های انبوه از enumeratorAt با resourceValues استفاده کنید.

برای بهینه‌سازی کار با حجم‌های زیاد داده:

• برای پردازش جریانی فایل‌های بزرگ از FileHandle استفاده کنید
• نتایج fileManager.urls را برای دایرکتوری‌های پرکاربرد ذخیره کنید
• عملیات دسته‌ای را در صف دانه‌بندی شده اجرا کنید و از مسدود کردن main thread خودداری کنید
• برای دسترسی امن از چند thread از CoordinatedFileManager استفاده کنید

Apple Instruments الگوی File Activity را برای پروفایل عملیات فایل فراهم می‌کند. از آن برای شناسایی تنگناها استفاده کنید — مثلاً فراخوانی‌های مکرر fileExists در حلقه یا عملیات نوشتن در main thread. رایج‌ترین مشکلات عملکرد مربوط به نوشتن همزمان فایل‌های بزرگ هنگام جمع‌شدن برنامه است.