Checklist complète pour migrer vers Spring Boot 4 sans douleur

Migrer vers Spring Boot 4 demande de la méthode. Une migration mal préparée peut bloquer votre équipe pendant des jours. Cette checklist vous guide étape par étape pour une migration maîtrisée et sans mauvaise surprise.

Phase 1 : Prérequis et préparation

Environnement Java

• ☐ Installer Java 21 LTS sur tous les postes de développement
• ☐ Mettre à jour les IDE (IntelliJ 2024.1+, Eclipse 2024-03+, VS Code avec Extension Pack for Java récent)
• ☐ Configurer JAVA_HOME pour pointer vers Java 21
• ☐ Vérifier la compatibilité CI/CD (GitHub Actions, GitLab CI, Jenkins)

java -version

echo $JAVA_HOME

Audit des dépendances

• ☐ Lister toutes les dépendances avec leurs versions actuelles
• ☐ Identifier les dépendances critiques (ORM, Security, Messaging)
• ☐ Vérifier la compatibilité Java 21 pour chaque dépendance
• ☐ Repérer les dépendances sans maintenance (risque de blocage)

./mvnw versions:display-dependency-updates

./gradlew dependencyUpdates

Sauvegarde et branche

• ☐ Créer une branche dédiée feature/spring-boot-4-migration
• ☐ Taguer la version stable actuelle pour rollback facile
• ☐ Documenter l'état actuel (versions, configuration, comportements)

git checkout -b feature/spring-boot-4-migration
git tag -a v3.3-stable -m "Dernière version stable avant migration SB4"

Phase 2 : Migration du POM/Build

Mise à jour Spring Boot

• ☐ Changer la version parent Spring Boot

<!-- pom.xml : Avant -->
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.3.x</version>
</parent>

<!-- pom.xml : Après -->
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>4.0.0</version>
</parent>

• ☐ Mettre à jour la version Java

<properties>
    <java.version>21</java.version>
</properties>

Dépendances à mettre à jour

• ☐ Hibernate : vérifier la compatibilité (7.x inclus dans SB4)
• ☐ Spring Security : 7.x inclus automatiquement
• ☐ Spring Cloud : passer à la version 2024.x
• ☐ Lombok : version 1.18.34+
• ☐ MapStruct : version 1.6.x
• ☐ Flyway : version 10.x uniquement

<!-- Exemple : Spring Cloud compatible -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>2024.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Starters modifiés

• ☐ Vérifier les starters supprimés (Jetty standalone)
• ☐ Ajouter le nouveau starter observabilité si besoin

<!-- Nouveau starter unifié observabilité -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-observability</artifactId>
</dependency>

Phase 3 : Migration du code

Spring Security

• ☐ Remplacer authorizeRequests() par authorizeHttpRequests()
• ☐ Remplacer antMatchers() par requestMatchers()
• ☐ Configurer CSRF explicitement pour les APIs REST
• ☐ Vérifier la configuration CORS

// AVANT (erreur en SB4)
http.authorizeRequests()
    .antMatchers("/api/**").authenticated();

// APRÈS (obligatoire)
http.authorizeHttpRequests(auth -> auth
    .requestMatchers("/api/**").authenticated()
);

// CSRF pour API REST stateless
http.csrf(csrf -> csrf.disable());

Hibernate et JPA

• ☐ Vérifier les @ManyToOne : maintenant LAZY par défaut
• ☐ Migrer les Criteria legacy vers JPA Criteria API
• ☐ Tester les requêtes N+1 qui peuvent apparaître

// ATTENTION : comportement modifié
@ManyToOne  // Était EAGER, maintenant LAZY par défaut
private Customer customer;

// Si EAGER nécessaire, expliciter :
@ManyToOne(fetch = FetchType.EAGER)
private Customer customer;

• ☐ Supprimer les APIs Hibernate dépréciées

// SUPPRIMÉ en Hibernate 7
Criteria criteria = session.createCriteria(User.class);

// REMPLACER PAR
CriteriaBuilder cb = entityManager.getCriteriaBuilder();
CriteriaQuery<User> query = cb.createQuery(User.class);
Root<User> root = query.from(User.class);

Servlet API

• ☐ Vérifier getRequestURL() : retourne StringBuilder (non StringBuffer)

// Avant (potentiel warning)
StringBuffer url = request.getRequestURL();

// Après (compatible et propre)
String url = request.getRequestURL().toString();

Métriques et observabilité

• ☐ Migrer l'API Micrometer vers la nouvelle syntaxe

// AVANT (Micrometer 1.x)
Metrics.counter("api.requests", "endpoint", "/users").increment();

// APRÈS (Micrometer 2.x)
Metrics.counter("api.requests", Tags.of("endpoint", "/users")).increment();

• ☐ Adopter l'API Observations pour les nouvelles métriques

@Observed(name = "user.service", contextualName = "get-user")
public User getUser(Long id) {
    return userRepository.findById(id).orElseThrow();
}

Phase 4 : Migration de la configuration

Propriétés application.yml

• ☐ Scanner les propriétés dépréciées

grep -r "spring.datasource.initialization-mode" src/
grep -r "use-new-id-generator-mappings" src/
grep -r "management.metrics.tags" src/

