دایرکتوری اسناد در برنامه موبایل — چیست، هدف و نحوه سازماندهی ذخیره‌سازی

دایرکتوری اسناد برنامه چیست؟

دایرکتوری اسناد — یک فضای ذخیره‌سازی تخصصی در داخل سندباکس برنامه است که برای ذخیره‌سازی دائمی فایل‌های کاربر طراحی شده است. برخلاف کش، فایل‌های موجود در این دایرکتوری برای کاربر مهم تلقی می‌شوند: در صورت کمبود فضا توسط سیستم حذف نمی‌شوند، در هنگام به‌روزرسانی برنامه حفظ می‌شوند و در هنگام همگام‌سازی دستگاه پشتیبان‌گیری می‌شوند. در iOS، دایرکتوری Documents بخشی از کانتینر Sandbox است و به طور خودکار در پشتیبان‌گیری iCloud گنجانده می‌شود. در Android معادل مستقیمی وجود ندارد — معادل آن context.filesDir است که برای فایل‌های دائمی در نظر گرفته شده است اما مکانیزم داخلی پشتیبان‌گیری ندارد.

تفاوت بین دایرکتوری اسناد و ذخیره‌سازی داخلی (Internal Storage) در Android حداقل است: هر دو در سندباکس برنامه قرار دارند، هر دو در هنگام حذف نصب پاک می‌شوند، هر دو برای سایر برنامه‌ها غیرقابل دسترسی هستند. تفاوت اصلی معنایی است: Documents Directory فرض می‌کند که فایل‌ها توسط کاربر ایجاد یا وارد شده‌اند، در حالی که Internal Storage ممکن است حاوی فایل‌های داخلی برنامه (پایگاه‌های داده، تنظیمات) باشد. در iOS تفاوت قابل توجه‌تر است: Documents به طور خودکار پشتیبان‌گیری می‌شود، اما Library/Application Support نه. این بر استراتژی ذخیره‌سازی تأثیر می‌گذارد: در Documents فقط مواردی را قرار دهید که کاربر می‌خواهد در دستگاه جدید بازیابی کند، و در Application Support — داده‌های داخلی که برنامه می‌تواند بازتولید کند.

معماری سندباکس تضمین می‌کند که سایر برنامه‌ها به دایرکتوری اسناد برنامه شما دسترسی ندارند. در iOS دسترسی به Documents سایر برنامه‌ها بدون jailbreak غیرممکن است. در Android دسترسی روت به خواندن filesDir هر برنامه‌ای اجازه می‌دهد، بنابراین داده‌های محرمانه (توکن‌ها، کلیدهای رمزنگاری) باید با استفاده از EncryptedSharedPreferences یا EncryptedFile از کتابخانه AndroidX Security محافظت بیشتری شوند.

چه داده‌هایی در دایرکتوری اسناد ذخیره می‌شوند

در دایرکتوری اسناد باید داده‌هایی قرار داده شوند که برای کاربر ارزش دارند و باید پس از راه‌اندازی مجدد برنامه یا بازیابی دستگاه در دسترس باشند. همه فایل‌ها برای ذخیره در این دایرکتوری مناسب نیستند — انتخاب بستگی به نوع داده و سناریوی استفاده دارد.

اسناد و فایل‌های کاربر

فایل‌های کاربر — محتوای اصلی دایرکتوری اسناد. اینها می‌توانند اسناد متنی ایجاد شده در ویرایشگر، تصاویر گرفته شده با دوربین برنامه، گزارش‌های PDF صادر شده، ضبط‌های صوتی، یادداشت‌ها باشند. هر یک از این فایل‌ها توسط کاربر یا به درخواست او ایجاد شده است و باید در هر لحظه در دسترس باشد. در iOS فایل‌های موجود در Documents در برنامه سیستم Files نمایش داده می‌شوند که به کاربر اجازه می‌دهد از طریق مدیر فایل استاندارد آنها را مدیریت کند. در Android نمایش مشابهی وجود ندارد — برنامه باید خودش رابطی برای مشاهده فایل‌های ذخیره شده فراهم کند.

پایگاه‌های داده و تنظیمات برنامه

پایگاه‌های داده SQLite و فایل‌های تنظیمات معمولاً در کنار دایرکتوری اسناد ذخیره می‌شوند، اما در داخل آن نه. در iOS پایگاه‌های داده در Library/Application Support قرار می‌گیرند، زیرا نباید در برنامه Files نمایش داده شوند و جداگانه پشتیبان‌گیری شوند. در Android پایگاه‌های داده به طور پیش‌فرض از طریق Room یا SQLiteOpenHelper در /data/data/<package>/databases/ ایجاد می‌شوند. اگر پایگاه داده حاوی محتوای کاربر (یادداشت‌ها، دفترچه خاطرات، سوابق مالی) باشد، می‌توان آن را در filesDir قرار داد تا پشتیبان‌گیری از طریق سیستم انجام شود. Room اجازه می‌دهد دایرکتوری سفارشی برای ذخیره پایگاه داده از طریق callback RoomDatabase.Builder تعیین شود.

