Développement d'applications avec Quarkus

Création d’un projet avec la ligne de commande, code.quarkus.io ou un IDE

Pour créer un projet, on peut utiliser la CLI (Command-Line Interface - interface ligne de commande) de Quarkus, Maven, le site https://code.quarkus.io ou un IDE (Integrated Development Environment ou environnement de développement intégré).

La manière la plus simple de créer un projet est d’utiliser le site https://code.quarkus.io. Il contient un formulaire pour spécifier les coordonnées du projet Maven ou Gradle à créer, ainsi qu’une barre de recherche afin d’ajouter les extensions que vous voulez utiliser. Ce site permet d’ajouter les extensions présentes sur la plateforme Quarkus ; la plateforme est un ensemble d’extensions testées les unes avec les autres et qui garantissent qu’elles peuvent être utilisées conjointement sans conflit.

Une fois la sélection d’extensions réalisée, vous pouvez télécharger un ZIP du projet ou directement faire un push sur un repository GitHub.

Pour créer un projet en ligne de commande, on peut utiliser la CLI Quarkus ou Maven.

La CLI Quarkus est installable de plusieurs manières en fonction de l’OS : SDKMAN (Linux et macOS), Homebrew (Linux et macOS) ou Chocolatey (Windows).

Pour installer la CLI via SDKMAN!, utilisez la commande suivante :

sdk install...

Anatomie d’un projet Quarkus

Voici la structure du projet Quarkus généré :

Le projet généré contient les éléments suivants :

Si on regarde plus en détail le pom.xml, celui-ci va procéder comme suit :

<dependencyManagement> 
  <dependencies> 
    <dependency> 
      <groupId>${quarkus.platform.group-id}</groupId> 
      <artifactId>${quarkus.platform.artifact-id}</artifactId> 
      <version>${quarkus.platform.version}</version> ...

Bases : configuration, logs, injection de dépendances et tests

@Path("/hello") 
public class GreetingResource { 
 
    @GET 
    @Produces(MediaType.TEXT_PLAIN) 
    public String hello() { 
        return "Hello RESTEasy"; 
    } 
} 

greeting.message=Hello World 

@Path("/hello") 
public class GreetingResource { 
    @ConfigProperty(name="greeting.message") String message; 
 
    @GET 
    @Produces(MediaType.TEXT_PLAIN) 
    public String hello() { 
        return message; 
    } 
} 

Developer Joy : dev mode, dev UI, continuous testing, dev services

1. Le dev mode

Le dev mode est un mode spécial de lancement d’une application Quarkus sur le poste local d’un développeur en ligne de commande. Dans ce mode, l’application va utiliser le profil de configuration %dev et de nombreux outils d’aide au développement seront disponibles.

On peut lancer l’application en mode développeur (dev) avec la CLI, le plugin Maven, ou le plugin Gradle.

Pour lancer l’application avec la CLI, utilisez la ligne de commande suivante :

quarkus dev 

Pour lancer l’application avec le plugin Maven, utilisez la ligne de commande suivante :

mvn quarkus:dev 

Pour lancer l’application avec le plugin Gradle, utilisez la ligne de commande suivante :

gradle --console=plain quarkusDev 

Le résultat est le suivant :

Dans les logs, on voit la bannière Quarkus, trois logs de démarrage, puis l’aide de la dev console

Vous voici maintenant dans la dev console. Celle-ci est interactive, les principales commandes sont affichées en bas : [r] pour activer les tests en continu, [:] pour un terminal interactif permettant de passer des commandes à la console, [h] pour l’aide, [s] pour forcer le redémarrage de l’application et [q] pour la quitter.

Redémarrer l’application n’est normalement pas nécessaire car Quarkus va le faire automatiquement à chaque modification de code, fichier de configuration ou ajout de dépendance dans le fichier pom.xml. Et ce redémarrage...

Webservice REST avec JAX-RS

1. Les extensions HTTP

Quarkus permet de développer des endpoints (points de terminaison) HTTP via les frameworks suivants :

• RESTEasy : pour les services web REST selon la spécification JAX-RS (Jakarta RESTful Web Services).

• Undertow : pour le développement de Servlet.

• Vert.x Reactive routes : pour des endpoints légers et réactifs directement basés sur Vert.x.

• Spring Web : pour les services web REST compatibles avec les annotations Spring Web. Quarkus n’utilise pas de librairie Spring lors du fonctionnement d’une application. La couche de compatibilité Spring va lire les annotations spécifiques Spring, puis générer le code Quarkus correspondant. Pour Spring Web, elle va générer du code RESTEasy.

Quelle que soit l’extension HTTP utilisée, celle-ci s’intégrera avec le framework Eclipse Vert.x qui est au cœur de la stack (pile en français) HTTP de Quarkus.

Vert.x utilise le framework Netty pour le transport HTTP, les entrées-sorties sur le réseau seront donc faites via Netty. Netty implémente des entrées-sorties non bloquantes ; c’est grâce à Vert.x et Netty que le cœur de Quarkus est réactif. Ceci sera expliqué plus en détail dans le chapitre Développement d’applications réactives.

Documentation d’API avec OpenAPI

OpenAPI est une spécification qui vise à standardiser la description des API pour tous les langages de programmation. Elle permet la découverte du fonctionnement d’une API sans nécessiter l’accès au code source ou l’introspection du réseau.

Eclipse Microprofile OpenAPI fournit un ensemble d’annotations permettant de documenter une API de manière compatible avec la spécification OpenAPI. 

