Maintenez le code source exporté synchronisé grâce à des règles de gouvernance claires

Quel problème vous résolvez (en termes simples)

Quand une plateforme régénère votre appli, elle peut réécrire de larges parties du code. Cela garde le code propre, mais cela signifie aussi que toute modification manuelle dans des fichiers générés peut disparaître la prochaine fois que vous régénérez ou publiez une nouvelle build.

L'objectif réel n'est pas de « ne jamais exporter le code ». Il s'agit de garder le modèle visuel comme source de vérité pour que les changements restent cohérents et reproductibles. Dans AppMaster, ce modèle inclut votre schéma de données, vos processus métier, vos endpoints API et vos écrans UI. Quand le modèle est correct, la régénération devient une action sûre et routinière plutôt qu'un événement stressant.

« Code source exporté » signifie généralement prendre le backend Go généré, l'app web Vue3 et les apps mobiles Kotlin/SwiftUI et les mettre sous votre contrôle. Les équipes exportent pour des raisons pratiques : revues de sécurité, hébergement interne, règles d'infrastructure spécifiques, intégrations particulières ou maintien à long terme en dehors de la plateforme.

Les problèmes apparaissent quand le dépôt exporté commence à vivre sa propre vie. Quelqu'un corrige un bug directement dans des fichiers générés, ajoute une fonctionnalité « rapidement » dans le code, ou modifie manuellement la couche base de données. Ensuite, le modèle change (renommage d'un champ, nouvel endpoint, process métier modifié), l'application est régénérée, et vous vous retrouvez avec de la dérive, des merges douloureux ou du travail perdu.

La gouvernance est surtout une question de processus, pas d'outillage. Elle répond à quelques questions de base :

• Où les modifications sont-elles autorisées, et où sont-elles interdites ?
• Qui peut approuver des changements au modèle visuel vs au dépôt exporté ?
• Comment enregistrez-vous pourquoi un changement a été fait dans le code plutôt que dans le modèle ?
• Que se passe-t-il quand la régénération entre en conflit avec une extension personnalisée ?

Quand ces règles sont claires, la régénération cesse d'être un risque. Elle devient un moyen fiable de livrer des mises à jour tout en protégeant le petit ensemble de parties écrites à la main qui doivent vraiment exister.

Choisir la source de vérité et s'y tenir

Pour garder le code source exporté synchronisé avec une plateforme régénératrice, il vous faut une règle par défaut claire : où vivent les changements ?

Pour des plateformes comme AppMaster, la règle la plus sûre est simple : le modèle visuel est la source de vérité. Ce qui définit le comportement quotidien du produit doit vivre dans le modèle, pas dans le dépôt exporté. Cela inclut généralement votre modèle de données, la logique métier, les endpoints API et les flux UI principaux.

Le code exporté reste utile, mais traitez-le comme un artefact de build plus une petite zone explicitement autorisée pour le travail que le modèle ne peut pas exprimer correctement.

Une politique que la plupart des équipes peuvent suivre ressemble à ceci :

• Si cela change le comportement produit, cela appartient au modèle visuel.
• Si c'est un connecteur vers quelque chose d'externe, cela peut vivre en dehors du modèle comme un adaptateur mince.
• Si c'est une utilité partagée (ajustements de logging, petit helper de parsing), cela peut vivre en dehors du modèle comme une librairie.
• Si c'est une configuration spécifique client ou environnement, gardez-la hors du modèle et injectez-la au moment du déploiement.
• Si c'est un correctif de performance ou de sécurité, vérifiez d'abord s'il peut être exprimé dans le modèle. Sinon, documentez l'exception.

Gardez volontairement la zone autorisée petite. Plus elle grandit, plus la régénération risque d'écraser des changements ou de créer de la dérive silencieuse.

Décidez aussi qui peut approuver les exceptions. Par exemple, seul un tech lead peut approuver des changements de code affectant l'authentification, la validation des données ou les workflows critiques. Ajoutez une règle simple pour la durée des exceptions, comme « revoir après le prochain cycle de régénération », pour que les correctifs temporaires ne deviennent pas des forks permanents.

Quand exporter le code a du sens (et quand non)

Exporter le code source peut être la bonne décision, mais seulement si vous êtes clair sur le pourquoi et ce que vous attendez comme changement par la suite. Avec une plateforme régénératrice comme AppMaster, la règle la plus sûre est de traiter le modèle visuel comme source de vérité et l'export comme quelque chose à inspecter, tester et déployer.