val dbFile = File(context.filesDir, "user_database.db")

val db = Room.databaseBuilder<AppDatabase>(
    context,
    dbFile.absolutePath
).build()

داده‌های صادر و وارد شده

فایل‌هایی که کاربر از برنامه‌های دیگر وارد می‌کند یا از برنامه شما صادر می‌کند، نیز باید در دایرکتوری اسناد ذخیره شوند. در iOS وارد کردن از طریق UIDocumentPickerViewController با استفاده از پارامتر asCopy: true به طور خودکار یک کپی از فایل را در Documents قرار می‌دهد. در Android وارد کردن از طریق دیالوگ SAF نیز یک کپی از فایل را در سندباکس برنامه ایجاد می‌کند. هنگام صدور داده‌ها (به عنوان مثال، ایجاد فایل CSV با مخاطبان)، ابتدا فایل را در Documents/filesDir ذخیره کنید، سپس از کاربر بخواهید آن را از طریق Share Sheet به اشتراک بگذارد. این تضمین می‌کند که حتی اگر کاربر فراموش کند فایل را پس از ارسال ذخیره کند، یک کپی در برنامه برای استفاده بعدی باقی می‌ماند.

نحوه کار با دایرکتوری اسناد در Android

در Android عملکرد دایرکتوری اسناد توسط context.filesDir انجام می‌شود. علاوه بر این، دایرکتوری context.externalFilesDir در کارت SD در دسترس است، اما حفظ داده‌ها را تضمین نمی‌کند. بیایید روش‌های اصلی کار با این دایرکتوری‌ها را بررسی کنیم.

دسترسی و مدیریت فایل‌ها از طریق filesDir

filesDir — دایرکتوری اصلی برای فایل‌های دائمی برنامه در Android است. در سندباکس برنامه قرار دارد و در هنگام حذف نصب به طور کامل حذف می‌شود. برای دریافت نمونه File از context.filesDir استفاده کنید که مسیر دایرکتوری /data/data/<package>/files/ را برمی‌گرداند. برای ایجاد و خواندن فایل‌ها از عملیات استاندارد File در Java/Kotlin یا متدهای Context openFileInput() و openFileOutput() استفاده کنید که نام فایل را دریافت کرده و FileInputStream/FileOutputStream برمی‌گردانند. متد openFileOutput() اگر فایل هنوز وجود نداشته باشد، به طور خودکار آن را در filesDir ایجاد می‌کند و اجازه می‌دهد حالت دسترسی را مشخص کنید: MODE_PRIVATE (فقط برنامه فعلی)، MODE_APPEND (افزودن) یا MODE_WORLD_READABLE (منسوخ شده، از API 24+ استفاده نمی‌شود).

val fileName = "report.pdf"
val content = "PDF content".toByteArray()

context.openFileOutput(fileName, Context.MODE_PRIVATE).use { stream ->
    stream.write(content)
}

val bytes = context.openFileInput(fileName).use { stream ->
    stream.readBytes()
}

ویژگی‌های ذخیره‌سازی در Android 10+

در Android 10+ مدل Scoped Storage روی filesDir تأثیری ندارد — دسترسی به سندباکس خود برنامه کاملاً باقی می‌ماند. تمام عملیات خواندن و نوشتن در داخل filesDir به مجوزهای اضافی نیاز ندارند. با این حال، هنگام تلاش برای دسترسی به فایل‌های برنامه دیگر از طریق filesDir یک استثنا دریافت خواهید کرد. برای تبادل فایل از FileProvider استفاده کنید که یک content URI موقت برای ارسال فایل به برنامه دیگر ایجاد می‌کند. FileProvider در AndroidManifest.xml از طریق تگ <provider> اعلام می‌شود و در فایل XML مسیرها پیکربندی می‌شود. این یک مکانیزم استاندارد برای انتقال فایل‌ها بین برنامه‌ها است که به عنوان مثال هنگام ارسال تصویر از طریق Intent با ACTION_SEND استفاده می‌شود.

نحوه کار با دایرکتوری اسناد در iOS

در iOS Documents Directory بخشی از کانتینر Sandbox برنامه با وضعیت ویژه است. فایل‌های این دایرکتوری به طور خودکار در پشتیبان‌گیری iCloud گنجانده می‌شوند، در برنامه Files نمایش داده می‌شوند و در هنگام به‌روزرسانی برنامه از طریق App Store حفظ می‌شوند.

Documents Directory و پشتیبان‌گیری