SmallRye OpenAPI est l’extension qui permet le support d’Eclipse Microprofile OpenAPI dans Quarkus ; vous pouvez l’ajouter à votre application via :

quarkus extension add quarkus-smallrye-openapi 

mvn quarkus:add-extension -Dextensions="quarkus-smallrye-openapi" 

Ceci va ajouter la dépendance Maven suivante :

<dependency> 
    <groupId>io.quarkus</groupId> 
    <artifactId>quarkus-smallrye-openapi</artifactId> 
</dependency> 

Dès l’ajout de cette dépendance, une documentation par défaut de l’API est disponible à l’URL http://localhost:8080/q/openapi. Cette URL est configurable via la propriété quarkus.smallrye-openapi.path.

Pour personnaliser cette documentation par défaut, vous pouvez utiliser les annotations suivantes :...

Appel d’un autre service web avec le client REST

Dans une architecture de type micro-service, il est fréquent qu’un service ait besoin d’en appeler un autre.

Par exemple, un service produit pourrait avoir besoin d’appeler un service prix pour récupérer le prix d’un produit. Si ce service prix est un service accessible via HTTP, il est possible d’utiliser l’extension REST Client qui fournit un client HTTP obéissant aux principes REST.

Quarkus propose deux extensions REST Client : REST Client Classic et REST Client Reactive. Le client REST réactif est plus performant que le client REST classique et est compatible avec un développement impératif. De plus, il détecte et gère automatiquement les entrées-sorties bloquantes. Nous n’allons pour l’instant utiliser aucune fonctionnalité propre au développement réactif qui sera vu dans le chapitre Développement d’applications réactives. L’extension REST Client reactive est donc conseillée même pour le développement impératif et l’utilisation d’entrées-sorties bloquante.

Des extensions REST Client spécifiques supportant la sérialisation JSON via Jackson ou JSON-B existent. Il est plus simple de les utiliser que d’ajouter séparément l’extension REST Client et une extension JSON. La librairie Jackson étant plus connue que JSON-B, nous allons l’utiliser dans les exemples de ce chapitre.

Pour ajouter l’extension REST Client Reactive avec Jackson a un projet existant, vous pouvez utiliser la ligne de commande de la CLI Quarkus suivante :

quarkus extension add rest-client-reactive-jackson 

ou la ligne de commande Maven suivante :

mvn quarkus:add-extension \ 
    -Dextension=rest-client-reactive-jackson 

Ces commandes ajouteront la dépendance Maven suivante au fichier pom.xml :

<dependency> 
    <groupId>io.quarkus</groupId> 
    <artifactId>quarkus-rest-client-reactive-jackson</artifactId> ...

Fonctionnalités HTTP

quarkus extension add webjars-locator 

mvn quarkus:add-extension \ 
    -Dextension=webjars-locator 

<dependency> 
    <groupId>io.quarkus</groupId> 
    <artifactId>quarkus-webjars-local</artifactId> 
</dependency> 

<dependency> 
    <groupId>org.webjars</groupId> 
    <artifactId>jquery</artifactId> 
    <version>3.1.1</version> 
</dependency> 

<script src="/webjars/jquery/jquery.min.js"> 

Sécurité : authentification et habilitation

Quarkus supporte un grand nombre de méthodes d’authentification différentes : HTTP Basic, Bearer Token, mTLS… ainsi qu’un grand nombre de fournisseurs d’authentification différents : properties file, JWT, OIDC, LDAP, BDD…

Pour simplifier les exemples de ce livre, nous utiliserons une authentification de type HTTP Basic avec des authentifications (utilisateur et mot de passe) incluses dans le fichier application.properties. Celle-ci est fournie par l’extension Elytron Security Properties File.

Dans la vie réelle, nous utiliserions plutôt une authentification de type OAuth2 ou OIDC. Une fois configurées, ces extensions permettent de gérer les habilitations de la même manière que l’extension Elytron Security Properties File.

Pour ajouter l’extension Elytron Security Properties File à un projet existant, vous pouvez utiliser la ligne de commande de la CLI Quarkus suivante :

quarkus extension add elytron-security-properties-file 

ou la ligne de commande Maven suivante :

mvn quarkus:add-extension \ 
    -Dextension=elytron-security-properties-file 

Ces commandes ajouteront la dépendance Maven suivante au fichier pom.xml :

<dependency> 
    <groupId>io.quarkus</groupId> 
    <artifactId>quarkus-elytron-security-properties-file</artifactId> 
</dependency> 

quarkus.security.users.embedded.enabled=true 
quarkus.security.users.embedded.plain-text=true 
quarkus.security.users.embedded.users.jdoe=p4ssw0rd 
quarkus.security.users.embedded.users.admin=n0Adm1n 
quarkus.security.users.embedded.roles.jdoe=user 
quarkus.security.users.embedded.roles.admin=user,admin 

Applications ligne de commande

Jusqu’ici, nous avons uniquement vu le développement d’applications de type service web qui se démarrent mais ne se finissent jamais.

Il est aussi possible avec Quarkus de créer des applications de type ligne de commande qui se démarrent et se finissent.

Pour créer une application ligne de commande, aucune extension n’est nécessaire. 

Vous pouvez créer une application ligne de commande via la commande de la CLI Quarkus suivante :

quarkus create app hello-command --no-code 

ou via la commande Maven suivante :

mvn io.quarkus.platform:quarkus-maven-plugin:2.16.1.Final:create \ 
    -DnoCode 

L’implémentation d’une application ligne de commande se fait via une classe qui implémente QuarkusApplication et est annotée par @QuarkusMain.

Voici un simple Hello World :

@QuarkusMain ...