Formation Spring Boot : API REST, sécurité, Kafka et Docker

Structure d’un projet Spring Boot : packages et couches

Organisation, hiérarchie, conventions, configuration, starters et architecture propre pour bâtir des projets Spring Boot réellement maintenables.

Leçon gratuite

Introduction

La structure d’un projet Spring Boot influence directement sa maintenabilité, son évolutivité et la qualité globale de l’architecture. Un projet bien organisé facilite la collaboration, la testabilité et la compréhension du domaine métier.

Dans ce chapitre, vous découvrirez comment organiser vos packages, structurer votre domaine, configurer proprement vos composants et mettre en place une base solide pour un projet professionnel.

Lexique essentiel

Starter Spring Boot

Dépendance prête à l’emploi regroupant configuration et libs associées.

Application Runner

Hook pour exécuter du code au démarrage.

@Component

Annotation générique pour un bean Spring.

@Configuration

Classe déclarant des beans et configurations explicites.

Package-by-feature

Organisation du code centrée sur le métier (recommandée).

Package-by-layer

Organisation technique en couches (à limiter dans de grands projets).

Structure recommandée pour un projet Spring Boot

Spring Boot n’impose pas de structure stricte, mais encourage une organisation claire autour du domaine métier plutôt que des couches techniques. Cette approche améliore la lisibilité et réduit le couplage.

Voici un exemple de structure professionnelle :

src/main/java/com/example/app
│
├── application
│   ├── controllers
│   ├── dto
│   └── handlers
│
├── domain
│   ├── model
│   ├── services
│   └── events
│
├── infrastructure
│   ├── repository
│   ├── configuration
│   └── clients
│
└── AppApplication.java

L’objectif est de séparer clairement : l’application (ce qui expose ou orchestre), le domaine (la logique métier), et l’infrastructure (le technique).

Configuration & conventions

Un projet professionnel doit éviter la configuration “magique”. Les propriétés doivent être explicites, centralisées et structurées via des classes annotées @ConfigurationProperties.

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties(prefix = "app.email")
public record EmailProperties(
    String host,
    int port,
    String sender
) {}

// Enregistrement obligatoire, sinon le record n'est pas un bean :
@SpringBootApplication
@ConfigurationPropertiesScan // ou @EnableConfigurationProperties(EmailProperties.class)
public class AppApplication { /* main(...) */ }

Bonnes pratiques

  • Centraliser la configuration dans un package dédié.
  • Éviter les propriétés dispersées dans plusieurs fichiers.
  • Préférer @ConfigurationProperties à @Value.
  • Construire une architecture orientée métier (package-by-feature).

Astuce d’expert

Combinez les deux approches : découpez d’abord par feature (order/, catalog/, payment/), puis, à l’intérieur de chaque feature, par rôle (application, domain, infrastructure). Ajoutez un test ArchUnit (ou Spring Modulith ApplicationModules.of(ShopApplication.class).verify()) pour empêcher qu’une feature n’accède aux classes internes d’une autre.

Quiz : Structure Spring Boot

  • Q1. Quelle approche est la plus adaptée pour un projet complexe ?
    • A. package-by-layer
    • B. package-by-feature
    • C. tout mettre dans un seul package
  • Q2. Quelle annotation permet de déclarer une configuration propre ?
    • A. @Bean
    • B. @Configuration
    • C. @Entity

Exercice d’application

Créez la structure complète d’un module « gestion des commandes » :
— Quels packages métier devez-vous créer ?
— Quelle partie va dans application / domain / infrastructure ?
— Quels DTO, services et modèles devez-vous définir ?

Résumé

Une bonne structure Spring Boot repose sur des principes simples : code orienté métier, séparation claire des responsabilités, configuration propre et architecture évolutive. Cette fondation garantit maintenabilité et robustesse.

Pour aller plus loin : quand le métier s’étoffe, ce découpage peut évoluer vers une architecture hexagonale Spring Boot, avec un domaine indépendant de Spring et de JPA.

Suivez votre progression. Créez un compte gratuit pour cocher vos leçons et reprendre là où vous en étiez.

Créer un compte gratuit