Diretório de documentos numa aplicação móvel — o que é, propósito e como organizar o armazenamento

O que é o diretório de documentos da aplicação?

O diretório de documentos é um armazenamento especializado dentro da sandbox da aplicação, projetado para o armazenamento permanente de ficheiros do utilizador. Ao contrário da cache, os ficheiros neste diretório são considerados importantes para o utilizador: o sistema não os elimina quando falta espaço, são preservados durante as atualizações da aplicação e são copiados durante a sincronização do dispositivo. No iOS, o diretório Documents faz parte do contentor Sandbox e é automaticamente incluído na cópia de segurança do iCloud. No Android, não existe um equivalente direto — o equivalente é context.filesDir, que também se destina a ficheiros permanentes mas não tem um mecanismo de backup integrado.

A diferença entre o diretório de documentos e o armazenamento interno no Android é mínima: ambos estão localizados na sandbox da aplicação, ambos são eliminados ao desinstalar, ambos são inacessíveis a outras aplicações. A principal diferença é semântica: o diretório Documents assume que os ficheiros são criados ou importados pelo utilizador, enquanto o armazenamento interno pode conter ficheiros internos da aplicação (bases de dados, configurações). No iOS, a diferença é mais substancial: o Documents é copiado automaticamente, enquanto o Library/Application Support não. Isto afeta a estratégia de armazenamento: coloque apenas o que o utilizador gostaria de restaurar num novo dispositivo em Documents, e os dados internos que a aplicação pode recriar em Application Support.

A arquitetura de sandbox garante que outras aplicações não possam aceder ao diretório de documentos da sua aplicação. No iOS, aceder aos Documents de outras aplicações é impossível sem jailbreak. No Android, o acesso root permite ler o filesDir de qualquer aplicação, pelo que os dados confidenciais (tokens, chaves de encriptação) devem ser protegidos adicionalmente com EncryptedSharedPreferences ou EncryptedFile da biblioteca AndroidX Security.

Que dados são armazenados no diretório de documentos

O diretório de documentos deve armazenar dados que são valiosos para o utilizador e devem estar acessíveis após reiniciar a aplicação ou restaurar o dispositivo. Nem todos os ficheiros são adequados para armazenamento neste diretório — a escolha depende do tipo de dados e do cenário de utilização.

Documentos e ficheiros do utilizador

Os ficheiros do utilizador são o conteúdo principal do diretório de documentos. Podem ser documentos de texto criados num editor, imagens tiradas com a câmara da aplicação, relatórios PDF exportados, gravações de áudio, notas. Cada um destes ficheiros é criado pelo utilizador ou a seu pedido e deve estar acessível em qualquer momento. No iOS, os ficheiros do Documents são exibidos na aplicação Files do sistema, permitindo ao utilizador geri-los através do gestor de ficheiros padrão. No Android, não existe uma exibição semelhante — a aplicação deve fornecer ela própria uma interface para ver os ficheiros guardados.

Bases de dados e configurações da aplicação

As bases de dados SQLite e os ficheiros de configuração são geralmente armazenados perto do diretório de documentos, mas não dentro dele. No iOS, as bases de dados são colocadas em Library/Application Support, pois não devem aparecer na aplicação Files nem ser copiadas separadamente. No Android, as bases de dados são criadas por defeito em /data/data/<package>/databases/ através do Room ou SQLiteOpenHelper. Se a base de dados contiver conteúdo do utilizador (notas, diário, registos financeiros), pode ser colocada em filesDir para garantir a cópia de segurança do sistema. O Room permite especificar um diretório de armazenamento personalizado para a base de dados através do callback RoomDatabase.Builder.

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

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

Dados exportados e importados

Os ficheiros que o utilizador importa de outras aplicações ou exporta da sua aplicação também devem ser guardados no diretório de documentos. No iOS, a importação através do UIDocumentPickerViewController coloca automaticamente uma cópia do ficheiro em Documents ao usar o parâmetro asCopy: true. No Android, a importação através do diálogo SAF também cria uma cópia do ficheiro na sandbox da aplicação. Ao exportar dados (por exemplo, criar um ficheiro CSV com contactos), guarde o ficheiro primeiro em Documents/filesDir e depois ofereça ao utilizador a opção de o partilhar através do Share Sheet. Isto garante que, mesmo que o utilizador se esqueça de guardar o ficheiro depois de o enviar, uma cópia permanece na aplicação para uso posterior.

Como trabalhar com o diretório de documentos no Android

No Android, a função do diretório de documentos é desempenhada por context.filesDir. Além disso, está disponível o diretório context.externalFilesDir no cartão SD, mas não garante a integridade dos dados. Vamos analisar as principais técnicas para trabalhar com estes diretórios.

Aceder e gerir ficheiros através de filesDir

filesDir é o diretório principal para ficheiros permanentes da aplicação no Android. Está localizado na sandbox da aplicação e é completamente eliminado ao desinstalar. Para obter uma instância File, use context.filesDir, que devolve o caminho para /data/data/<package>/files/. Para criar e ler ficheiros, use operações padrão Java/Kotlin File ou os métodos Context openFileInput() e openFileOutput(), que recebem um nome de ficheiro e devolvem FileInputStream/FileOutputStream. O método openFileOutput() cria automaticamente o ficheiro em filesDir se ainda não existir e permite especificar o modo de acesso: MODE_PRIVATE (apenas a aplicação atual), MODE_APPEND (anexar) ou MODE_WORLD_READABLE (obsoleto, não usado desde 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()
}

