MicroProfile pour les microservices (contexte Quarkus)

Emmanuel BRUNO

emmanuel.bruno@univ-tln.fr

Université de Toulon

LIS UMR CNRS 7020

2026-11-07

Objectifs

À la fin de cette leçon, vous serez capable de :

• Comprendre les principaux APIs MicroProfile et leur rôle dans les architectures microservices.
• Créer et lancer un projet Quarkus avec les extensions du TP (MicroProfile Config intégré, Health, Metrics, OpenAPI).
• Externaliser la configuration avec MicroProfile Config (@ConfigProperty) — cœur, mis en œuvre dans le TP.
• Exposer les endpoints de santé (liveness / readiness) et les métriques applicatives — cœur, mis en œuvre dans le TP.
• Documenter l’API avec OpenAPI — cœur, mis en œuvre dans le TP.
• Comprendre le rôle de la tolérance de panne (aperçu — prolongements).
• Comprendre les clients REST typés (aperçu — prolongements).

Comment suivre cette leçon : ce document est le cœur conceptuel de MicroProfile sous Quarkus. Il s’accompagne d’un TP pratique (04_java_MicroProfile_P_microprofile-demo.qmd) ; la sécurité est développée dans la leçon 05 (05_java_Security_L_Introduction.qmd).

Pourquoi MicroProfile ?

MicroProfile est un ensemble de spécifications (SmallRye / Eclipse) qui complète Jakarta EE pour les architectures microservices : configuration externalisée, tolérance de panne, métriques, santé, documentation OpenAPI et sécurité légère.

Quarkus fournit d’excellentes intégrations MicroProfile (SmallRye implementations), optimisées pour le démarrage rapide et la compilation native.

Démarrage rapide (Quarkus + MicroProfile)

1. Créer un projet Quarkus (Maven) :

quarkus create app fr.ebruno.microprofile:microprofile-demo \
  --extension=rest-jackson,smallrye-health,smallrye-metrics,smallrye-openapi

La commande normative figure dans le TP (Étape 1). Les extensions Fault Tolerance et Rest Client ne s’ajoutent que dans les Prolongements (optionnel).

2. Lancer en mode développement :

mvn quarkus:dev
# hot-reload, accessible à http://localhost:8080

Note : adaptez la version Quarkus selon votre projet. Les extensions SmallRye apportent les implémentations MicroProfile.

MicroProfile Config (configuration)

Un même service tourne en dev, test et prod avec des URLs et des secrets différents : comment éviter de recompiler pour chaque environnement ?

MicroProfile Config permet d’injecter des valeurs depuis application.properties, variables d’environnement, ou autres sources.

Exemple : injection de config

import org.eclipse.microprofile.config.inject.ConfigProperty;

@ApplicationScoped
public class GreetingService {
    @ConfigProperty(name = "greeting.message", defaultValue = "Hello")
    String message;

    public String greet(String name) {
        return message + ", " + name;
    }
}

application.properties :

greeting.message=Bonjour

Dans Quarkus, application.properties est la source préférée mais MP Config s’intègre aussi aux variables d’environnement.

MicroProfile Health (liveness / readiness)

L’orchestrateur (Kubernetes) doit savoir si votre pod est vivant et s’il peut recevoir du trafic.

MicroProfile Health expose des endpoints permettant d’évaluer la santé des services.

Health check simple (Quarkus / SmallRye)

import org.eclipse.microprofile.health.HealthCheck;
import org.eclipse.microprofile.health.HealthCheckResponse;
import org.eclipse.microprofile.health.Liveness;

@Liveness
@ApplicationScoped
public class LivenessCheck implements HealthCheck {
    @Override
    public HealthCheckResponse call() {
        return HealthCheckResponse.up("application");
    }
}

Endpoints fournis par Quarkus (SmallRye Health) :

• GET /q/health/live (liveness)
• GET /q/health/ready (readiness)

Exemples avancés : vérifier accès base de données, file d’attente, connexions externes.

MicroProfile Metrics

Comment savoir en production qu’un endpoint ralentit ou est surappelé ?

Expose des métriques applicatives (Prometheus, Micrometer adapter possible).

Prometheus est un système de monitoring open source qui interroge périodiquement (« scrape ») des endpoints HTTP pour collecter des métriques. Un microservice expose donc les siennes sur /q/metrics afin que Prometheus les collecte pour alimenter des tableaux de bord et de l’alerting. Kubernetes utilise ces métriques (autoscaling, alerting) et consomme les health checks pour redémarrer ou retirer du trafic un pod malade.

