3.21 Règles-conception

3.21.1 - Conception

3.21.1.1 - Les projets et leur catégorisation

Le projet socle se compose de multiples projets (notion de micro-service) mais ces projets se divisent en plusieurs catégories

  • les projets fonctionnels apportant des fonctionnalités et exposant des APIs sécurisées comme
    • socle-dbdocument traitant du stockage des documents générés et des pièces jointes ;
    • socle-dbconfiguration stockant les configurations internes et publiques des démarches ;
    • socle-dbbrouillon stockant les brouillons de télé-dossier ;
    • socle-referentiel exposant des APIs permettant l’autocomplétion à partir de données indéxées et obtenues depuis des référentiels externes ;
    • socle-referentielexterne exposant des APIs permettant l’autocomplétion à partir de directement obtenues (à chaque requête entrante) depuis des référentiels externes ;
    • socle-soumission exposant l’API de création d’un tx²élé-dossier (validation, génération de documents…) ;
    • socle-securite exposant les APIs de gestion de l’authentification des usagers.
  • les services standards permettant le bon fonctionnement, l’accès, l’administration ou le suivi des micro-services fonctionnels comme
    • service-nosql proposant une base de données MongoDB utilisable sur un environnement de développement ;
    • service-registry démarrant un annuaire des micro-services ;
    • service-gateway démarrant un portail exposant les APIs des micro-services à l’extérieur du SI ;
    • service-admin permettant de suivre et configurer les micro-services démarrés.
  • les projets techniques portant des fonctionnalités communes à tous les autres :
    • socle-commun fournit les éléments de base de
      • la sécurité des APIs REST ;
      • la gestion des tokens JWT ;
      • la transformation des exceptions en message JSON ;
      • la base des clients REST ;
      • les éléments de configuration des applications SpringBoot (documentation, REST, sécurité, …) ;
      • les fichiers de configuration commun à tous les micro-service ;
      • des classes utilitaires ;
    • socle-communtest fournit la classe de base pour tous les tests automatisés avec le chargement des fichiers de configurations communs à tous ainsi qu’une classe utilitaire pour traiter les tokens JWT.
    • socle-commundb fournit
      • une classe abstraite permettant de démarrer un processus MongoDB ;
      • une classe abstraite d’interrogation d’une base MongoDB ;
      • une classe de base pour les exceptions dans les appels à MongoDB ;
      • une classe utilitaire pour initialiser MongoDB avec un jeu de données basé sur les fichiers de bouchon des projets FRONT Angular.

3.21.1.2 - Configuration

Les paramètres de chaque micro-service sont présents dans des fichier .properties. Ce choix a été fait car les fichiers YML ont un format est plus subtile, basé sur les indentations. Ceci en fait des fichiers plus sujet aux erreurs. La règle veut que chaque fichier de configuration ait un objectif et un seul. Pour conserver un équilibre cohérence/cohésion, chaque fichier de configuration est lié à une fonctionnalité majeure (les logs par exemple) ou à une librairie (le lien avec l’annuaire/registry).

Concernant la configuration Maven :

  • toutes les versions de dépendances sont paramétrées dans le pom.xml du SOCLE PARENT et exclusivement là-bas
  • beaucoup de dépendances sont paramétrées directement dans les projets socle-commun*. Ceci permet que les mécaniques de tous les micro-services soient homogènes.
  • toute dépendance d’un projet à un autre doit utiliser la version ${project.version}
  • /!\ Certains micro-services dépendent d’un autre (socle-soumission dépendant de socle-dbdocument par exemple). Normalement, la soumission doit se faire avec le client. Mais Eclipse gère mal la notion de classifier. La dépendance est donc doublée avec un scope test pour permettre au code de fonctionner correctement dans Eclipse.

3.21.1.3 - Les clients d’API

TODO Chaque projet fonctionnel expose des APIs. Pour chacune d’entre elles, doit exister une méthode dans une classe Client les DTO en fonction des besoins de appelant pas de DTO JAVA exhaustif

3.21.2 - Règles de nommage

Les annotations à utiliser sont décrites dans le chapitre 3.0.2

  • les services métiers sont les composants applicatifs contenant de l’intelligence (algorithmie)
    • à suffixer par Service pour l’interface et ServiceImpl pour l’implémentation
    • dans un package service
    • sans aucun constructeur (c’est un composant Spring utilisant @Autowired sur ses membres pour l’injection de dépendances)
  • les API sont des interfaces contenant toute la déclaration d’une API (méthodes publiques avec les annotations @XxxMapping)
    • à suffixer par API
    • dans un pachage apiclient.api
  • les contrôleurs REST sont les composants applicatifs exposant les services via une API REST
    • à suffixer par Controlleur
    • dans un package controlleur
    • sans aucun constructeur (c’est un composant Spring utilisant @Autowired sur ses membres pour l’injection de dépendances)
    • implémentant une API (sauf cas particulier comme l’upload de document)
  • les objets de transport (DTO) sont les classes contenant des données mais qui ne sont pas des Objets Métiers (aucune intelligence) ni des Rntités (des objets sauvegardés en base)
    • à suffixer par Dto
    • dans un package dto
    • avec un constructeur sans paramètre systématiquement
  • les énumérations ne sont pas des DTO mais décrivent eux aussi des données. Donc elles sont au plus proche des DTO (dans le même package)
    • à suffixer par Enum
    • dans un package dto
  • les applications sont les classes permettant de démarrer une application SpringBoot
    • à suffixer par Application
    • dans un package application
    • avec un constructeur mais avec une méthode main
  • les configuration SpringBoot sont des composants applicatifs permettant d’activer, désactiver, paramétrer des comportements/fonctionnalités de SpringBoot
    • à suffixer par Config
    • dans le package application (si un seul) ou dans le package config
    • avec un constructeur mais avec une méthode main
  • les clients d’API (pour les APIs du socle ou les APIs externes) sont des composants applicatifs
    • à suffixer par Client
    • dans le package client
    • avec un constructeur mais avec une méthode main
  • les classes utilitaires ne sont pas des composants applicatif. Donc aucune injection n’est possible. Ces classes exposent des méthodes statiques uniquement.
    • à suffixer par Utils
    • dans le package au plus proche s’il n’en existe qu’une seule dans le projet sinon dans un package utils
    • dans le package au plus proche s’il n’en existe qu’une seule dans le projet sinon dans un package utils
    • avec un constructeur privé uniquement
    • n’exposant que des méthodes statiques
  • les tests automatisés
    • à suffixer par Test
    • dans le répertoire src/test/java des projets exclusivement (sauf pour les classes de base des tests présentes dans le projet socle-communtest
    • pour plus de détails, se référer au chapitre dédié
  • les composants de génération de données de test suive le pattern ObjectMother décrit par Martin Fowler
    • à suffixer par ObjectMother
    • dans le répertoire src/test/java au plus près des tests automatisés
  • tout autre type de composant doit être soigneusement décrit