• ☐ Renommer les propriétés

• ☐ Configurer les nouvelles valeurs par défaut sécurité

spring:
  security:
    # Désactiver CSRF pour API REST si nécessaire
    csrf:
      enabled: false

management:
  observations:
    key-values:
      application: ${spring.application.name}
      environment: ${ENVIRONMENT:dev}

Logging structuré

• ☐ Activer le logging JSON si environnement cloud

logging:
  structured:
    format:
      console: ecs  # Elastic Common Schema
      file: json

Phase 5 : Tests et validation

Tests unitaires

• ☐ Exécuter tous les tests unitaires
• ☐ Corriger les tests en échec liés aux changements d'API
• ☐ Vérifier les mocks Spring Security (API modifiée)

./mvnw test

Tests d'intégration

• ☐ Exécuter les tests d'intégration
• ☐ Vérifier les tests @DataJpaTest (changement Hibernate)
• ☐ Tester les endpoints sécurisés

./mvnw verify

Tests de régression

• ☐ Tester manuellement les parcours critiques
• ☐ Vérifier les comportements de lazy loading
• ☐ Valider les réponses API (format, codes HTTP)

Tests de performance

• ☐ Mesurer le temps de démarrage
• ☐ Comparer la consommation mémoire
• ☐ Exécuter un test de charge léger

time java -jar target/app.jar --spring.main.banner-mode=off &

jcmd <pid> VM.native_memory summary

Phase 6 : Infrastructure

Images Docker

• ☐ Mettre à jour l'image de base

FROM eclipse-temurin:17-jre

FROM eclipse-temurin:21-jre

• ☐ Reconstruire et tester l'image

docker build -t myapp:sb4 .
docker run -p 8080:8080 myapp:sb4

CI/CD

• ☐ Mettre à jour les pipelines avec Java 21
• ☐ Vérifier les caches Maven/Gradle
• ☐ Tester le build complet en CI

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'

Environnements

• ☐ Déployer en environnement de dev
• ☐ Valider en staging avec données réalistes
• ☐ Préparer le rollback en cas de problème

Phase 7 : Déploiement production

Checklist pré-déploiement

• ☐ Tous les tests passent (unitaires, intégration, performance)
• ☐ Documentation mise à jour (README, runbook)
• ☐ Équipe informée du déploiement
• ☐ Monitoring prêt à détecter les anomalies
• ☐ Plan de rollback documenté

Déploiement

• ☐ Déployer en heures creuses si possible
• ☐ Surveiller les logs pendant 30 minutes
• ☐ Vérifier les métriques (latence, erreurs, mémoire)
• ☐ Valider les parcours critiques en production

Post-déploiement

• ☐ Garder l'ancienne version disponible 48h minimum
• ☐ Documenter les problèmes rencontrés
• ☐ Partager le retour d'expérience avec l'équipe

Scripts utilitaires

Script de vérification des prérequis

#!/bin/bash
echo "=== Vérification prérequis Spring Boot 4 ==="

java_version=$(java -version 2>&1 | head -n 1 | cut -d'"' -f2 | cut -d'.' -f1)
if [ "$java_version" -ge 21 ]; then
    echo "✅ Java $java_version (21+ requis)"
else
    echo "❌ Java $java_version (21+ requis)"
fi

mvn_version=$(mvn -v 2>&1 | head -n 1 | cut -d' ' -f3)
echo "ℹ️  Maven $mvn_version"

echo ""
echo "=== Propriétés dépréciées détectées ==="
grep -r "spring.datasource.initialization-mode" src/ 2>/dev/null && echo "⚠️  initialization-mode trouvé"
grep -r "use-new-id-generator-mappings" src/ 2>/dev/null && echo "⚠️  use-new-id-generator-mappings trouvé"

echo ""
echo "=== Patterns Security dépréciés ==="
grep -r "authorizeRequests()" src/ 2>/dev/null && echo "⚠️  authorizeRequests() trouvé"
grep -r "antMatchers(" src/ 2>/dev/null && echo "⚠️  antMatchers() trouvé"

Script de migration des imports

#!/bin/bash

echo "=== Fichiers à modifier ==="

echo ""
echo "--- Security ---"
grep -rl "authorizeRequests()" src/main/java/

echo ""
echo "--- Hibernate Criteria legacy ---"
grep -rl "session.createCriteria" src/main/java/

echo ""
echo "--- Micrometer 1.x syntax ---"
grep -rl 'counter.*".*",.*"' src/main/java/

Temps estimé par phase

Ressources complémentaires

Pour comprendre en détail chaque breaking change, consultez notre article : Spring Boot 4 : breaking changes à connaître avant de migrer

Pour comparer objectivement les deux versions : Spring Boot 3 vs Spring Boot 4 : comparatif technique et performance

Pour une vision stratégique : Spring Boot 4 : faut-il migrer maintenant ?

Cette checklist couvre les cas les plus courants. Adaptez-la à votre contexte : certaines étapes peuvent être non applicables selon votre stack. L'essentiel est de procéder méthodiquement et de valider chaque phase avant de passer à la suivante.