Créer sa première application Spring Boot pas à pas

📌 Article principal de la série : Java Enterprise : Spring Boot, Jakarta EE et microservices modernes
Ce tutoriel fait partie de la série Java Enterprise. Pour la vue d’ensemble de l’écosystème, consultez l’article principal.

Spring Boot est le point d’entrée le plus direct dans le développement Java enterprise moderne. Là où Spring Framework classique demandait des dizaines de fichiers de configuration XML ou Java pour démarrer une application web, Spring Boot réduit cela à quelques clics sur Spring Initializr et une classe principale avec une annotation. Ce tutoriel couvre l’installation de Java 21 et Maven, la génération d’un projet Spring Boot via Spring Initializr, la compréhension de la structure générée, la création d’un premier endpoint REST, et le lancement et test de l’application — le tout sur Linux, macOS et Windows.

Prérequis

• Un ordinateur sous Linux (Ubuntu 22.04+ / Debian 12), macOS 13+ ou Windows 10/11
• Accès administrateur ou sudo
• Connexion Internet
• Connaissance de base de Java (classes, méthodes, annotations) — aucune expérience Spring requise
• Niveau : débutant Spring Boot
• Temps estimé : 45 à 60 minutes

Étape 1 — Installer Java 21 LTS

Spring Boot 3.x requiert Java 17 minimum, mais Java 21 LTS est le choix recommandé pour tous les nouveaux projets en 2025 : c’est la version LTS courante, supportée jusqu’en septembre 2031, et elle apporte les virtual threads (JEP 444) que Spring Boot 3.2+ exploite nativement. Il existe plusieurs distributions OpenJDK ; les plus utilisées en entreprise sont Eclipse Temurin (anciennement AdoptOpenJDK) et les builds Oracle.

# === Linux (Ubuntu/Debian) ===
# Installer Eclipse Temurin 21 via apt (dépôt Adoptium)
sudo apt install -y wget apt-transport-https gpg
wget -qO - https://packages.adoptium.net/artifactory/api/gpg/key/public \
  | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/adoptium.gpg > /dev/null
echo "deb https://packages.adoptium.net/artifactory/deb $(lsb_release -cs) main" \
  | sudo tee /etc/apt/sources.list.d/adoptium.list
sudo apt update
sudo apt install temurin-21-jdk

# Vérification
java -version
javac -version

Ces commandes ajoutent le dépôt APT officiel d’Eclipse Adoptium (la fondation qui distribue Temurin), importent sa clé GPG pour vérifier l’authenticité des paquets, puis installent le JDK 21. La commande java -version doit afficher openjdk version "21.x.x" et javac -version doit afficher javac 21.x.x. Si l’une des deux commandes échoue avec « command not found », fermez et rouvrez le terminal pour recharger le PATH.

# === macOS (via Homebrew) ===
brew install --cask temurin@21

# Vérification
java -version

# === Windows (via winget, PowerShell administrateur) ===
winget install EclipseAdoptium.Temurin.21.JDK

# Fermer et rouvrir PowerShell, puis vérifier
java -version

Sur macOS, Homebrew installe le JDK dans /Library/Java/JavaVirtualMachines/. Sur Windows, winget installe le JDK et met à jour automatiquement la variable d’environnement JAVA_HOME — vous devez fermer et rouvrir PowerShell pour que la modification soit prise en compte. Si java -version affiche une version différente de 21 (système Java préexistant), utilisez jenv (macOS/Linux) ou les variables d’environnement Windows pour forcer Java 21.

Étape 2 — Installer Maven 3.9

Maven est l’outil de build le plus utilisé dans l’écosystème Spring Boot. Il gère les dépendances (téléchargement depuis Maven Central), le cycle de vie de build (compilation, tests, packaging) et la structure standard du projet. Maven 3.9.x est la version stable recommandée.

# === Linux / macOS ===
# Télécharger Maven 3.9.9 depuis apache.org
MVN_VERSION="3.9.9"
wget https://dlcdn.apache.org/maven/maven-3/${MVN_VERSION}/binaries/apache-maven-${MVN_VERSION}-bin.tar.gz
sudo tar -xzf apache-maven-${MVN_VERSION}-bin.tar.gz -C /opt
sudo ln -s /opt/apache-maven-${MVN_VERSION} /opt/maven

# Ajouter Maven au PATH (bash/zsh)
echo 'export MAVEN_HOME=/opt/maven' >> ~/.bashrc
echo 'export PATH=$MAVEN_HOME/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Vérification
mvn -version

La commande mvn -version doit retourner quelque chose comme Apache Maven 3.9.9 suivi du chemin Java — vérifiez que le Java listé est bien la version 21 que vous venez d’installer. Si Maven utilise un autre Java, définissez la variable JAVA_HOME : export JAVA_HOME=$(dirname $(dirname $(readlink -f $(which java)))) avant de relancer mvn -version. Sur Windows, téléchargez le ZIP depuis maven.apache.org, extrayez dans C:\tools\maven\ et ajoutez C:\tools\maven\bin aux variables d’environnement système.