L'export a généralement du sens quand les équipes ont besoin d'une meilleure traçabilité (pouvoir montrer ce qui tourne en production), d'auto-hébergement, ou d'intégrations spéciales non couvertes par les modules intégrés. Cela aide aussi quand votre équipe sécurité exige un scan de code, ou quand vous voulez un plan de sortie indépendant du fournisseur.

La question clé est : avez-vous besoin d'accès au code ou de modifier le code ?

• Code en lecture seule (export read-only) : audits, revue de sécurité, reprise après sinistre, portabilité, expliquer le comportement aux parties prenantes.
• Modifications du code (export éditable) : ajouter des capacités bas-niveau qui doivent vivre en code, patcher une librairie tierce, respecter une contrainte d'exécution stricte que le modèle ne peut pas représenter.

L'export en lecture seule est plus simple, car vous pouvez régénérer souvent sans craindre d'écraser des modifications manuelles.

L'export éditable est là où les équipes se mettent en difficulté. Les changements manuels de longue durée sont une décision de gouvernance, pas une préférence de développeur. Si vous ne pouvez pas répondre à « où vivra ce changement dans un an ? », vous finirez par de la dérive : le modèle dit une chose, le code en production en dit une autre.

Une règle robuste : si le changement concerne la logique métier, la forme des données, le flux UI ou le comportement API, gardez-le dans le modèle. Si c'est un réel manque de la plateforme, autorisez les modifications de code seulement avec une propriété explicite, un pattern d'extension documenté et un plan clair pour gérer la régénération.

Concevoir des points d'extension sûrs pour que la régénération ne vous casse pas

Ne considérez jamais les fichiers générés comme un endroit où « ajouter juste une petite modification ». La régénération l'emportera tôt ou tard.

Commencez par tracer une ligne claire entre ce qui est détenu par le modèle visuel et ce qui est détenu par votre équipe. Avec AppMaster, le modèle peut régénérer le backend (Go), le web (Vue3) et le mobile (Kotlin/SwiftUI), donc supposez que tout ce qui est dans la zone générée peut être remplacé à tout moment.

Créez des frontières difficiles à franchir

Rendez la frontière visible dans votre repo et dans vos habitudes. Les gens font la mauvaise chose quand la bonne chose est inconfortable.

Quelques garde-fous qui fonctionnent en pratique :

• Mettez la sortie générée dans un dossier dédié traité en lecture seule.
• Placez le code personnalisé dans un dossier séparé avec ses propres points d'entrée de build.
• Exigez que le code personnalisé n'appelle le code généré que via des interfaces publiques (pas des fichiers internes).
• Ajoutez un contrôle CI qui échoue si des fichiers marqués « do not edit » sont modifiés.
• Ajoutez un commentaire en en-tête dans les fichiers générés indiquant clairement qu'ils seront écrasés.

Ce dernier point importe. Un message clair « DO NOT EDIT: regenerated from model » empêche des corrections bien intentionnées qui deviennent des casse-têtes plus tard.

Préférez des wrappers plutôt que des modifications directes

Quand vous avez besoin d'un comportement personnalisé, enveloppez le code généré plutôt que de le modifier. Pensez « couche adaptatrice » ou « fine façade » entre votre application et les parties générées.

Par exemple, si vous exportez un backend AppMaster et devez ajouter une intégration personnalisée à un système d'inventaire tiers, ne modifiez pas le handler d'endpoint généré. Au lieu de cela :

1. Gardez l'endpoint généré tel quel.

2. Ajoutez un service personnalisé (dans votre zone custom) qui appelle l'API d'inventaire.

3. Faites en sorte que la logique générée appelle votre service via une interface stable que vous possédez, comme un petit package avec une interface InventoryClient.

La régénération peut remplacer l'implémentation de l'endpoint, mais votre code d'intégration demeure intact. Seule la frontière d'interface doit rester stable.

Utilisez des points d'intégration stables quand c'est possible

Avant d'écrire du code personnalisé, vérifiez si vous pouvez attacher du comportement via des hooks stables comme des API, webhooks ou modules plateforme. Par exemple, AppMaster inclut des modules préconstruits pour Stripe et Telegram ou l'envoi email/SMS. Utiliser des points d'intégration stables réduit la fréquence des surprises liées à la régénération.

Documentez les zones « do not edit » sur une page courte et faites-les respecter par l'automatisation. Les règles qui vivent seulement dans la tête des gens ne survivent pas aux délais.