Exemple : @Counted et @Timed

import org.eclipse.microprofile.metrics.annotation.Counted;
import org.eclipse.microprofile.metrics.annotation.Timed;

@ApplicationScoped
public class OrderService {
    @Counted(name = "orders_created_count")
    @Timed(name = "orders_create_time")
    public void createOrder(String id) {
        // logique
    }
}

Quarkus expose les métriques à :

• GET /q/metrics (raw)
• GET /q/metrics/application (application metrics)

Ces métriques peuvent être récupérées par Prometheus.

MicroProfile Fault Tolerance

Un service en aval est lent ou tombe : comment éviter que tout le système ne tombe avec lui ?

API pour gérer latences, échecs réseau, retries, timeouts, fallback et circuit breakers.

Exemple : @Retry, @Timeout, @Fallback

import org.eclipse.microprofile.faulttolerance.Retry;
import org.eclipse.microprofile.faulttolerance.Timeout;
import org.eclipse.microprofile.faulttolerance.Fallback;

@ApplicationScoped
public class RemoteService {

    @Retry(maxRetries = 3)
    @Timeout(2000)
    @Fallback(fallbackMethod = "fallbackResponse")
    public String callExternal() {
        // appel HTTP externe
    }

    public String fallbackResponse() {
        return "service-unavailable";
    }
}

@CircuitBreaker

import org.eclipse.microprofile.faulttolerance.CircuitBreaker;

@CircuitBreaker(requestVolumeThreshold = 5, failureRatio = 0.5)
public String callExternal() { ... }

Quarkus SmallRye Fault Tolerance implémente ces annotations et expose des métriques de tolérance.

MicroProfile Rest Client

Un service doit appeler un autre service de façon typée, sans parser le JSON à la main.

Permet d’écrire des clients REST typés via une interface Java.

Exemple : interface client

import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import java.util.List;

record Item(String id, String name) {}

@RegisterRestClient(configKey = "inventory-api")
@Path("/inventory")
public interface InventoryClient {
    @GET
    List<Item> listItems();
}

Injection :

@Inject
InventoryClient inventoryClient;

public void check() {
    inventoryClient.listItems();
}

Configuration (application.properties) :

inventory-api/mp-rest/url=http://inventory:8080

Quarkus supporte aussi la version reactive des Rest Clients.

MicroProfile OpenAPI

Comment documenter et consommer une API REST sans maintenir la documentation à la main ?

Génère automatiquement une documentation OpenAPI à partir des ressources JAX-RS et des annotations.

• Extension Quarkus : smallrye-openapi
• URI par défaut : /q/openapi (spec JSON) et /q/swagger-ui (interface)

Exemple minimal :

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

OpenAPI sera exposé automatiquement ; on peut enrichir via @Operation, @APIResponse, etc.

Sécurité (JWT) : la sécurité basée sur les jetons JWT (MicroProfile JWT / SmallRye, annotation @RolesAllowed, injection de JsonWebToken, configuration des permissions) est traitée dans la leçon 05 : 05_java_Security_L_Introduction.qmd.

Observability et Production

• Exposez metrics à Prometheus (/q/metrics)
• Exposez health checks (/q/health)
• Documentez API avec OpenAPI (/q/openapi + /q/swagger-ui)
• Utilisez Fault Tolerance pour circuit breaker & retries

Exemples pratiques (endpoints)

Un petit service demo :

• GET /greet → greeting message (MP Config)
• GET /q/health/ready → readiness
• GET /q/metrics → metrics
• GET /q/openapi → OpenAPI JSON

Débogage et développement

• Mode dev : mvn quarkus:dev (hot reload) ; la Dev UI (http://localhost:8080/q/dev-ui) permet d’inspecter l’état de l’application.
• Pour déboguer la santé ou les métriques, inspectez directement la sortie des endpoints /q/health et /q/metrics (via curl ou le navigateur).

Bonnes pratiques

• Centralisez la configuration via MP Config
• Protégez les endpoints critiques (voir la leçon 05 pour la sécurité)
• Exposez métriques et health checks pour l’orchestrateur (Kubernetes)
• Testez Fault Tolerance via tests d’intégration (chaos)
• Documentez l’API avec OpenAPI et gardez-le synchronisé

Ressources et liens

• MicroProfile official : https://microprofile.io
• SmallRye (implémentations) : https://smallrye.io
• Quarkus guides : https://quarkus.io/guides
• Quarkus MicroProfile (OpenAPI, Health, Metrics, Fault Tolerance) guides