Étape 3 — Générer le projet avec Spring Initializr

Spring Initializr est le générateur de projets Spring Boot officiel, disponible à l’adresse start.spring.io. Il génère la structure complète du projet avec le pom.xml configuré et la classe principale. Vous pouvez utiliser l’interface web ou la ligne de commande avec curl.

# Générer le projet en ligne de commande avec curl
curl https://start.spring.io/starter.tgz \
  -d type=maven-project \
  -d language=java \
  -d bootVersion=3.5.14 \
  -d baseDir=demo-spring \
  -d groupId=io.itskillscenter \
  -d artifactId=demo-spring \
  -d name=demo-spring \
  -d packageName=io.itskillscenter.demo \
  -d javaVersion=21 \
  -d dependencies=web \
  | tar -xzf -

cd demo-spring
ls -la

Cette commande génère un projet Spring Boot 3.5.x avec la dépendance spring-boot-starter-web (serveur Tomcat embarqué + Spring MVC + Jackson JSON). Les paramètres groupId et artifactId suivent la convention Maven : le groupId identifie l’organisation (souvent le nom de domaine inversé), l’artifactId identifie le projet. Le répertoire généré contient la structure Maven standard : src/main/java/ pour le code source, src/main/resources/ pour la configuration, src/test/java/ pour les tests.

Étape 4 — Comprendre la structure du projet généré

Avant d’écrire du code, prenez le temps de comprendre ce que Spring Initializr a généré. Une mauvaise compréhension de la structure Spring Boot est la cause de nombreuses erreurs débutantes.