Structure de dépôt qui survit à la régénération

Un repo qui survit à la régénération rend une chose évidente en un coup d'œil : ce qui est généré, ce qui est humain, et ce qui est de la configuration. Si quelqu'un ne peut pas le comprendre en 10 secondes, des écrasements et des « correctifs mystères » arrivent.

Quand vous exportez depuis une plateforme régénératrice comme AppMaster, traitez l'export comme un artefact de build reproductible, pas comme une remise unique.

Une structure pratique sépare le code par propriété et cycle de vie :

• generated/ (ou appmaster_generated/) : tout ce qui peut être régénéré. Pas d'éditions manuelles.
• custom/ : toutes les extensions écrites à la main, adaptateurs et glue code.
• config/ : templates d'environnement, paramètres de déploiement, placeholders pour secrets (pas de vrais secrets).
• scripts/ : automatisations comme « regen + patch + test ».
• docs/ : une courte page de règles pour le dépôt.

Les conventions de nommage aident quand les gens sont pressés. Utilisez un préfixe cohérent pour les pièces custom (par exemple custom_ ou ext_) et ne reflétez la structure générée que lorsque cela aide vraiment. Si vous êtes tenté de toucher un fichier généré « juste cette fois », arrêtez-vous et déplacez ce changement dans custom/ ou dans un point d'extension convenu.

Le branching doit refléter la même séparation. Beaucoup d'équipes conservent deux types de travail visibles : les changements pilotés par le modèle (mises à jour du modèle visuel qui régénéreront le code) et les changements de code personnalisé (extensions et intégrations). Même dans un seul repo, exiger des labels PR ou une nomenclature de branches comme model/* et custom/* clarifie les revues.

Pour les releases, rendez la « régénération fraîche » non négociable. Le candidat de release doit commencer par régénérer dans generated/, réappliquer les patchs scriptés, puis lancer les tests. Si on ne peut pas reconstruire à partir de zéro, le dépôt dérive déjà.

Workflow étape par étape pour garder modèle et code alignés

Considérez chaque export comme une petite release : régénérez, vérifiez, réappliquez seulement ce qui est sûr, puis verrouillez avec un enregistrement clair. Cela garde le modèle visuel comme source de vérité tout en permettant un travail personnalisé contrôlé.

Un workflow qui tient la route :

• Régénérer depuis le modèle le plus récent : confirmez que le modèle visuel est à jour (schéma de données, logique métier, UI). Régénérez et exportez depuis cette version exacte.
• Faire un build propre et un quick smoke test : build depuis un état propre et exécutez un contrôle basique « est-ce que ça démarre ». Appelez un endpoint de santé pour le backend et chargez l'écran principal pour le web.
• Réappliquer le code personnalisé uniquement via des points d'extension approuvés : évitez de recoller des modifications dans des fichiers générés. Placez le comportement custom dans un module séparé, un wrapper ou un hook conçu pour survivre à la régénération.
• Exécuter des contrôles automatisés et comparer les sorties clés : lancez les tests, puis comparez ce qui compte : contrats API, migrations DB et vérifications rapides UI des écrans clés.
• Taguer la release et consigner ce qui a changé : écrivez une note courte séparant les changements du modèle (schéma, logique, UI) des changements custom (extensions, intégrations, configs).

Si quelque chose casse après régénération, corrigez d'abord dans le modèle lorsque c'est possible. Choisissez le code personnalisé seulement quand le modèle ne peut pas exprimer l'exigence, et gardez ce code isolé pour que la prochaine régénération ne l'efface pas.

Règles de gouvernance : rôles, approbations et contrôle des changements

Si votre plateforme peut régénérer du code (comme AppMaster), la gouvernance empêche le travail perdu. Sans propriété claire et un chemin d'approbation simple, les équipes modifient ce qui est le plus accessible, et la régénération devient une surprise récurrente.

Nommez quelques responsables. Vous n'avez pas besoin d'un comité, mais vous avez besoin de clarté.

• Mainteneur du modèle : propriétaire du modèle visuel et garant de la source de vérité pour les données, API et logique core.
• Mainteneur du code custom : propriétaire des extensions écrites à la main et des frontières d'extension sûres.
• Responsable release : coordonne le versioning, le calendrier de régénération et ce qui part en production.

