Une application mobile qui perd ses données dès que la 4G faiblit dans un parking ou un ascenseur donne une impression d'amateurisme immédiate, même quand le reste du code est soigné. Le offline-first n'est pas une fonctionnalité qu'on ajoute en fin de projet avec un package de cache : c'est une décision d'architecture qui conditionne la façon dont on modélise les données, dont on écrit les écrans et dont on pense les erreurs réseau. Voici comment poser cette architecture correctement, avec les compromis réels qu'elle impose.
Le problème concret
Un cas typique : une app de prise de commande terrain (livraison, maintenance, vente ambulante). L'utilisateur doit pouvoir créer une commande, la modifier, cocher une étape, même sans réseau. Au retour de connexion, tout doit se synchroniser avec le backend REST sans doublon ni perte.
L'erreur classique consiste à faire un cache "en lecture" avec shared_preferences ou Hive pour accélérer l'affichage, puis à bricoler des try/catch autour des appels HTTP pour "rejouer plus tard". Ça fonctionne en démo, puis ça casse dès qu'un utilisateur crée deux commandes hors-ligne, revient en ligne, et se retrouve avec une commande en double ou une mise à jour écrasée par une version plus ancienne.
Pourquoi ça arrive : le mécanisme sous-jacent
Le offline-first casse une hypothèse implicite de la plupart des architectures mobiles : que l'état local est une simple projection de l'état serveur. Dès qu'on autorise l'écriture hors-ligne, on a deux sources de vérité temporairement divergentes, et il faut un protocole explicite pour les réconcilier :
- Perte d'ordre : les requêtes mises en file pendant une coupure ne partent pas forcément dans l'ordre de création une fois le réseau revenu, surtout si on relance plusieurs isolats ou si l'app est tuée puis relancée par l'OS.
- Doublons : un
POST /ordersrejoué après un timeout réseau (le serveur a peut-être déjà traité la requête, la réponse s'est juste perdue) crée une deuxième ressource si on n'a pas de clé d'idempotence. - Conflits d'écriture : un enregistrement modifié localement peut avoir été modifié entre-temps côté serveur (par un autre appareil, un back-office). Sans stratégie de résolution, c'est systématiquement le dernier écrit qui gagne, ce qui n'est pas toujours souhaitable.
Ignorer ces trois points, c'est construire un système qui semble marcher sur le réseau de bureau et qui s'effondre sur le terrain, précisément là où le offline-first était censé apporter de la valeur.
Diagnostiquer avant de corriger
Avant de choisir une solution, il faut objectiver le problème : combien de mutations sont en attente, depuis combien de temps, et combien échouent silencieusement. Deux leviers pratiques :
- Exposer un compteur de la file de synchronisation dans l'UI (même discret, un badge) pour que le support puisse reproduire les signalements utilisateurs.
- Logger chaque transition d'état d'une mutation (
pending→syncing→synced/failed) avec un identifiant stable, pour pouvoir retracer un incident précis dans Sentry ou équivalent plutôt que de deviner.
enum SyncStatus { pending, syncing, synced, failed }
class SyncLogger {
static void log(String mutationId, SyncStatus status, {String? error}) {
debugPrint('[sync] $mutationId -> $status ${error ?? ''}');
// En prod : envoyer vers Sentry/Crashlytics avec mutationId en tag
}
}
L'architecture qui tient la route
La base : séparer clairement une source de vérité locale (base SQLite via drift, ou Isar), un client REST, et un service de synchronisation qui orchestre les deux. Les écrans ne parlent jamais directement au réseau ; ils lisent et écrivent dans la base locale, qui devient le seul état observé par l'UI.
La base locale comme source de vérité
// tables.drift.dart (schéma drift)
class Orders extends Table {
TextColumn get id => text()(); // UUID généré côté client
TextColumn get remoteId => text().nullable()();
TextColumn get payload => text()(); // JSON de la commande
IntColumn get status => intEnum<SyncStatus>()();
DateTimeColumn get updatedAt => dateTime()();
DateTimeColumn get lastSyncedAt => dateTime().nullable()();
@override
Set<Column> get primaryKey => {id};
}
L'ID local est un UUID généré au moment de la création, pas l'ID serveur. C'est ce qui permet de créer une commande hors-ligne, de l'afficher immédiatement, puis de la relier à un remoteId une fois synchronisée, sans jamais bloquer l'UI sur une réponse réseau.
La file de mutations avec idempotence
Chaque écriture passe par une file persistée, pas par un simple retry en mémoire qui disparaît si l'app est tuée.
class SyncQueue {
final AppDatabase db;
SyncQueue(this.db);
Future<void> enqueueCreateOrder(Order order) async {
await db.into(db.orders).insert(
OrdersCompanion.insert(
id: order.id, // UUID client, servira d'idempotency key
payload: jsonEncode(order.toJson()),
status: SyncStatus.pending,
updatedAt: DateTime.now(),
),
);
}
Future<void> processPending(ApiClient api) async {
final pending = await (db.select(db.orders)
..where((o) => o.status.equalsValue(SyncStatus.pending)))
.get();
for (final order in pending) {
try {
final response = await api.post(
'/orders',
headers: {'Idempotency-Key': order.id},
body: order.payload,
);
await db.update(db.orders).replace(
order.copyWith(
status: SyncStatus.synced,
remoteId: Value(response['id']),
lastSyncedAt: Value(DateTime.now()),
),
);
} on DioException catch (e) {
if (e.response?.statusCode == 409) {
// Conflit détecté côté serveur : à résoudre, pas à ignorer
await _handleConflict(order, e.response!.data);
}
// Sinon : reste en pending, retry au prochain cycle
}
}
}
}
L'en-tête Idempotency-Key (pattern standard côté Stripe et repris par de nombreuses API internes) doit être supporté côté backend : si la clé a déjà été traitée, le serveur renvoie la ressource existante au lieu d'en créer une nouvelle. C'est la seule façon fiable d'éviter les doublons sur un POST rejoué.
Détecter le retour réseau sans boucler
final connectivitySubscription = Connectivity()
.onConnectivityChanged
.where((result) => result != ConnectivityResult.none)
.listen((_) => syncQueue.processPending(apiClient));
Le package connectivity_plus évite d'avoir à réinventer la détection d'état réseau, mais attention : un changement de ConnectivityResult ne garantit pas qu'Internet est réellement joignable (un Wi-Fi captif sans accès réel déclenche le même événement). Pour une synchronisation critique, un ping léger vers une route de santé du backend avant de lancer processPending évite des cycles d'échec inutiles.
Les compromis à assumer
- drift/Isar vs Hive : Hive est plus simple pour du cache clé-valeur, mais sans schéma relationnel ni requêtes, ce qui devient vite limitant dès qu'on a des relations entre entités (commandes, lignes, clients).
driftimpose plus de boilerplate initial mais donne de vraies requêtes SQL typées et des migrations versionnées. - Résolution de conflits automatique vs manuelle : last-write-wins est simple à implémenter mais perd silencieusement des données métier. Pour des champs critiques (quantités, montants), il est souvent préférable de renvoyer le conflit à l'utilisateur plutôt que de trancher automatiquement.
- Packages tout-en-un (
brick,flutter_data) accélèrent le démarrage mais imposent leurs propres conventions de modélisation ; ils valent le coup sur un projet neuf, moins sur un projet existant avec un client REST déjà en place.
Quand la solution "simple" ne suffit plus
Ce pattern (file locale + idempotence + reprise réseau) couvre la grande majorité des apps métier avec un seul utilisateur par ressource. Il devient insuffisant dès qu'on a de l'édition collaborative en quasi temps réel (plusieurs appareils modifiant la même ressource simultanément) : il faut alors des structures de données convergentes (CRDT) ou une synchronisation serveur-autoritaire avec diff de champs, pas une simple clé d'idempotence. De même, si la synchronisation doit continuer même app fermée, WorkManager (Android) et les tâches en arrière-plan iOS (BGTaskScheduler via background_fetch) deviennent nécessaires, avec leurs propres contraintes d'exécution limitée par l'OS.
À retenir
Le offline-first se résout avec une base locale comme unique source de vérité pour l'UI, une file de mutations persistée et idempotente, et une stratégie de conflit explicite plutôt qu'implicite. Les packages existants (drift, connectivity_plus) couvrent la plomberie ; la vraie décision d'architecture porte sur qui résout les conflits, et à quel moment.