Características de armazenamento no Android 10+

No Android 10+, o modelo Scoped Storage não afeta o filesDir — o acesso completo à sandbox própria da aplicação permanece. Todas as operações de leitura e escrita dentro de filesDir não requerem permissões adicionais. No entanto, se tentar aceder aos ficheiros de outra aplicação através de filesDir, obterá uma exceção. Para partilhar ficheiros, use FileProvider, que cria um URI de conteúdo temporário para transferir um ficheiro para outra aplicação. O FileProvider é declarado no AndroidManifest.xml através da tag <provider> e configurado num ficheiro XML de caminhos. Este é o mecanismo padrão para transferir ficheiros entre aplicações, utilizado, por exemplo, ao enviar uma imagem através de Intent com ACTION_SEND.

Como trabalhar com o diretório de documentos no iOS

No iOS, o Documents Directory faz parte do contentor Sandbox da aplicação com um estatuto especial. Os ficheiros deste diretório são automaticamente incluídos no backup do iCloud, exibidos na aplicação Files e preservados durante as atualizações da aplicação através da App Store.

Diretório de documentos e backup

O backup automático do Documents é uma vantagem chave do iOS. Quando o utilizador liga o dispositivo ao iTunes ou ativa o iCloud Backup, todos os ficheiros de Documents/ são copiados para o backup. Ao restaurar num novo dispositivo, o utilizador obtém todos os seus ficheiros sem ações adicionais. No entanto, esta vantagem torna-se uma desvantagem se a aplicação armazenar grandes quantidades de dados em Documents: o tempo de backup aumenta e o armazenamento do iCloud pode esgotar-se rapidamente. Portanto, o Documents deve armazenar apenas os ficheiros de que o utilizador realmente necessita durante o restauro. Ficheiros temporários, cache e dados recriáveis devem estar em Caches ou Library/Application Support. A Apple recomenda excluir do backup os ficheiros que podem ser transferidos novamente da Internet, através do atributo isExcludedFromBackup.

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

let fileURL = docsURL.appendingPathComponent("notes.txt")
let text = "Conteúdo da nota"
try text.write(to: fileURL, atomically: true, encoding: .utf8)

iCloud Drive e sincronização entre dispositivos

O iCloud Drive permite sincronizar ficheiros do Documents entre os dispositivos de um utilizador. Para ativar a sincronização, a aplicação deve usar as APIs NSDocument ou UIDocument, que gerem automaticamente o versionamento e a resolução de conflitos. Uma abordagem alternativa é usar o iCloud com CloudKit, que proporciona um controlo mais flexível sobre a sincronização, mas requer configuração no CloudKit Dashboard. Ao usar o iCloud Drive, certifique-se de que trata corretamente os conflitos de edição (merge ou last-write-wins) e informa o utilizador sobre o estado da sincronização através da interface da aplicação. O iCloud não garante sincronização instantânea — o atraso pode variar de alguns segundos a vários minutos, dependendo do tamanho do ficheiro e da qualidade da ligação. Para dados críticos, utilize escrita transacional e versionamento para que, em caso de conflito, a versão anterior do ficheiro possa ser restaurada.

Diferenças do diretório de cache e melhores práticas

Escolher corretamente entre Documents Directory e Cache Directory determina a fiabilidade do armazenamento de dados do utilizador. Um erro na escolha leva à perda de dados (se ficheiros importantes forem armazenados na cache) ou ao transbordo do backup (se ficheiros temporários forem armazenados em Documents).

As melhores práticas para usar o diretório de documentos incluem várias regras-chave. Primeiro, peça sempre confirmação do utilizador antes de eliminar ficheiros deste diretório. Ao contrário da cache, eliminar um documento pode levar à perda irreversível de conteúdo do utilizador. Segundo, implemente versionamento de ficheiros: ao sobrescrever um ficheiro existente, guarde a versão anterior com o sufixo _backup ou use mecanismos de Snapshot. Terceiro, forneça ao utilizador uma interface para ver, renomear, eliminar e exportar ficheiros do diretório de documentos. No iOS, os ficheiros do Documents são automaticamente exibidos em Files; no Android, precisa de implementar o seu próprio gestor de ficheiros ou usar bibliotecas de terceiros.

Preste especial atenção à migração de dados durante as atualizações da aplicação. Se a nova versão alterar a estrutura de armazenamento de ficheiros (por exemplo, mover dados de uma subpasta para outra ou alterar o formato do ficheiro), implemente uma migração única no primeiro arranque após a atualização. Armazene o número de versão do esquema de dados em SharedPreferences e execute a migração se não coincidirem. Não elimine os ficheiros antigos antes de a migração terminar — em caso de falha, o utilizador não deve perder dados. Se a migração envolver conversão de formato (por exemplo, mudar de JSON para SQLite), guarde os ficheiros originais como backup num diretório separado com a data da migração. O utilizador deve poder reverter as alterações através das definições da aplicação nos primeiros 30 dias após a atualização, conforme recomendado pelas Apple Human Interface Guidelines.