Arcadia Genesis Demo

API backend Spring Boot (Maven) avec qualite integree : Spotless, Checkstyle, Error Prone, NullAway et JaCoCo.

Architecture multi-module

Le projet est organise en 5 modules Maven sous src/ :

src/
  common/         -> backendapi-common
  domain/         -> backendapi-domain
  infrastructure/ -> backendapi-infrastructure
  application/    -> backendapi-application-core
  api/
    v1/           -> backendapi-api-v1

Package racine : com.ldc.arcadiagenesis.backendapi

Separation des responsabilites

• application-core : logique applicative reutilisable, sans dependance Spring.
• infrastructure : adaptateurs techniques en Java pur (pas d'annotations Spring).
• api/v1 : bootstrap Spring Boot (controllers, securite, wiring des beans, events Spring).

Spring est confine au module api/v1. Le wiring des beans infra/core est centralise dans :

• src/api/v1/src/main/java/com/ldc/arcadiagenesis/backendapi/application/apiv1/config/InfrastructureConfiguration.java
• src/api/v1/src/main/java/com/ldc/arcadiagenesis/backendapi/application/apiv1/config/ApplicationCoreConfiguration.java

Dependances entre modules

backendapi-api-v1           -> backendapi-application-core, backendapi-infrastructure,
                               backendapi-domain, backendapi-common
backendapi-application-core -> backendapi-domain, backendapi-common
backendapi-infrastructure   -> backendapi-domain, backendapi-common
backendapi-domain           -> backendapi-common

Versionnement de l'API

Le versionnement se fait par module bootstrap sous src/api/.

• v1 actuel : src/api/v1
• futur v2 : src/api/v2 (a creer)

Chaque version peut exposer ses routes/configs propres, tout en reutilisant application-core et infrastructure.

Prerequis

• Java 25
• Maven Wrapper (./mvnw)

Commandes principales

Build rapide

./mvnw clean compile

Tests

./mvnw test

Verification complete (CI locale)

Inclut : compile (Error Prone + NullAway), tests, Spotless check, Checkstyle, JaCoCo.

./mvnw clean verify

Qualite du code

Spotless

Verifier :

./mvnw spotless:check

Appliquer :

./mvnw spotless:apply

Checkstyle (Google style)

./mvnw checkstyle:check

Configuration : checkstyle/checkstyle.xml

Error Prone + NullAway

Executes pendant compile :

./mvnw compile

Couverture (JaCoCo)

La phase verify genere les rapports et impose un seuil minimum de couverture de 80%.

Rapports du module api/v1 :

• HTML : src/api/v1/target/site/jacoco/index.html
• XML : src/api/v1/target/site/jacoco/jacoco.xml

Lancer l'application v1

Le module api/v1 depend des autres modules du mono-repo.

Il faut donc d'abord installer les artefacts locaux depuis la racine du projet :

./mvnw clean install -DskipTests

Puis lancer le module v1 :

./mvnw -pl src/api/v1 spring-boot:run

Pourquoi :

• spring-boot:run est execute uniquement sur le module src/api/v1
• ses dependances inter-modules (backendapi-common, backendapi-domain, backendapi-infrastructure, backendapi-application-core) doivent donc deja exister dans le depot Maven local

OpenAPI / Swagger

La documentation OpenAPI de l'API v1 est exposee par springdoc.

Configuration actuelle :

• context path applicatif : /api/v1
• endpoint OpenAPI JSON : /api-docs
• interface Swagger UI : /swagger-ui/index.html

Une fois l'application lancee, tu peux acceder a :

• Swagger UI : http://localhost:8080/api/v1/swagger-ui/index.html
• OpenAPI JSON : http://localhost:8080/api/v1/api-docs

Remarque :

• le prefixe /api/v1 vient de la propriete server.servlet.context-path
• les chemins /api-docs et /swagger-ui proviennent de la configuration springdoc dans src/api/v1/src/main/resources/application.properties

Docker

Un Dockerfile unique permet de builder une version d'API donnee et de definir le port directement au build.

Arguments supportes :

• API_VERSION : version du module a builder sous src/api/ (exemple : v1, futur v2)
• APP_PORT : port HTTP expose par le conteneur

Build de l'image

Exemple pour v1 sur le port 8080 :

docker build \
  --build-arg API_VERSION=v1 \
  --build-arg APP_PORT=8080 \
  -t arcadia-api:v1 .

Exemple pour une future v2 sur le port 8081 :

docker build \
  --build-arg API_VERSION=v2 \
  --build-arg APP_PORT=8081 \
  -t arcadia-api:v2 .

Lancer le conteneur

docker run --rm -p 8080:8080 arcadia-api:v1

Si l'image a ete build avec APP_PORT=8081 :

docker run --rm -p 8081:8081 arcadia-api:v2

Effet des arguments Docker

• API_VERSION selectionne le module Maven src/api/ a packager
• APP_PORT surcharge server.port dans Spring Boot
• le conteneur fixe aussi automatiquement le context-path a /api/

Exemple pour v1 :

• application : http://localhost:8080/api/v1
• Swagger UI : http://localhost:8080/api/v1/swagger-ui/index.html
• OpenAPI JSON : http://localhost:8080/api/v1/api-docs

Docker Compose

Le fichier docker-compose.yml permet de piloter les differentes versions d'API et leurs parametres via des variables d'environnement.

Un fichier d'exemple est fourni : .env.example

Tu peux t'en servir comme base pour tes variables locales :

cp .env.example .env
docker compose up --build api-v1

Service disponible par defaut :

• api-v1

Service prepare pour une future version :

• api-v2, active uniquement avec le profile compose v2

Lancer v1

docker compose up --build api-v1

Lancer v2

Quand le module src/api/v2 existera :

docker compose --profile v2 up --build api-v2

Parametres configurables

Pour v1 :

• API_V1_VERSION : version build du module API, par defaut v1
• API_V1_PORT : port HTTP du conteneur, par defaut 8080
• API_V1_LOG_LEVEL_ROOT : niveau de log racine, par defaut INFO
• API_V1_LOG_LEVEL_APP : niveau de log applicatif com.openapi.demo, par defaut INFO
• API_V1_SWAGGER_ENABLED : active Swagger UI, par defaut true
• API_V1_API_DOCS_ENABLED : active l'endpoint OpenAPI JSON, par defaut true
• API_V1_API_DOCS_PATH : chemin des api-docs, par defaut /api-docs
• API_V1_SWAGGER_UI_PATH : chemin Swagger UI, par defaut /swagger-ui.html
• API_V1_MANAGEMENT_EXPOSURE : endpoints actuator exposes, par defaut *
• API_V1_MANAGEMENT_HEALTH_DETAILS : niveau de details health actuator, par defaut always

Les memes variables existent pour v2 avec le prefixe API_V2_.

Exemple de lancement avec parametres personnalises

API_V1_PORT=8090 \
API_V1_LOG_LEVEL_ROOT=DEBUG \
API_V1_SWAGGER_ENABLED=true \
API_V1_API_DOCS_ENABLED=true \
docker compose up --build api-v1

Avec cette configuration :

• application : http://localhost:8090/api/v1
• Swagger UI : http://localhost:8090/api/v1/swagger-ui/index.html
• OpenAPI JSON : http://localhost:8090/api/v1/api-docs

Comment ca fonctionne

• le Dockerfile build le module src/api/<version> choisi
• docker-compose passe les variables d'environnement a Spring Boot
• application.properties lit ces variables avec des valeurs par defaut pour le port, les logs, OpenAPI et Actuator

Etat des controles verifies localement

Les commandes suivantes ont ete executees avec succes (exit code 0) :

• ./mvnw spotless:check -q
• ./mvnw checkstyle:check -q
• ./mvnw compile -q