Refactoriser un prototype en modules avec un risque minimal

Pourquoi les prototypes deviennent risqués à modifier

Un prototype donne l'impression d'aller vite parce que tout est proche. Une route interroge la base de données, façonne la réponse, et l'UI l'affiche. Cette rapidité est réelle, mais elle cache un coût : dès que d'autres fonctionnalités arrivent, le premier « chemin rapide » devient celui dont tout dépend.

Ce qui casse en premier n'est généralement pas le nouveau code. Ce sont les anciennes hypothèses.

Un petit changement sur une route peut silencieusement modifier la forme de la réponse et casser deux écrans. Une requête « temporaire » copiée en trois endroits commence à retourner des données légèrement différentes, et personne ne sait laquelle est correcte.

C'est aussi pour cela que les gros rewrites échouent, même avec de bonnes intentions. Ils changent la structure et le comportement en même temps. Quand des bugs apparaissent, on ne sait pas si la cause est un nouveau choix de conception ou une erreur basique. La confiance baisse, le périmètre s'élargit, et le rewrite traîne.

Un refactor à faible risque signifie garder les changements petits et réversibles. Vous devez pouvoir vous arrêter après n'importe quelle étape et avoir toujours une application fonctionnelle. Les règles pratiques sont simples :

• Un objectif clair par changement (déplacer du code, ne pas changer ce qu'il fait)
• Cycles courts pour pouvoir retester le même flux utilisateur à chaque fois
• Un plan de rollback ennuyeux que vous pouvez exécuter rapidement
• Le nouveau code cohabite avec l'ancien tant qu'il ne fait pas ses preuves

Routes, services, accès base de données et UI s'emmêlent quand chaque couche commence à faire le travail des autres. Démêler n'est pas courir après une « architecture parfaite ». C'est déplacer un fil à la fois.

Poser des règles avant de toucher le code

Considérez le refactor comme un déménagement, pas une rénovation. Gardez le comportement identique et facilitez la structure pour la modifier plus tard. Si vous « améliorez » aussi des fonctionnalités en réorganisant, vous perdrez la trace de ce qui a cassé et pourquoi.

Écrivez ce qui ne changera pas encore. Éléments courants « pas encore » : nouvelles fonctionnalités, redesign UI, changements de schéma de BD et travail de performance. Cette limite est ce qui maintient le travail à faible risque.

Choisissez un « parcours principal » et protégez-le. Prenez quelque chose que les gens font quotidiennement, par exemple :

se connecter → créer un élément → voir la liste → modifier l'élément → enregistrer

Vous relancerez ce flux après chaque petit pas. S'il se comporte de la même façon, vous pouvez continuer.

Mettez d'accord un rollback avant le premier commit. Le rollback doit être ennuyeux : un git revert, un drapeau de fonctionnalité de courte durée, ou un snapshot de plateforme que vous pouvez restaurer. Si vous construisez dans Koder.ai, les snapshots et rollback peuvent être un filet de sécurité utile pendant la réorganisation.

Gardez une petite définition de done par étape. Pas besoin d'une grande checklist, juste assez pour empêcher un « déplacer + changer » de se glisser :

• Les mêmes entrées produisent les mêmes sorties (y compris erreurs et états vides)
• Le parcours principal passe un test manuel rapide (ou une petite vérification automatisée)
• Les changements restent dans le périmètre de l'étape (routes seulement, ou services seulement)
• Le rollback est vérifié au moins une fois (vous l'essayez réellement)
• Une courte note explique ce qui a été déplacé et où il vit maintenant

Si le prototype a un seul fichier qui gère routes, requêtes BD et formatage UI, ne tout séparez pas d'un coup. Déplacez d'abord seulement les handlers de route dans un dossier et gardez la logique telle quelle, même si elle est copiée. Une fois stable, extrayez les services et l'accès BD dans des étapes ultérieures.

Inventaire rapide : routes, écrans et chemins de données

Avant de commencer, cartographiez ce qui existe aujourd'hui. Ce n'est pas une refonte. C'est une étape de sécurité pour pouvoir faire des mouvements petits et réversibles.

Listez chaque route ou endpoint et écrivez une phrase simple sur ce qu'il fait. Incluez les routes UI (pages) et les routes API (handlers). Si vous avez utilisé un générateur piloté par chat et exporté du code, traitez-le de la même façon : l'inventaire doit faire correspondre ce que les utilisateurs voient à ce que le code touche réellement.

Un inventaire léger et utile :

• Route/endpoint + but (exemple : "/checkout" affiche le formulaire de paiement)
• Écran/composant UI qui le déclenche
• Règles métier impliquées (tarification, validation, permissions)
• Tables de la base concernées et type d'accès (lecture/écriture/transaction)
• Copies et répétitions (la même validation copiée dans trois fichiers)

Pour chaque route, écrivez une note « chemin des données » :

Événement UI → handler → logique → requête BD → réponse → mise à jour UI

Au fur et à mesure, taguez les zones risquées pour ne pas les changer accidentellement pendant que vous nettoyez le code autour :

• Paiements et facturation
• Auth, sessions, rôles
• Migrations de base et scripts de seed
• Jobs en arrière-plan et tâches planifiées
• Tout ce qui s'exécute dans une transaction

Enfin, esquissez une carte cible simple des modules. Gardez-la peu profonde. Vous choisissez des destinations, vous ne construisez pas un nouveau système :

routes/handlers, services, db (queries/repositories), ui (screens/components)

Si vous ne pouvez pas expliquer où devrait vivre un morceau de code, cette zone est un bon candidat pour un refactor plus tard, après avoir gagné en confiance.

Étape 1 : Stabiliser les routes sans changer la logique

Commencez par traiter les routes (ou controllers) comme une frontière, pas un endroit pour améliorer le code. L'objectif est de garder chaque requête avec le même comportement tout en plaçant les endpoints à des endroits prévisibles.

Créez un module fin par domaine fonctionnel, comme users, orders ou billing. Évitez de « nettoyer en déplaçant ». Si vous renommez, réorganisez des fichiers et réécrivez la logique dans le même commit, il devient difficile de repérer ce qui a cassé.

Séquence sûre :

• Groupez les handlers de route existants par fonctionnalité, même si l'intérieur est désordonné.
• Déplacez d'abord seulement le code de raccordement : lire les params, validation basique, appeler les mêmes fonctions existantes en lesquelles vous avez confiance.
• Gardez les réponses identiques : codes de statut, messages d'erreur et formes de payload.
• Ajoutez une petite vérification pour le parcours principal par route (un appel happy-path qui doit rester fonctionnel).

Exemple concret : si vous avez un fichier unique avec POST /orders qui parse du JSON, vérifie des champs, calcule des totaux, écrit dans la BD et retourne la commande, ne le réécrivez pas. Extrayez le handler dans orders/routes et appelez l'ancienne logique, par exemple createOrderLegacy(req). Le nouveau module de route devient la porte d'entrée ; la logique legacy reste intacte pour l'instant.

Si vous travaillez avec du code généré (par exemple, un backend Go produit dans Koder.ai), l'état d'esprit ne change pas. Placez chaque endpoint à un endroit prévisible, enveloppez la logique legacy et prouvez que la requête commune réussit toujours.

Étape 2 : Extraire la logique métier dans des services

Les routes ne sont pas un bon foyer pour les règles métier. Elles grossissent vite, mélangent les préoccupations, et chaque changement semble risqué car vous touchez à tout.

Définissez une fonction de service par action utilisateur. Une route doit collecter les entrées, appeler un service et retourner une réponse. Gardez les appels BD, les règles de tarification et les vérifications de permission hors des routes.

Les fonctions de service restent plus faciles à raisonner quand elles ont un travail unique, des entrées claires et une sortie claire. Si vous continuez à ajouter « et aussi… », séparez-les.

Un modèle de nommage qui marche généralement :

• CreateOrder(input) -> order
• CancelOrder(orderId, actor) -> result
• GetOrderSummary(orderId) -> summary

Gardez les règles dans les services, pas dans l'UI. Par exemple : au lieu que l'UI désactive un bouton selon « les utilisateurs premium peuvent créer 10 commandes », appliquez cette règle dans le service. L'UI peut toujours afficher un message amical, mais la règle vit en un seul endroit.

Avant d'aller plus loin, ajoutez juste assez de tests pour rendre les changements réversibles :

• Un test happy-path qui crée/met à jour correctement
• Un test error-path (champ requis manquant, permission refusée)

Si vous utilisez un outil d'itération rapide comme Koder.ai pour générer ou itérer vite, les services deviennent votre ancre. Routes et UI peuvent évoluer, mais les règles restent stables et testables.

Étape 3 : Isoler l'accès à la base de données en toute sécurité

Une fois les routes stables et les services en place, cessez de laisser la base de données être « partout ». Cachez les requêtes brutes derrière une petite couche d'accès aux données.

Créez un petit module (repository/store/queries) qui expose quelques fonctions avec des noms évidents, comme GetUserByEmail, ListInvoicesForAccount ou SaveOrder. Ne cherchez pas l'élégance ici. Visez un endroit évident pour chaque chaîne SQL ou appel ORM.

Gardez cette étape strictement structurelle. Évitez les changements de schéma, les ajustements d'index ou les migrations « tant qu'on y est ». Ceux-ci méritent leur propre modification planifiée et rollback.

Mettre les transactions au même endroit

Une odeur commune de prototype est des transactions dispersées : une fonction démarre une transaction, une autre en ouvre une silencieusement, et la gestion d'erreur varie selon les fichiers.

Au lieu de cela, créez un point d'entrée qui exécute un callback dans une transaction, et laissez les repositories accepter un contexte de transaction.

Gardez les mouvements petits :

• Déplacez une requête à la fois dans le repository, en gardant les mêmes entrées/sorties.
• Faites appeler les services par la nouvelle fonction de repository directement (pas de logique supplémentaire).
• Centralisez begin/commit/rollback de transaction dans un helper.
• Standardisez le mapping d'erreurs (par exemple, « not found » vs « unexpected error »).

Par exemple, si « Create Project » insère un projet puis insère des settings par défaut, enveloppez les deux appels dans un helper de transaction. Si quelque chose échoue à mi-chemin, vous n'obtenez pas un projet sans ses settings.

Une fois que les services dépendent d'une interface plutôt que d'un client BD concret, vous pouvez tester la plupart du comportement sans base réelle. Cela réduit la peur, qui est le but de cette étape.

Étape 4 : Nettoyer les composants UI sans redesign

Le nettoyage UI ne vise pas à embellir. Il vise à rendre les écrans prévisibles et à réduire les effets secondaires surprises.

Groupez le code UI par fonctionnalité, pas par type technique. Un dossier fonctionnel peut contenir son écran, des composants plus petits et des helpers locaux. Quand vous voyez du balisage répété (la même rangée de boutons, carte ou champ de formulaire), extrayez-le, mais conservez le balisage et le style identiques.

Gardez les props sobres. Passez seulement ce dont le composant a besoin (chaînes, ids, booléens, callbacks). Si vous passez un objet géant « au cas où », définissez une forme plus petite.

Déplacez les appels API hors des composants UI. Même avec une couche de service, le code UI contient souvent de la logique fetch, des retries et du mapping. Créez un petit module client par fonctionnalité (ou par zone API) qui renvoie des données prêtes à l'emploi pour l'écran.

Ensuite, rendez la gestion du chargement et des erreurs cohérente entre les écrans. Choisissez un pattern et réutilisez-le : un état de chargement prévisible, un message d'erreur cohérent avec une action de retry, et des états vides qui expliquent la prochaine étape.

Après chaque extraction, faites une vérification visuelle rapide de l'écran touché. Cliquez sur les actions principales, rafraîchissez la page et déclenchez un cas d'erreur. Les petits pas valent mieux que les gros rewrites UI.

Un exemple réaliste : refactoriser une fonctionnalité de bout en bout

Imaginez un petit prototype avec trois écrans : connexion, liste d'éléments, édition d'un élément. Ça fonctionne, mais chaque route mélange checks d'auth, règles métier, SQL et état UI. L'objectif est de transformer juste cette fonctionnalité en un module propre avec des changements que vous pouvez annuler.

Avant et après : ce qui se déplace où

Avant, la logique « items » peut être dispersée :

server/
  main.go
  routes.go
  handlers.go          # sign in + items + random helpers
  db.go                # raw SQL helpers used everywhere
web/
  pages/
    SignIn.tsx
    Items.tsx          # fetch + state + form markup mixed

Après, le comportement reste le même, mais les frontières sont plus claires :

server/
  routes/
    items_routes.go
  handlers/
    items_handler.go
  services/
    items_service.go
  repositories/
    items_repo.go
web/
  pages/
    Items.tsx
  components/
    ItemForm.tsx

Un passage de bout en bout (petit, réversible)

Commencez par déplacer le code sans changer la logique. Conservez les noms de fonctions et les formes de retour, de sorte qu'un rollback soit principalement des déplacements de fichiers.

Refactorez d'abord une route. Le handler devrait ne gérer que l'HTTP, pas les règles ou le SQL :

// handlers/items_handler.go
func (h *ItemsHandler) UpdateItem(w http.ResponseWriter, r *http.Request) {
  userID := h.auth.UserIDFromRequest(r) // same auth logic as before
  itemID := mux.Vars(r)["id"]

  var in UpdateItemInput
  json.NewDecoder(r.Body).Decode(&in)

  item, err := h.itemsService.UpdateItem(r.Context(), userID, itemID, in)
  if err != nil { writeError(w, err); return }
  writeJSON(w, item)
}

Ensuite, déplacez les règles métier dans un service. C'est ici que vous mettez des checks comme « l'utilisateur ne peut éditer que ses propres éléments » ou « le nom ne peut pas être vide ». Le service appelle un repository pour le travail BD :

// services/items_service.go
func (s *ItemsService) UpdateItem(ctx context.Context, userID, itemID string, in UpdateItemInput) (Item, error) {
  if strings.TrimSpace(in.Name) == "" { return Item{}, ErrInvalidName }
  return s.repo.UpdateItem(ctx, userID, itemID, in)
}

Puis isolez l'accès BD dans une fonction repository :

// repositories/items_repo.go
func (r *ItemsRepo) UpdateItem(ctx context.Context, userID, itemID string, in UpdateItemInput) (Item, error) {
  row := r.db.QueryRowContext(ctx,
    `UPDATE items SET name=$1 WHERE id=$2 AND user_id=$3 RETURNING id, name`,
    in.Name, itemID, userID,
  )
  var it Item
  err := row.Scan(&it.ID, &it.Name)
  return it, err
}

Côté UI, conservez la mise en page, mais extrayez le balisage de formulaire répété dans un composant partagé utilisé par les flux « new » et « edit » :

• pages/Items.tsx garde le fetch et la navigation
• components/ItemForm.tsx possède les champs, les messages de validation et le bouton de soumission

Si vous utilisez Koder.ai (koder.ai), son export de code source peut être utile avant des refactors plus profonds, et les snapshots/rollback peuvent vous aider à récupérer rapidement lorsqu'un déplacement tourne mal.

Pièges courants qui augmentent le risque

Le plus grand risque est de mélanger travail de « déplacement » et travail de « changement ». Quand vous déplacez des fichiers et réécrivez la logique dans le même commit, les bugs se cachent dans des diffs bruyants. Gardez les déplacements ennuyeux : mêmes fonctions, mêmes entrées, mêmes sorties, nouveau domicile.

Un autre piège est un nettoyage qui change le comportement. Renommer des variables est acceptable ; renommer des concepts ne l'est pas. Si status passe de chaînes à nombres, vous avez changé le produit, pas seulement le code. Faites-le plus tard avec des tests clairs et une release délibérée.

Patterns qui créent silencieusement des problèmes

Tôt, on est tenté de construire un grand arbre de dossiers et des couches multiples « pour le futur ». Cela vous ralentit souvent et rend plus difficile de voir où se trouve vraiment le travail. Commencez avec les plus petites frontières utiles, puis faites-les évoluer quand la prochaine fonctionnalité l'exige.

Surveillez aussi les raccourcis où l'UI accède directement à la base (ou appelle des requêtes brutes via un helper). Ça semble rapide, mais cela rend chaque écran responsable des permissions, règles de données et de la gestion d'erreur.

Facteurs de risque à éviter :

• Gros commits de refactor qui touchent beaucoup de fichiers et changent aussi la logique
• Formes de retour partagées qui changent sans mettre à jour tous les appelants
• Nouvelles couches ajoutées sans raison claire
• Gestion d'erreur aplatie (tout devient null ou un message générique)

Un petit exemple : si un écran attend { ok: true, data } mais que le nouveau service renvoie { data } et lève sur les erreurs, la moitié de l'app peut cesser d'afficher des messages conviviaux. Conservez d'abord l'ancienne forme à la frontière, puis migrez les appelants un par un.

Vérifications rapides avant de passer à l'étape suivante

Avant l'étape suivante, prouvez que vous n'avez pas cassé l'expérience principale. Lancez le même parcours principal à chaque fois (connexion, créer un élément, le voir, le modifier, le supprimer). La cohérence vous aide à repérer de petites régressions.

Utilisez une porte go/no-go simple après chaque étape :

• Le parcours principal fonctionne toujours de bout en bout, y compris les cas d'erreur courants.
• Routes/controllers sont fins : lire l'entrée, appeler un service, retourner une réponse.
• Services sont portables : appelables depuis routes, jobs en arrière-plan ou actions UI sans connaître HTTP.
• L'accès BD est centralisé avec un pattern de transaction unique et une gestion d'erreur cohérente.
• Le rollback est rapide et prouvé.

Si un point échoue, arrêtez et corrigez avant de construire dessus. Les petites fissures deviennent grandes plus tard.

Exercice rapide « peut-on annuler ça ? »

Juste après le merge, passez cinq minutes à vérifier que vous pouvez revenir en arrière :

• Revert du dernier commit sur une branche locale et confirmez que l'app démarre et que le parcours principal s'exécute.
• Désactivez le nouveau chemin de code (feature flag, switch de config ou condition) et confirmez que l'ancien comportement existe toujours.
• Vérifiez les logs et les écritures BD du parcours principal une fois pour confirmer que le stockage n'a pas changé.

Étapes suivantes : garder la modularité à mesure que le produit grandit

La victoire n'est pas le premier nettoyage. La victoire, c'est garder la forme quand vous ajoutez des fonctionnalités. Vous ne cherchez pas une architecture parfaite. Vous rendez les changements futurs prévisibles, petits et faciles à annuler.

Choisissez le prochain module selon l'impact et le risque, pas selon l'irritation. Bons candidats : parties que les utilisateurs touchent souvent et dont le comportement est déjà compris. Laissez les zones floues ou fragiles jusqu'à ce que vous ayez de meilleurs tests ou de meilleures réponses produit.

Gardez un rythme simple : petites PR qui déplacent une chose, cycles de revue courts, releases fréquentes et règle d'arrêt (si le périmètre s'étend, scindez-le et livrez la petite partie).

Avant chaque étape, définissez un point de rollback : un tag git, une branche de release ou un build déployable que vous savez fonctionnel. Si vous construisez dans Koder.ai, le Planning Mode peut vous aider à étager les changements pour ne pas refactoriser trois couches à la fois.

Règle pratique pour une architecture modulaire : chaque nouvelle fonctionnalité suit les mêmes frontières. Les routes restent fines, les services possèdent les règles métier, le code BD vit en un seul endroit, et les composants UI se concentrent sur l'affichage. Quand une nouvelle fonctionnalité enfreint ces règles, refactorisez tôt pendant que le changement est encore petit.