FileManager — o que é, trabalho com o sistema de arquivos iOS

O que é FileManager

FileManager é uma classe singleton do framework Foundation que fornece uma API unificada para interagir com o sistema de arquivos em todas as plataformas Apple. Está disponível através de FileManager.default ou criando uma instância com um delegado personalizado.

As principais capacidades da classe incluem: verificar existência de arquivo (fileExists), criar diretórios (createDirectory), copiar e mover (copyItem, moveItem), excluir (removeItem), obter atributos (attributesOfItem) e conteúdo de diretórios (contentsOfDirectory). FileManager está intimamente relacionado com NSData, String e JSONEncoder/Decoder para serialização de dados.

FileManager é thread-safe: a Apple garante chamadas seguras de métodos de diferentes threads. No entanto, as operações do sistema de arquivos podem ser lentas em arquivos grandes, por isso a Apple recomenda realizá-las em uma fila em segundo plano (DispatchQueue.global) e chamar métodos FileManagerDelegate para reportar progresso.

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)")
}

Principais diretórios de aplicações iOS

Cada aplicação iOS tem três diretórios principais acessíveis através do FileManager dentro do Sandbox: Documents, Library e tmp. Cada um tem seu próprio propósito e regras de backup que são fundamentais para passar pela revisão da App Store.

Documents — para dados do usuário que devem persistir entre inicializações e ser copiados para o iCloud. Library — para arquivos da aplicação: caches (Caches), configurações (Preferences), bancos de dados (Application Support). tmp — para arquivos temporários que podem ser excluídos pelo sistema a qualquer momento entre inicializações da aplicação.

Regra da Apple: se um arquivo pode ser recuperado da internet ou recriado — deve ser armazenado em Caches (sem backup). Se um arquivo contém dados do usuário — Documents (com backup). A colocação incorreta de arquivos é uma das razões comuns para rejeição de aplicativos, pois a Apple verifica a conformidade com as Diretrizes de Armazenamento e Backup do iCloud.

Leitura e escrita de arquivos

FileManager em si não fornece métodos para ler conteúdo de arquivos — para isso use NSData(contentsOf), String(contentsOf) ou métodos FileHandle. FileManager é responsável por gerenciar arquivos: verificar existência, mover, copiar, excluir.

Para escrever dados use o método createFile(atPath:contents:attributes:) ou APIs de alto nível — data.write(to:), JSONEncoder.encode e PropertyListEncoder. FileManager também fornece FileHandle para leitura e escrita em streaming de arquivos grandes, que não carrega todo o arquivo na memória.

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

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

// Write JSON to 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)

// Read JSON
let loadedData = try Data(contentsOf: url)
let loadedSettings = try JSONDecoder()
    .decode(UserSettings.self, from: loadedData)

Ao escrever, use options: .atomic — isso garante que o arquivo não será corrompido se a escrita falhar: os dados são primeiro salvos em um arquivo temporário, depois movidos atomicamente para o caminho de destino. Para ler arquivos grandes, use FileHandle com .readingMode e leia dados em pedaços, controlando o consumo de memória.

Gerenciamento de diretórios

FileManager fornece métodos para gerenciamento completo de diretórios: createDirectory (criando todas as pastas intermediárias via withIntermediateDirectories), contentsOfDirectory (obter lista de arquivos), enumeratorAt (percurso recursivo) e subpathsOfDirectory (todos os caminhos dentro de um diretório).

O método enumeratorAt retorna um DirectoryEnumerator, que permite percorrer eficientemente grandes diretórios sem carregar todo o conteúdo na memória. Suporta filtragem via skipDescendants e fornece atributos de cada item sem uma consulta adicional ao sistema de arquivos.

// Recursive directory traversal
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")
        }
    }
}

Para excluir um diretório use removeItem(at:). Aviso: excluir um diretório no iOS é irreversível — os arquivos não vão para a lixeira como no macOS. Antes de excluir, certifique-se de que não precisa mais dos arquivos desse diretório e realize a operação em uma thread em segundo plano, pois excluir muitos arquivos pode bloquear a interface do usuário.

FileManager e iCloud

FileManager integra-se com iCloud Drive através do método URLForUbiquityContainerIdentifier, que retorna o URL do diretório iCloud para a aplicação. Isso requer habilitar a capacidade iCloud no projeto e adicionar o entitlement apropriado.

Os arquivos iCloud sincronizam automaticamente, mas FileManager fornece métodos para controle manual: startDownloadingUbiquitousItem força o download, evictUbiquitousItem remove a cópia local e urlOfItem(at:) retorna o URL local para um arquivo iCloud. NSMetadataQuery é usado para pesquisar arquivos no iCloud.

Limitação crítica: iCloud Drive não é suportado para arquivos no diretório Documents — apenas para arquivos em ubiquityContainer. Não tente sincronizar Documents via iCloud; para isso use NSUbiquitousKeyValueStore para pequenas quantidades de dados ou Core Data com CloudKit para estruturas complexas.

Desempenho do FileManager

Operações com FileManager podem ser custosas, especialmente em dispositivos com memória flash lenta. As principais recomendações da Apple incluem realizar todas as operações de arquivos em filas em segundo plano, minimizar o número de chamadas fileExistsAtPath e armazenar resultados em cache.

O método fileExists realiza uma chamada de sistema stat(), que é relativamente lenta. Se você verifica a existência de um arquivo antes de lê-lo, é melhor simplesmente tentar lê-lo e tratar o erro — isso realiza o mesmo stat, mas evita uma chamada de sistema dupla. Para verificações em massa, use enumeratorAt com resourceValues.

Para otimizar o trabalho com grandes volumes de dados:

• Use FileHandle para processamento em streaming de arquivos grandes
• Armazene em cache os resultados de fileManager.urls para diretórios usados com frequência
• Realize operações em lote em uma fila granular, evitando bloquear a thread principal
• Use CoordinatedFileManager para acesso seguro de múltiplas threads

O Apple Instruments fornece o modelo File Activity para perfilamento de operações de arquivos. Use-o para identificar gargalos — por exemplo, chamadas frequentes a fileExists em um loop ou operações de escrita na thread principal. Os problemas de desempenho mais comuns estão relacionados à escrita síncrona de arquivos grandes quando a aplicação é suspensa.