Rendez les revues non négociables pour les zones à risque. Tout code custom touchant des intégrations (paiements, messaging, APIs externes) ou la sécurité (auth, rôles, secrets, accès aux données) doit nécessiter la revue du mainteneur custom plus un autre reviewer. Il ne s'agit pas de style mais d'éviter une dérive difficile à démêler.

Pour le contrôle des changements, utilisez une petite demande de changement que n'importe qui peut remplir. Gardez-la assez rapide pour que les gens l'utilisent.

• Ce qui a changé (modèle, paramètres d'export ou extension custom)
• Pourquoi ça a changé (besoin utilisateur ou incident)
• Risque (ce qui peut casser, qui est affecté)
• Plan de rollback (comment annuler en toute sécurité)
• Comment vérifier (une ou deux vérifications)

Mettez une règle pour les corrections urgentes. Si un hotfix doit être appliqué directement au code exporté, programmez la recréation du même changement dans le modèle visuel (ou la refonte du point d'extension) dans un délai fixe, par exemple 1 à 3 jours ouvrés. Cette règle détermine souvent si une exception reste temporaire ou devient une dérive permanente.

Erreurs courantes qui causent des écrasements et de la dérive

La plupart des problèmes d'écrasement commencent comme un raccourci raisonnable : « je vais juste modifier ce fichier ». Avec une plateforme régénératrice comme AppMaster, ce raccourci devient généralement du rework car la prochaine export régénère ces mêmes fichiers.

Les patterns qui créent de la dérive

Le plus courant est de modifier du code généré parce que c'est plus rapide sur le moment. Ça marche jusqu'à la prochaine régénération, où le patch disparaît ou entre en conflit avec la nouvelle sortie.

Un autre problème fréquent est plusieurs personnes ajoutant du code custom sans frontière claire. Si une équipe ajoute un helper « temporaire » dans les dossiers générés et qu'une autre ajoute un helper différent au même endroit, vous ne pouvez plus régénérer fiablement ni revoir les changements proprement.

La dérive arrive aussi quand des releases évitent la régénération parce que cela paraît risqué. Alors le modèle visuel change, mais la production tourne sur un ancien export. Après quelques cycles, personne ne sait vraiment ce que fait l'appli.

Une erreur plus discrète est de ne pas enregistrer quelle version du modèle a produit quel export. Sans un tag ou une note simple, vous ne pouvez pas répondre à des questions basiques comme « ce comportement d'API vient-il du modèle ou d'un patch custom ? »

Un exemple rapide

Un développeur constate l'absence d'une règle de validation et modifie directement un handler Go généré pour bloquer les valeurs vides. Ça passe les tests et ça part en production. Deux semaines plus tard, l'équipe met à jour un Business Process AppMaster et exporte de nouveau. Le handler est régénéré, la validation a disparu, et le bug revient.

Signes précurseurs à surveiller :

• Commits custom dans les répertoires générés
• Pas de règle écrite pour l'emplacement des extensions
• « On ne peut pas régénérer cette release » qui devient la norme
• Releases qui ne notent pas la version du modèle utilisée
• Correctifs existant uniquement dans le code, pas dans le modèle visuel

Contrôles qualité qui détectent la dérive tôt

Considérez chaque régénération comme une petite release. Vous vérifiez non seulement que l'appli tourne, mais que le modèle visuel (par exemple, votre AppMaster Data Designer et Business Process Editor) correspond toujours à ce que votre dépôt déploie.

Commencez par une suite de tests minimale qui reflète le comportement utilisateur réel. Gardez-la petite pour qu'elle s'exécute sur chaque changement, mais assurez-vous qu'elle couvre les flux qui rapportent de l'argent ou génèrent des tickets support. Pour un outil interne ops, cela peut être : se connecter, créer un enregistrement, l'approuver et le voir dans un rapport.

Quelques vérifications ciblées faciles à répéter :

• Smoke tests pour les 3 à 5 flux utilisateurs principaux (web et mobile si vous livrez les deux)
• Contrôles de contrat pour les APIs clés (forme requête/réponse) et les intégrations critiques comme Stripe ou Telegram
• Revue de diff après export focalisée sur les dossiers custom, pas les zones générées
• Un exercice de rollback : confirmer que vous pouvez redéployer la dernière build stable rapidement
• Journalisation de version : version du modèle, date d'export et tag du commit déployé

Les contrôles de contrat détectent les problèmes « ça a l'air ok en UI ». Exemple : un endpoint régénéré existe toujours, mais le type d'un champ est passé d'entier à string, ce qui casse un appel de facturation en aval.

Pour la revue de diff, gardez une règle simple : si un fichier est dans un répertoire généré, ne l'éditez pas à la main. Les réviseurs doivent ignorer le churn bruyant et se concentrer sur ce que vous possédez (modules custom, adaptateurs, wrappers d'intégration).

Rédigez un plan de rollback avant d'en avoir besoin. Si la régénération introduit un changement bloquant, vous devez savoir qui peut approuver le rollback, où se trouve l'artefact stable et quelle version du modèle l'a produit.

Exemple : ajouter une intégration custom sans la perdre lors de la regen

Supposons que votre équipe construit un portail client dans AppMaster mais a besoin d'une intégration de messaging personnalisée non couverte par les modules intégrés (par exemple, un fournisseur SMS niche). Vous exportez le code source pour ajouter le SDK du provider et gérer quelques cas limites.

La règle qui empêche les problèmes plus tard est simple : gardez le modèle visuel comme source de vérité pour les données, endpoints API et le flux core. Placez le code fournisseur custom dans une couche adaptatrice que le code généré appelle, mais qu'il ne possède pas.

Une séparation propre ressemble à ceci :

• Modèle visuel (AppMaster) : champs de base de données, endpoints API, règles d'authent, et le process métier qui décide quand envoyer un message
• Couche adaptatrice (écrite à la main) : client provider, signature des requêtes, retries, et transformation des erreurs provider en un petit ensemble d'erreurs applicatives stables
• Frontière fine : une interface unique comme SendMessage(to, text, metadata) déclenchée par le process métier

Semaine après semaine, la régénération devient ennuyeuse, ce qui est le but. Un lundi, un changement produit ajoute un nouveau type de message et un champ PostgreSQL. Vous mettez à jour le modèle AppMaster et régénérez. Le backend généré change, mais la couche adaptatrice ne change pas. Si l'interface a besoin d'un nouveau paramètre, vous le changez une seule fois, puis mettez à jour le point d'appel unique à la frontière convenue.

Les revues et tests vous aident à ne pas dépendre du savoir tribal. Un minimum utile :

• Une vérification qu'aucun fichier généré n'a été édité directement
• Tests unitaires pour l'adaptateur (chemin heureux, timeout provider, numéro invalide)
• Un test d'intégration qui s'exécute après régénération et confirme l'envoi du message

Rédigez une courte fiche d'intégration pour la personne suivante : ce que fait l'adaptateur, où il vit, comment faire pivoter les credentials, comment lancer les tests et quoi changer lorsque le modèle visuel ajoute de nouveaux champs.

Prochaines étapes : plan de déploiement pratique (avec une note légère sur le choix d'outils)

Commencez petit et mettez-le par écrit. Une politique d'une page suffit si elle répond à deux questions : qu'est-ce qui est autorisé à changer dans le repo, et qu'est-ce qui doit changer dans le modèle visuel. Ajoutez un schéma de frontière simple (même une capture d'écran) montrant quels dossiers sont générés et lesquels sont à vous.

Ensuite, pilotez le workflow sur une vraie fonctionnalité. Choisissez quelque chose de précieux mais contenu, comme ajouter un webhook, un petit écran admin ou une nouvelle étape d'approbation.

Un plan de déploiement pratique :

• Rédiger la politique et le diagramme de frontière, et les stocker à côté du README du repo.
• Choisir une fonctionnalité pilote et l'exécuter de bout en bout : changement de modèle, export, revue, déploiement.
• Planifier un exercice de régénération récurrent (mensuel suffit) où vous régénérez volontairement et confirmez que rien d'important n'est écrasé.
• Ajouter une porte de contrôle simple : pas de merge si le changement du modèle visuel n'est pas référencé (ticket, note ou message de commit).
• Après deux exercices réussis, appliquer les mêmes règles à l'équipe suivante et à l'appli suivante.

Note sur le choix d'outil : si vous utilisez AppMaster, traitez le modèle visuel comme l'endroit par défaut pour les données, les APIs et la logique métier. Utilisez le code exporté pour les besoins de déploiement (votre cloud, vos politiques) ou pour des extensions contrôlées qui vivent dans des zones clairement séparées.

Si vous construisez avec AppMaster sur appmaster.io, une bonne pratique est de vous entraîner sur un petit projet no-code : créez la logique applicative dans les éditeurs visuels, exportez, régénérez et prouvez que vos frontières tiennent avant de monter en charge vers des systèmes plus importants.