Documents Directory: 정의, 목적 및 파일 액세스

iOS에서 Documents Directory란?

Documents Directory는 iOS 앱 샌드박스 내의 디렉토리로, 실행 간에 유지되어야 하고 사용자가 액세스할 수 있는 사용자 데이터를 저장하기 위해 설계되었습니다. 각 앱은 자체 격리된 샌드박스를 가지며, Documents는 Caches, tmp 및 Library와 함께 주요 디렉토리 중 하나입니다.

iOS는 엄격한 샌드박스를 사용합니다. 앱은 특별한 권한 없이 다른 앱의 파일 시스템이나 시스템 디렉토리에 액세스할 수 없습니다. Documents Directory는 사용자가 iTunes File Sharing을 통해 내용을 볼 수 있는 유일한 디렉토리입니다(Info.plist에서 UIFileSharingEnabled 키가 활성화된 경우).

Apple WWDC 2023에 따르면 App Store 앱의 85% 이상이 Documents Directory를 사용하여 최소 한 가지 유형의 사용자 데이터(내보낸 PDF, 저장된 게임 파일, 내보낸 이미지 등)를 저장합니다.

개발자가 이해해야 할 중요한 사항: Documents의 파일은 iCloud 및 iTunes 백업에 자동으로 포함됩니다. 앱이 Documents에 많은 양의 복구 가능한 데이터(예: 이미지 캐시 또는 임시 파일)를 저장하면 사용자의 iCloud 저장 공간을 불필요하게 소비하게 됩니다.

Documents Directory 경로 얻는 방법

Swift에서 Documents Directory의 경로는 FileManager를 통해 얻습니다. Apple은 최신 iOS 기능과의 더 나은 호환성을 위해 문자열 기반 API 대신 URL 기반 API를 사용할 것을 권장합니다.

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 또는 iCloud 동기화가 포함된 Core Data를 추가로 사용하는 것이 좋습니다.

핵심 기준: 데이터를 네트워크에서 다시 다운로드하거나 다시 생성할 수 있다면 Caches에 있어야 하며 Documents에 있으면 안 됩니다. Documents의 1기가바이트는 사용자의 iCloud 백업에서 1기가바이트입니다.

백업 및 동기화

iOS는 장치가 iTunes에 연결되거나 iCloud와 동기화할 때 Documents Directory의 내용을 백업에 자동으로 포함합니다. 이 동작은 디렉토리 수준에서 비활성화할 수 없으며 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 동기화는 앱이 iCloud Documents를 사용하는 경우 NSUbiquitousContainer를 통해 작동합니다. 이 경우 Documents Directory의 파일이 사용자의 장치 간에 자동으로 동기화됩니다. iCloud가 없는 앱의 경우 동기화는 백업으로 제한됩니다.

Documents Directory vs Caches Directory

Documents와 Caches의 차이점은 초보 iOS 개발자들 사이에서 가장 흔한 오해 중 하나입니다. 주요 차이점: 시스템은 공간을 확보하기 위해 언제든지 Caches에서 파일을 삭제할 수 있지만 사용자가 모르는 사이에 Documents는 절대 건드리지 않습니다.

Apple Developer Documentation(2024)에 따르면 Documents Directory의 부적절한 사용은 검토 중 앱 거부의 일반적인 원인 중 하나입니다. 앱이 Documents에 수 메가바이트 이상의 복구 가능한 데이터를 저장하는 경우 Apple은 Caches로 이동하거나 NSURLIsExcludedFromBackupKey를 적용할 것을 권장합니다.

실용적인 규칙: 사용자가 파일을 잃어서 속상해할 경우 Documents에 저장하세요. 파일을 다시 다운로드하거나 다시 생성할 수 있는 경우 Caches에 저장하세요.

Documents 작업 모범 사례

경험 많은 iOS 개발자들은 앱 수명 주기의 모든 단계(개발부터 App Store 출시까지)에서 Documents Directory 관련 문제를 방지하는 데 도움이 되는 여러 규칙을 개발했습니다.

디렉토리 크기 모니터링

FileManager.enumerator(at:includingPropertiesForKeys:)를 통해 Documents Directory의 크기를 정기적으로 확인하세요. 사용자 데이터가 아닌 것이 100MB를 초과하면 스토리지 아키텍처를 재고해야 할 이유입니다.

복구 가능한 파일을 백업에서 제외

다시 다운로드할 수 있는 파일의 경우 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 검토가 간소화됩니다.