پشتیبان‌گیری خودکار Documents — مزیت کلیدی iOS است. وقتی کاربر دستگاه را به iTunes متصل می‌کند یا iCloud Backup را فعال می‌کند، تمام فایل‌های Documents/ در پشتیبان کپی می‌شوند. هنگام بازیابی در دستگاه جدید، کاربر تمام فایل‌های خود را بدون اقدام اضافی دریافت می‌کند. با این حال، این مزیت زمانی به نقطه ضعف تبدیل می‌شود که برنامه حجم زیادی از داده را در Documents ذخیره کند: زمان پشتیبان‌گیری افزایش می‌یابد و فضای iCloud ممکن است به سرعت تمام شود. بنابراین در Documents باید فقط فایل‌هایی را ذخیره کرد که واقعاً در هنگام بازیابی به کاربر نیاز هستند. فایل‌های موقت، کش و داده‌های قابل بازتولید باید در Caches یا Library/Application Support باشند. Apple توصیه می‌کند فایل‌هایی را که می‌توان از اینترنت دوباره دانلود کرد، از طریق ویژگی isExcludedFromBackup از پشتیبان‌گیری حذف کنید.

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

let fileURL = docsURL.appendingPathComponent("notes.txt")
let text = "محتوای یادداشت"
try text.write(to: fileURL, atomically: true, encoding: .utf8)

iCloud Drive و همگام‌سازی بین دستگاه‌ها

iCloud Drive امکان همگام‌سازی فایل‌های Documents را بین دستگاه‌های یک کاربر فراهم می‌کند. برای فعال‌سازی همگام‌سازی، برنامه باید از API NSDocument یا UIDocument استفاده کند که به طور خودکار نسخه‌بندی و حل تعارضات را مدیریت می‌کنند. رویکرد جایگزین — استفاده از iCloud با CloudKit که کنترل انعطاف‌پذیرتری بر همگام‌سازی فراهم می‌کند اما نیاز به پیکربندی در CloudKit Dashboard دارد. هنگام استفاده از iCloud Drive مطمئن شوید که تعارضات ویرایش را به درستی مدیریت می‌کنید (merge یا last-write-wins) و کاربر را از وضعیت همگام‌سازی از طریق رابط برنامه مطلع می‌کنید. iCloud همگام‌سازی فوری را تضمین نمی‌کند — تأخیر می‌تواند از چند ثانیه تا چند دقیقه بسته به اندازه فایل و کیفیت اتصال متغیر باشد. برای داده‌های حیاتی از نوشتن تراکنشی و نسخه‌بندی استفاده کنید تا در صورت تعارض بتوان نسخه قبلی فایل را بازیابی کرد.

تفاوت‌ها با Cache Directory و بهترین روش‌ها

انتخاب صحیح بین Documents Directory و Cache Directory قابلیت اطمینان ذخیره‌سازی داده‌های کاربر را تعیین می‌کند. اشتباه در انتخاب منجر به از دست رفتن داده‌ها (اگر فایل‌های مهم در کش ذخیره شوند) یا پر شدن پشتیبان (اگر فایل‌های موقت در Documents ذخیره شوند) می‌شود.

بهترین روش‌ها استفاده از دایرکتوری اسناد شامل چندین قانون کلیدی است. اول، همیشه قبل از حذف فایل‌ها از این دایرکتوری تأیید کاربر را دریافت کنید. برخلاف کش، حذف یک سند می‌تواند منجر به از دست رفتن غیرقابل بازگشت محتوای کاربر شود. دوم، نسخه‌بندی فایل‌ها را پیاده‌سازی کنید: هنگام بازنویسی فایل موجود، نسخه قبلی را با پسوند _backup ذخیره کنید یا از مکانیزم‌های Snapshot استفاده کنید. سوم، به کاربر رابطی برای مشاهده، تغییر نام، حذف و صدور فایل‌ها از دایرکتوری اسناد ارائه دهید. در iOS فایل‌های Documents به طور خودکار در Files نمایش داده می‌شوند، در Android باید مدیر فایل خود را پیاده‌سازی کنید یا از کتابخانه‌های شخص ثالث استفاده کنید.

به مهاجرت داده‌ها در هنگام به‌روزرسانی برنامه توجه ویژه کنید. اگر نسخه جدید ساختار ذخیره‌سازی فایل را تغییر می‌دهد (مثلاً داده‌ها را از یک زیردایرکتوری به زیردایرکتوری دیگر منتقل می‌کند یا فرمت فایل را تغییر می‌دهد)، یک مهاجرت یکباره در اولین راه‌اندازی پس از به‌روزرسانی پیاده‌سازی کنید. شماره نسخه طرح داده را در SharedPreferences ذخیره کنید و در صورت عدم تطابق، مهاجرت را آغاز کنید. فایل‌های قدیمی را تا پایان مهاجرت حذف نکنید — در صورت خرابی، کاربر نباید داده‌ها را از دست بدهد. اگر مهاجرت شامل تبدیل فرمت (مثلاً انتقال از JSON به SQLite) باشد، فایل‌های اصلی را به عنوان پشتیبان در یک دایرکتوری جداگانه با تاریخ مهاجرت ذخیره کنید. کاربر باید بتواند از طریق تنظیمات برنامه در 30 روز اول پس از به‌روزرسانی تغییرات را بازگرداند، همانطور که Apple Human Interface Guidelines توصیه می‌کند.