3.12 Infos-Spring

Les fonctionnalités CLOUD et plus largement de Spring sont utilisées dans les projets BACK.

3.12.1 - Liste des principales dépendances Spring et leurs usages

  • Ces dépendances Spring sont utilisés sont dans les services de gestion/administration

    • spring-boot-admin-starter-server est utilisé dans service-admin pour fournir une interface d’administration de l’ensemble du SI. A travers ces écrans, les instances de micro-services sont visibles, leurs métriques sont consultables et il est possible de modifier certains paramètres (comme les niveaux de log).
    • spring-cloud-starter-gateway est utilisé dans le projet services-cloud\service-gateway pour créer un point d’entrée unique à tous les micro-services. Ce portail (traduction possible de ‘gateway’) contient, dans sa configuration, une route pour chaque micro-service. Cette configuration fait référence au nom du micro-service (spring.application.name) et utilise un répartiteur de charge simpliste ainsi que l’annuaire. C’est le seul et unique point d’entrée du SI. Aucun micro-service ne doit être appelé depuis l’extérieur du SI sans passer par la Gateway.
    • spring-cloud-starter-netflix-eureka-server est utilisé dans le projet services-cloud\service-registry pour créer un annuraire des micro-services. Chaque applicatif, à son démarrage, s’enregistre auprès de l’annuaire en fournissant son nom (spring.application.name configuré dans le fichier application-specifique.properties), son IP et son port. Ainsi l’annuaire connait tous les micro-services démarrés et fournit, à tous les micro-services et à la gateway, une URL à appeler pour un nom d’application donné.

  • Ces dépendances Spring sont utilisés dans tous les projets applicatifs de micro-service

    • spring-boot-starter-web permet la création des APIs avec l’annotation @Controller
    • spring-cloud-starter-sleuth est une librairie permettant d’ajouter, dans chaque ligne de log, un identifiant unique et de faire passer cet identifiant d’un micro-service à un autre.
    • spring-cloud-starter-openfeign est une librairie permettant de créer, dynamiquement, un client REST pour les APIs simples (hors upload de document par exemple). C’est une alternative aux clients développés manuellement. (le code actuel comprend un client manuel ET un client OpenFeign)
    • spring-cloud-starter-netflix-eureka-client est la dépendance par laquelle tout micro-service et la gateway appelle l’annuraire Eureka pour s’enregistrer ou obtenir l’URL d’un autre service (cf. spring-cloud-starter-netflix-eureka-server).

  • Ces dépendances Spring permettent la réalisation de test

    • spring-data-mongodb fournit un client MongoDB
    • spring-boot-starter-test fournit les classes de Spring pour s’intégrer aux frameworks de test (démarrage/redémarrage/arrêt de contexte Spring). /!\ Cette dépendance est en scope TEST et n’est donc pas transitive. Il est donc normal de la retrouver dans à peu près tous les projets.

3.12.2 - Liste des annotations Spring (et autres) utilisées dans les projets Back

Ce chapitre ne liste pas les annotations documentaires comme celles de la Javadoc.

