Caches Directory: o que é, gerenciamento de cache e limpeza de dados

O que é Caches Directory no iOS?

Caches Directory é um diretório dentro do sandbox da aplicação iOS otimizado para armazenar dados que podem ser restaurados quando necessário. Ao contrário do Documents Directory, o Caches não se destina a dados do usuário — é um armazenamento temporário para acelerar o desempenho da aplicação.

O iOS usa o Caches Directory para armazenar respostas de rede em cache, imagens pré-carregadas, objetos serializados e dados que a aplicação pode restaurar. Os desenvolvedores não devem confiar no armazenamento de longo prazo neste diretório.

De acordo com Apple WWDC 2020, cerca de 40% das aplicações iOS usam o Caches Directory para armazenar imagens e dados de rede em cache, enquanto 25% dos desenvolvedores colocam incorretamente no Caches dados que deveriam estar no Documents ou Application Support por não entenderem as diferenças entre esses diretórios.

Uma propriedade crítica do Caches: a aplicação deve lidar corretamente com situações em que um arquivo de cache foi excluído pelo sistema. Se remover o cache quebrar a funcionalidade da aplicação, então os dados estão armazenados no diretório errado.

Como obter o caminho para o Caches Directory

Em Swift, o caminho para o Caches Directory é obtido usando o método padrão do FileManager com .cachesDirectory. Esta é uma operação simples usada em praticamente toda aplicação iOS que trabalha com dados de rede.

import Foundation

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

// Save cached JSON
let cacheFile = cachesURL.appendingPathComponent("feed_cache.json")
let jsonData = try JSONSerialization.data(
    withJSONObject: response,
    options: [.prettyPrinted]
)
try jsonData.write(to: cacheFile)

Objective-C usa NSSearchPathForDirectoriesInDomains com NSCachesDirectory. Embora a Apple recomende a API Swift, o código Objective-C com Caches Directory permanece funcional e suportado.

@import Foundation;

NSArray *paths = NSSearchPathForDirectoriesInDomains(
    NSCachesDirectory,
    NSUserDomainMask,
    YES
);
NSString *cachesPath = paths.firstObject;
NSString *cacheFile = [cachesPath stringByAppendingPathComponent:@"feed_cache.plist"];

Os projetos Swift devem preferir a API baseada em URL: é type-safe e integra-se melhor com frameworks modernos como SwiftUI e Combine.

Quais dados armazenar no Caches

Caches Directory é ideal para várias categorias de dados que a aplicação usa para acelerar o desempenho, mas não é a única fonte de verdade. Escolher os dados certos para cache afeta diretamente a UX e o desempenho da aplicação.

Respostas de rede em cache

Respostas JSON de APIs, dados de feeds de notícias, listas de objetos — tudo o que a aplicação pode baixar novamente do servidor. Use URLCache para cache automático de respostas HTTP ou salve objetos serializados manualmente.

Imagens e arquivos de mídia

Imagens baixadas da rede são o caso de uso mais comum do Caches Directory. Bibliotecas como SDWebImage e Kingfisher salvam imagens em cache no Caches por padrão.

Se os dados não podem ser restaurados, eles não pertencem ao Caches. Este é o critério mais simples: imagine que amanhã o sistema excluirá todos os arquivos do Caches. Se a aplicação continuar funcionando corretamente, os dados estão armazenados corretamente.

Como o sistema gerencia a limpeza de cache

iOS gerencia automaticamente a limpeza do Caches Directory, mas os gatilhos e algoritmos exatos não são documentados pela Apple. Sabe-se que o sistema pode excluir arquivos do Caches quando o espaço em disco está baixo, bem como quando o recurso Offload Unused Apps está ativo.

O processo de limpeza é transparente para a aplicação: o sistema exclui arquivos sem notificação. A aplicação deve verificar a existência do arquivo antes de ler e recriá-lo se ausente. Não confiar no armazenamento de longo prazo é um requisito fundamental ao trabalhar com Caches.

De acordo com o artigo da Apple “File System Basics” (2024), a aplicação não deve esperar que os arquivos no Caches Directory estejam disponíveis entre sessões. Os desenvolvedores são aconselhados a implementar um mecanismo de fallback: se um arquivo em cache estiver faltando, baixe os dados da rede e salve-os novamente no Caches.

Um cenário separado é a descarrega da aplicação (Offload). Quando este recurso é ativado, o iOS remove a aplicação mas mantém seu Documents Directory. O Caches Directory é excluído no processo. Um usuário que restaura a aplicação não terá dados em cache — a aplicação deve baixá-los novamente.

Caches Directory vs Temporary Directory

A diferença entre os diretórios Caches e Temporary (tmp) frequentemente causa confusão entre os desenvolvedores. Ambos os diretórios armazenam dados temporários, mas com diferentes garantias de tempo de vida e propósito.

Escolha Caches se for benéfico manter dados entre inicializações da aplicação, mas eles podem ser restaurados. Use tmp se os dados forem necessários apenas na sessão atual e não tiverem valor após o término da aplicação.

Melhores práticas com Caches

Trabalhar com o Caches Directory requer seguir várias regras que ajudam a evitar perda de dados, comportamento inesperado da aplicação e problemas de desempenho.

Sempre verifique a existência do arquivo antes de ler

FileManager.fileExists(atPath:) deve ser chamado antes de cada leitura do Caches. Se o arquivo estiver faltando, carregue os dados da fonte original e salve no cache. Nunca presuma que um arquivo no Caches existe.

Limite o tamanho do cache

Defina um tamanho máximo para o Caches Directory na sua aplicação. Por exemplo, um limite de 50 MB para imagens e 10 MB para respostas JSON. Quando o limite for excedido, exclua os arquivos mais antigos por data de modificação.

import Foundation

func trimCache(to maxSizeBytes: Int) {
    let cachesURL = FileManager.default
        .urls(for: .cachesDirectory, in: .userDomainMask)
        .first!

    guard let enumerator = FileManager.default
        .enumerator(
            at: cachesURL,
            includingPropertiesForKeys: [.fileSizeKey, .contentModificationDateKey]
        )
    else { return }

    // Enumerate and remove old files
    // when exceeding size limit
}

Seguir estas práticas garante que a aplicação funcione corretamente independentemente das ações de limpeza de cache do sistema, e os usuários não encontrem perda inesperada de dados.