demo-spring/
├── pom.xml                          ← Descripteur Maven : dépendances, plugins, métadonnées
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── io/itskillscenter/demo/
│   │   │       └── DemoSpringApplication.java   ← Point d'entrée (méthode main)
│   │   └── resources/
│   │       ├── application.properties           ← Configuration Spring Boot
│   │       ├── static/                          ← Fichiers statiques (JS, CSS)
│   │       └── templates/                       ← Templates Thymeleaf (si ajouté)
│   └── test/
│       └── java/
│           └── io/itskillscenter/demo/
│               └── DemoSpringApplicationTests.java  ← Test de chargement du contexte
└── mvnw / mvnw.cmd                  ← Maven Wrapper (pas besoin d'installer Maven)

Le fichier DemoSpringApplication.java contient la méthode main annotée avec @SpringBootApplication. Cette annotation composite combine trois annotations : @Configuration (classe de configuration Spring), @EnableAutoConfiguration (déclenche l’auto-configuration Spring Boot) et @ComponentScan (scan les classes annotées dans le package courant et ses sous-packages). Le Maven Wrapper (mvnw) permet d’utiliser Maven sans l’avoir installé globalement — il télécharge la bonne version de Maven automatiquement. C’est utile pour les environnements CI/CD.

Étape 5 — Créer un premier endpoint REST

Avec la structure en place, il est temps d’écrire le premier controller REST. Créez un nouveau fichier Java dans le package principal. La convention Spring Boot est de placer les controllers dans un sous-package controller du package principal.

# Créer le sous-package controller
mkdir -p src/main/java/io/itskillscenter/demo/controller

Créez maintenant le fichier ProduitController.java dans ce nouveau répertoire. Ce fichier définit un controller Spring MVC qui expose deux endpoints REST :

// src/main/java/io/itskillscenter/demo/controller/ProduitController.java
package io.itskillscenter.demo.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;
import java.util.Map;

@RestController
@RequestMapping("/api/produits")
public class ProduitController {

    // Données statiques pour démonstration
    private static final List<Map<String, Object>> PRODUITS = List.of(
        Map.of("id", 1, "nom", "Laptop ThinkPad", "prix", 850000),
        Map.of("id", 2, "nom", "Souris USB", "prix", 15000),
        Map.of("id", 3, "nom", "Clé USB 64GB", "prix", 8000)
    );

    @GetMapping
    public List<Map<String, Object>> listerProduits() {
        return PRODUITS;
    }

    @GetMapping("/{id}")
    public Map<String, Object> obtenirProduit(@PathVariable int id) {
        return PRODUITS.stream()
            .filter(p -> (int) p.get("id") == id)
            .findFirst()
            .orElseThrow(() -> new RuntimeException("Produit non trouvé : " + id));
    }
}

L’annotation @RestController combine @Controller et @ResponseBody : chaque méthode retourne directement des données sérialisées en JSON par Jackson, sans passer par un template de vue. @RequestMapping("/api/produits") au niveau de la classe préfixe toutes les routes du controller. @GetMapping sans paramètre gère GET /api/produits. @GetMapping("/{id}") capture le segment {id} de l’URL et @PathVariable l’injecte dans le paramètre de méthode. La méthode orElseThrow lève une exception si le produit n’est pas trouvé — dans un projet réel, on utiliserait une exception personnalisée avec un handler global (@ControllerAdvice).

Étape 6 — Lancer et tester l’application

Spring Boot embarque Tomcat directement dans le JAR de l’application — aucun serveur d’application externe à installer ni à configurer. Lancer l’application est aussi simple que d’exécuter la commande Maven suivante :

# Dans le répertoire demo-spring/
mvn spring-boot:run

Maven compile le projet, résout les dépendances depuis Maven Central (première fois : téléchargement de plusieurs dizaines de MBs dans ~/.m2/repository/), puis lance l’application. Dans la console, vous devez voir des lignes de log Tomcat similaires à :

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::               (v3.5.14)

...
Tomcat started on port 8080 (http) with context path '/'
Started DemoSpringApplication in 2.341 seconds

Le serveur est prêt lorsque vous voyez « Started DemoSpringApplication in X seconds ». Spring Boot démarre sur le port 8080 par défaut. Ouvrez un second terminal et testez les deux endpoints :

# Lister tous les produits
curl -s http://localhost:8080/api/produits | python3 -m json.tool

# Récupérer le produit #2
curl -s http://localhost:8080/api/produits/2 | python3 -m json.tool

# Tester un produit inexistant (doit retourner une erreur 500 pour l'instant)
curl -s -o /dev/null -w "HTTP %{http_code}\n" http://localhost:8080/api/produits/99

Le premier appel retourne un tableau JSON avec les 3 produits. Le second retourne uniquement le produit avec l’ID 2. Le troisième retourne HTTP 500 (Internal Server Error) parce que orElseThrow lève une RuntimeException non gérée — dans le tutoriel sur l’API REST complète avec Spring Data JPA, on ajoute une gestion d’erreurs propre avec des codes HTTP corrects (404, 422, etc.).

Étape 7 — Packager l’application en JAR exécutable

L’un des atouts de Spring Boot est de produire un « fat JAR » — un fichier JAR unique contenant l’application et toutes ses dépendances, directement exécutable avec java -jar sans configuration de serveur externe. C’est le format de déploiement standard pour les containers Docker et les déploiements cloud.

# Stopper le serveur (Ctrl+C dans le terminal où il tourne)

# Compiler et packager
mvn clean package -DskipTests

# Lancer le JAR produit
java -jar target/demo-spring-0.0.1-SNAPSHOT.jar

# Vérifier que le JAR est bien lancé
curl -s http://localhost:8080/api/produits

La commande mvn clean package compile tout le code, exécute les tests (l’option -DskipTests les saute pour accélérer), puis produit le JAR dans le répertoire target/. La commande java -jar target/demo-spring-0.0.1-SNAPSHOT.jar lance l’application directement. Notez que le JAR Spring Boot n’est pas un JAR Maven ordinaire — il contient un mécanisme de classloading spécial (Spring Boot Loader) qui extrait et charge les dépendances embarquées. C’est pour cette raison qu’il est dit « fat JAR » ou « uber-JAR ».

Erreurs fréquentes

Tutoriels frères

• Construire une API REST avec Spring Boot et Spring Data JPA — Étape suivante : persistance en base de données, entités JPA, repositories et gestion des erreurs

Pour aller plus loin

• 🔝 Retour à l’article principal : Java Enterprise : Spring Boot, Jakarta EE et microservices modernes
• Getting Started — Documentation officielle Spring Boot
• Spring Initializr — interface web de génération de projets
• Spring MVC — Documentation officielle

FAQ

Quelle est la différence entre @Controller et @RestController ?

@Controller est le controller Spring MVC classique qui retourne des noms de vues (Thymeleaf, JSP) pour le rendu HTML côté serveur. @RestController est équivalent à @Controller + @ResponseBody sur chaque méthode : les valeurs retournées sont directement sérialisées en JSON (ou XML) et écrites dans la réponse HTTP. Pour une API REST, utilisez systématiquement @RestController.

Faut-il installer Tomcat séparément pour Spring Boot ?

Non. Spring Boot embarque Tomcat (ou Jetty / Undertow selon la configuration) directement dans le fat JAR de l’application. C’est l’un des avantages majeurs de Spring Boot par rapport à Spring Framework classique qui nécessitait de déployer un WAR sur un serveur Tomcat externe.

Comment modifier le port par défaut (8080) de Spring Boot ?

Ajoutez server.port=8081 (ou tout autre numéro) dans src/main/resources/application.properties. Vous pouvez aussi passer le port en ligne de commande : java -jar app.jar --server.port=8081, ou définir la variable d’environnement SERVER_PORT=8081 — Spring Boot honore toutes ces méthodes de configuration avec une priorité définie.