Les règles de nommage associées aux composants décrits ci-dessous sont au chapitre 3.4.2

  • Les annotations de base de Spring (IOC&DI alias inversion de contrôle et injection de dépendance)

    • @Component et @Service permettent de déclarer, à Spring, que cette classe est un composant que Spring doit considérer comme un composant applicatif à instancier une (et une seule) fois, à y injecter d’autres composant et à injecter dans d’autres composant. Le @Component est à utiliser pour les composants qui ne sont pas des DAO, des services métiers ou des contrôleurs REST. @Service est à injecter dans tous les services métiers (dont le nom est suffixé par Service).
    • @Autowired est l’annotation demandant à Spring d’injecter automatiquement un composant applicatif dans un autre (un DAO dans un service ou un service dans un contrôleur REST ou un service dans un test, …)
    • @PostConstruct est une annotation particulière permettant de faire s’exécuter une méthode d’un composant applicatif Spring juste après que le dit composant ait été instancié et que les dépendances aient été injectées.

  • Les annotation de configuration de Spring :

    • @Configuration est une annotation à placer sur toute classe définissant des éléments de configuration pour Spring (par annotation comme @PropertySource, par méthode avec @Bean). Ces classes-là doivent être suffixées par Config.
    • @Value("${la.clef:ValEurParDEFAUT}") est une annotation à placer sur un attribut d’un composant Spring. Elle permet d’injecter automatiquement une valeur configurée dans un fichier PROPERTIES.
    • @PropertySource(“classpath:unfichier.properties”) est une annotation à placer sur une classe de configuration ou d’application listant/ajoutant un fichier de configuration à charger.
    • @Bean est une annotation placée sur une méthode de classe de configuration. Cette méthode retourne un (ou une liste de) composant(s) applicatif(s).

  • Les annotations de base des contrôleur REST de Spring :

    • @DeleteMapping, @GetMapping, @PostMapping et @PutMapping sont des annotations déclarant une méthode publique d’une classe suffixée par API que Spring devra exposer sous forme d’une API REST.
    • @PathVariable, @RequestParam, @RequestPart, @ResponseBody et @RequestBody sont des annotations décrivant une méthode exposée sous forme d’API REST : exemples Baeldung et documentation officielle.
    • @RestController est une annotation placée sur un contrôleur REST (cf. §3.21.2 pour les règles de nommage).
    • @SecurityRequirements({ @SecurityRequirement(name = “bearer-jwt”) }) : Cette chaîne de caractères est utilisée pour la documentation des APIs et notamment déclarer leur mode de protection.

  • Les annotations spécifiques à un besoin :

    • @FeignClient est une annotation à placer sur une interface décrivant une API REST. Cette annotation permet que Spring, sur demande, crée un client appelant cette API.
    • @ControllerAdvice est une annotation pour les classes traitant les exceptions et les transformant en une réponse d’API REST.
    • @LocalServerPort permet, depuis une classe de test par exemple, de récupérer le port sur lequel répondent les APIs REST du contexte Spring démarré (les tests s’exécutent toujours avec un port dynamique).
    • @Scheduled permet de déclencher à intervalle de temps régulier une méthode :

  • Les annotations spécifiques à SpringBoot ou à une librairie de SpringBoot

    • @SpringBootApplication est l’annotation de base de SpringBoot permettant de déclarer une classe de démarrage.
    • @EnableAutoConfiguration est une annotation permettant d’activer/désactiver des modules SpringBoot qui démarre normalement automatiquement du moment que le JAR est présent dans le classpath (dans notre cas, elle est utilisée pour désactiver le démarrage automatique de MongoDB).
    • @EnableFeignClients se place dans une classe d’application ou de configuration et permet de déclarer un ou plusieurs clients Feign (classes annotées avec @FeignClient).
    • @EnableWebSecurity et @EnableGlobalMethodSecurity s’associent pour créer une classe configurant la sécurité des APIs REST exposées.
    • @EnableScheduling permet d’autoriser l’usage de l’annotation @Scheduled.
    • @EnableAdminServer et @EnableEurekaServer permettent respectivement d’activer une application d’administration et un annuaire Eureka (cf. §3.12.2).

  • Les annotations de Jackson (framework réalisant la transformation JSON<->Java).

    • @JsonAnySetter permet de déclarer une méthode à utiliser si aucun setter ne correspond dans la classe (utilisé quand une partie des attributs sont dynamiques et stockés dans une Map par exemple).
    • @JsonCreator peut annoter un constructeur et sera utilisée pour désérialiser un JSON (transformer le texte JSON en classe Java). Ceci est utile pour les classes immutables ou quand quelques lignes de logique sont nécessaires.
    • @JsonIgnore permet de demander à Jackson de ne pas prendre en compte une méthode pour créer le JSON à partir d’une classe.
    • @JsonIgnoreProperties(ignoreUnknown = true), placée sur une classe, permet que Jackson ne lance pas d’erreur si un message JSON contient des attributs n’existant pas dans la classe Java.
    • @JsonProperty(“clef”) permet de personnaliser le nom d’un attribut JSON (par défaut, l’attribut JSON porte le nom de l’attribut Java).

  • Les annotations de JUnit

    • @SpringBootTest est une annotation de Spring permettant de configurer un test démarrant un contexte Spring.
    • @Test est une annotation JUnit à placer sur chaque méthode de test JUnit. Cette méthode doit être public, ne pas prendre d’argument et renvoyer void.
    • @AfterAll, @BeforeAll et @BeforeEach sont des annotations de JUnit permettant de faire s’exécuter une méthode avant/après chaque/tous test(s).
    • @ExtendWith(MockitoExtension.class) permet de dire à Spring que le test doit utiliser Mockito et traiter les annotations @InjectMocks et @Mock.
    • @TestInstance(Lifecycle.PER_CLASS) est une annotation JUnit permettant de lui préciser un cycle de vie particulier de la classe de test. En effet, par défaut, une nouvelle instance de la classe de test est créée pour chaque appel à une méthode de test. Mais, comme créer et injecter des bouchons est coûteux en temps, il est préférable de n’avoir qu’une unique instance de classe de test, de créer et injecter les bouchons une seule fois mais de réinitialiser les bouchons entre chaque test.
    • @Mock permet de générer un bouchon sur un membre de la classe dont le type est une classe (attention, interdit sur les interfaces).
    • @InjectMocks permet de dire à Spring d’injecter tous les bouchons générés dans la classe ainsi annotée.
    • @TestMethodOrder(MethodOrderer.MethodName.class) permet de dire à JUnit d’exécuter les tests dans un ordre précis (par défaut, l’ordre peut varier aléatoirement).
    • @TestPropertySource est une annotation permettant de préciser un ou plusieurs fichiers de configuration supplémentaires à utiliser pour cette classe de test particulière.