Code généré

12 min

Vue d'ensemble

Dans un projet OAV, tous les fichiers n'ont pas le même statut.

Trois natures de fichiers coexistent :

Nature	Produite par	Modifiable	Sort de la génération
Code généré	L'outillage.	Non	Réécrit intégralement.
Fichier squelette	L'outillage, une seule fois.	Oui.	Préservé.
Code de projet	Le développeur.	Oui	Ignoré.

Identifier un fichier généré

Un fichier généré porte un en-tête explicite :

// Code generated by gen. DO NOT EDIT.

[warn] Tout fichier portant cet en-tête est écrasé à la prochaine génération, sans avertissement ni sauvegarde.

Les répertoires concernés sont :

Répertoire	Produit par	Contenu
entities/	entities:gen	Code d'accès aux entités et énumérations.
migrations/	entities:gen	Migrations SQL du schéma du modèle de données.
views/	views:gen	Code client et serveur des vues, hors fichiers squelettes.

Les fichiers squelettes

La génération des vues produit également des fichiers destinés à être complétés. Ils ne portent pas l'en-tête de code généré et ne sont pas écrasés lors des générations suivantes.

Fichier	À compléter avec
views/<directory>/client/<Composant>.jsx	Le rendu de la vue et ses interactions.
views/<directory>/client/<Composant>.inte.test.jsx	Les tests d'intégration de la vue.
views/<directory>/server/graphql/resolver/<resolver>.mjs	La logique de résolution de la query ou de la mutation.
views/<directory>/server/graphql/resolver/<resolver>.test.js	Les tests du resolver.

[info] Un resolver généré est fonctionnel mais vide : il retourne une structure conforme au type déclaré, sans donnée. C'est au projet d'en écrire l'implémentation.

Le cycle de génération

Toute évolution du modèle ou du parcours suit le même enchaînement : modifier la configuration, générer, vérifier, puis migrer si nécessaire.

flowchart LR
    A[Configuration Change] --> B[Generation]
    B --> C[Verification of Generated Files]
    C --> D{Migration Generated?}
    D -->|Yes| E[Apply Migration]
    D -->|No| F[Implementation]
    E --> F

Modèle de données

Mise à jour du fichier de configuration des entités ;

exécution de npm run entities:gen ;

vérification des fichiers générés et de la présence éventuelle d'une nouvelle migration ;

exécution de npm run migrate:dev si une migration a été produite.

Parcours

Mise à jour de la configuration des vues ;

exécution de npm run views:gen ;

mise à jour des fichiers de transitions concernés ;

implémentation des composants et des resolvers de la vue.

Options de génération

La commande views generate accepte plusieurs options qui influent sur les fichiers produits :

Option	Type	Défaut	Effet
--clean-unused-files	booléen	false	Supprime les fichiers générés devenus inutiles.
--ext-file-backend	chaîne	mjs	Extension des fichiers serveur générés.
--gen-test-files	booléen	true	Génère les fichiers de test des vues.
--tree-structure	chaîne	standard	Arborescence produite pour les vues rangées en sous-répertoires.
--gen-secure-resolvers	booléen	false	Restreint l'appel des resolvers à la vue courante du parcours.

La commande entities generate accepte l'option --oas-config, qui indique que la configuration des entités est fournie au format OpenAPI.

Cas particulier des migrations

Les migrations sont un code généré d'une nature particulière : une fois exécutée, une migration décrit un état déjà atteint par la base de données.

[warn] Un fichier de migration déjà exécuté ne doit jamais être supprimé, renommé ni modifié. L'outil de migration vérifie l'existence des fichiers précédemment exécutés : la commande de migration échoue si l'un d'eux est manquant.

Toute correction passe donc par une nouvelle migration, obtenue en corrigeant la configuration des entités puis en relançant la génération.

Versionnement

Le code généré est versionné avec le projet. Cette pratique a deux vertus :

le diff d'une génération rend immédiatement visible l'effet d'une modification de configuration, et constitue le meilleur moyen de la vérifier ;

le projet reste constructible sans avoir à rejouer l'outillage.

Étendre plutôt que modifier

Lorsqu'un comportement généré ne convient pas, la réponse n'est jamais de modifier le fichier produit :

Besoin	Réponse
Ajouter une propriété à une entité.	Modifier la configuration des entités, puis régénérer.
Modifier la structure d'une vue.	Modifier son fichier de configuration YAML, puis régénérer.
Ajouter de la logique à une vue.	Implémenter le composant et les resolvers, qui sont des fichiers squelettes.
Enrichir l'objet Process.	Modifier server/process/extend-process.mjs et le type GraphQL associé.
Ajouter une route ou un traitement serveur.	Étendre la configuration passée à start dans server/index.mjs.

Résumé

Un fichier portant l'en-tête // Code generated by gen. DO NOT EDIT. est réécrit à chaque génération ;

les composants, les resolvers et leurs tests sont des squelettes : ils sont préservés et destinés à être complétés ;

toute évolution part de la configuration, jamais du code produit ;

une migration déjà exécutée est immuable : on la corrige par une nouvelle migration.