Chapitre 5: Dictionnaire Complet des Annotations (A-Z)
Référence rapide de toutes les annotations Spring Boot, classées par ordre alphabétique. Pour les exemples de code détaillés, consultez les chapitres 1 à 4.
A
| Annotation | Description |
|---|---|
| @ActiveProfiles | Active des profils Spring spécifiques pour les tests unitaires. Permet de charger application-test.yml par exemple. |
| @After | (JUnit 4) Exécute du code après chaque méthode de test. |
| @AfterClass | (JUnit 4) Exécute du code après toutes les méthodes de test d'une classe. |
| @AfterEach | (JUnit 5) Exécute du code après chaque méthode de test. Remplace @After. |
| @Async | Exécute une méthode de manière asynchrone dans un thread séparé. Nécessite @EnableAsync. |
| @AutoConfigureDataJpa | Configure automatiquement JPA pour un test unitaire. |
| @AutoConfigureJsonTesters | Configure automatiquement les outils de sérialisation/désérialisation JSON pour les tests. |
| @AutoConfigureMockMvc | Configure automatiquement l'objet MockMvc pour un test unitaire. |
| @AutoConfigureWebTestClient | Configure automatiquement le WebTestClient pour les tests WebFlux. |
| @Autowired | Injecte automatiquement une dépendance (bean Spring) dans une classe. Préférer l'injection par constructeur. |
B
| Annotation | Description |
|---|---|
| @Bean | Déclare une méthode qui retourne un objet géré par le conteneur Spring. Utilisée dans les classes @Configuration. |
| @Before | (JUnit 4) Exécute du code avant chaque méthode de test. |
| @BeforeClass | (JUnit 4) Exécute du code avant toutes les méthodes de test d'une classe. |
| @BeforeEach | (JUnit 5) Exécute du code avant chaque méthode de test. Remplace @Before. |
C
| Annotation | Description |
|---|---|
| @Cacheable | Met en cache le résultat d'une méthode. Les appels suivants retournent le résultat du cache. |
| @CacheConfig | Configure les paramètres de cache (nom, durée de vie, taille max) pour une classe entière. |
| @CacheEvict | Supprime une ou toutes les entrées du cache quand la méthode est appelée. |
| @CachePut | Met à jour le cache avec le résultat de la méthode, sans jamais utiliser le cache existant. |
| @CircuitBreaker | (Spring Cloud) Protège une méthode contre les échecs répétés en limitant les appels quand le service est en panne. |
| @Column | Configure le mapping d'une propriété JPA vers une colonne de base de données (nom, nullable, unique, longueur). |
| @Component | Marque une classe comme un bean Spring générique, détecté automatiquement par le component scan. |
| @ComponentScan | Scanne les packages pour détecter automatiquement les classes annotées @Component, @Service, @Repository, etc. |
| @Conditional | Conditionne la création d'un bean en fonction d'une condition personnalisée. |
| @ConditionalOnClass | Crée un bean uniquement si une classe spécifique est présente dans le classpath. |
| @ConditionalOnMissingBean | Crée un bean uniquement si aucun autre bean du même type n'existe déjà. |
| @ConditionalOnProperty | Crée un bean uniquement si une propriété a une certaine valeur dans la configuration. |
| @Configuration | Marque une classe de configuration Spring contenant des méthodes @Bean. |
| @ConfigurationProperties | Lie un groupe de propriétés du fichier de configuration à un objet Java (ex: app.mail.host). |
| @Controller | Marque une classe comme contrôleur Spring MVC qui retourne des vues (templates HTML). |
| @ControllerAdvice | Définit un conseiller global pour tous les contrôleurs (gestion centralisée des exceptions, binding, etc.). |
| @CrossOrigin | Autorise les requêtes HTTP cross-origin (CORS) depuis des domaines spécifiques ou tous les domaines. |
D
| Annotation | Description |
|---|---|
| @DataJpaTest | Test spécialisé qui charge uniquement la couche JPA (repositories, EntityManager, BDD en mémoire). |
| @DeleteMapping | Raccourci pour @RequestMapping(method = DELETE). Mappe une méthode à une requête HTTP DELETE. |
| @Disabled | (JUnit 5) Désactive temporairement un test unitaire sans le supprimer du code. |
E
| Annotation | Description |
|---|---|
| @EnableAsync | Active l'exécution asynchrone dans l'application. Nécessaire pour que @Async fonctionne. |
| @EnableCaching | Active la mise en cache dans l'application. Nécessaire pour que @Cacheable fonctionne. |
| @EnableConfigurationProperties | Active la liaison automatique des propriétés de configuration à des objets @ConfigurationProperties. |
| @EnableJms | Active le support JMS (Java Message Service) pour la messagerie dans l'application. |
| @EnableJpaRepositories | Active le support des repositories Spring Data JPA. Configuré automatiquement par Spring Boot. |
| @EnableScheduling | Active la planification des tâches. Nécessaire pour que @Scheduled fonctionne. |
| @EnableWebMvc | Active la configuration Spring MVC. Rarement nécessaire car Spring Boot l'active automatiquement. |
| @EnableWebSecurity | Active la configuration personnalisée de Spring Security. |
| @EnableMethodSecurity | Active la sécurité au niveau des méthodes (@PreAuthorize, @PostAuthorize, @Secured). |
| @Entity | Marque une classe comme entité JPA, mappée à une table en base de données. |
| @Enumerated | Définit comment un enum Java est stocké en BDD : STRING (texte) ou ORDINAL (nombre). |
| @EventListener | Écoute les événements Spring (démarrage de l'application, événements custom, etc.). |
| @ExceptionHandler | Gère une exception spécifique dans un contrôleur ou un @ControllerAdvice. Retourne une réponse d'erreur personnalisée. |
| @ExtendWith | (JUnit 5) Étend les fonctionnalités des tests avec des extensions (ex: SpringExtension, MockitoExtension). |
F
| Annotation | Description |
|---|---|
| @Fallback | (Spring Cloud) Fournit une méthode de secours quand une méthode @CircuitBreaker est en panne. |
| @FlywayTest | Teste les migrations de base de données Flyway dans les tests d'intégration. |
| @Formula | (Hibernate) Définit une colonne calculée côté SQL, sans colonne physique en base. |
G
| Annotation | Description |
|---|---|
| @GeneratedValue | Définit la stratégie de génération automatique de la clé primaire (IDENTITY, SEQUENCE, UUID, AUTO). |
| @GetMapping | Raccourci pour @RequestMapping(method = GET). Mappe une méthode à une requête HTTP GET. |
I
| Annotation | Description |
|---|---|
| @Id | Marque un champ comme clé primaire d'une entité JPA. |
| @Import | Importe d'autres classes de configuration dans une classe @Configuration. |
| @InitBinder | Personnalise la liaison de données entre les requêtes HTTP et les objets Java (conversion, validation, formatage). |
J
| Annotation | Description |
|---|---|
| @JoinColumn | Définit la colonne de clé étrangère pour une relation JPA (@ManyToOne, @OneToOne). |
| @JoinTable | Définit la table de jointure pour une relation @ManyToMany (nom de la table, colonnes de jointure). |
| @JmsListener | Définit une méthode qui écoute les messages JMS sur une file d'attente ou un topic. |
| @JsonFormat | Personnalise le format de sérialisation JSON (dates, nombres). Ex: @JsonFormat(pattern = "yyyy-MM-dd"). |
| @JsonIgnore | Exclut une propriété de la sérialisation/désérialisation JSON. |
| @JsonInclude | Contrôle quelles propriétés sont incluses dans le JSON (ex: exclure les valeurs null). |
| @JsonProperty | Renomme une propriété dans le JSON. Ex: @JsonProperty("full_name") pour un champ fullName. |
| @JsonSubTypes | Définit les sous-types pour la désérialisation polymorphique JSON. |
| @JsonTest | Test spécialisé pour la sérialisation/désérialisation JSON uniquement. |
| @JsonTypeInfo | Ajoute des informations de type dans le JSON pour permettre la désérialisation polymorphique. |
| @JsonView | Filtre les propriétés JSON selon la vue demandée (ex: vue publique vs vue admin). |
L
| Annotation | Description |
|---|---|
| @Lazy | Retarde l'initialisation d'un bean jusqu'à sa première utilisation. Améliore le temps de démarrage. |
| @Lob | Indique un champ de type Large Object : CLOB (texte long) ou BLOB (binaire). |
M
| Annotation | Description |
|---|---|
| @ManyToMany | Définit une relation plusieurs-à-plusieurs entre deux entités JPA. Utilise une table de jointure. |
| @ManyToOne | Définit une relation plusieurs-à-un. Le côté "Many" porte la clé étrangère. |
| @MessageMapping | (WebSocket/STOMP) Mappe une méthode à une destination de messagerie. |
| @MessagingGateway | (Spring Integration) Définit une interface de passerelle pour envoyer des messages. |
| @MockBean | Remplace un bean Spring par un mock Mockito dans un test. |
| @MockMvc | Injecte une instance MockMvc pour simuler des requêtes HTTP dans les tests. |
| @ModelAttribute | Lie les paramètres d'une requête HTTP à un objet Java. Utilisé aussi pour ajouter des attributs au modèle MVC. |
| @Modifying | Indique qu'une méthode @Query exécute un UPDATE ou DELETE (pas un SELECT). |
N
| Annotation | Description |
|---|---|
| @NamedQuery | Définit une requête JPQL nommée directement sur une entité. |
| @NamedQueries | Regroupe plusieurs @NamedQuery sur une même entité. |
O
| Annotation | Description |
|---|---|
| @OneToMany | Définit une relation un-à-plusieurs entre deux entités JPA. Le côté "One" est le parent. |
| @OneToOne | Définit une relation un-à-un entre deux entités JPA. |
| @Order | Définit l'ordre de priorité d'un bean. Plus le nombre est petit, plus la priorité est haute. |
P
| Annotation | Description |
|---|---|
| @PatchMapping | Raccourci pour @RequestMapping(method = PATCH). Mise à jour partielle d'une ressource. |
| @PathVariable | Extrait une variable depuis le chemin de l'URL. Ex: /users/\{id\} → @PathVariable Long id. |
| @PostAuthorize | Vérifie les autorisations après l'exécution d'une méthode (peut vérifier la valeur retournée). |
| @PostConstruct | Exécute une méthode juste après l'injection de toutes les dépendances du bean. |
| @PostMapping | Raccourci pour @RequestMapping(method = POST). Création d'une nouvelle ressource. |
| @PreAuthorize | Vérifie les autorisations avant l'exécution d'une méthode. Supporte les expressions SpEL. |
| @PreDestroy | Exécute une méthode juste avant la destruction du bean (nettoyage, fermeture de connexions). |
| @Primary | Définit le bean par défaut quand plusieurs beans du même type existent. |
| @Profile | Active un bean ou une configuration uniquement pour certains profils (dev, test, prod). |
| @PutMapping | Raccourci pour @RequestMapping(method = PUT). Remplacement complet d'une ressource. |
Q
| Annotation | Description |
|---|---|
| @Qualifier | Spécifie quel bean injecter quand plusieurs beans du même type existent. |
| @Query | Définit une requête JPQL ou SQL native personnalisée sur une méthode de repository. |
R
| Annotation | Description |
|---|---|
| @Repository | Marque une classe comme couche d'accès aux données. Active la traduction des exceptions SQL en exceptions Spring. |
| @RequestBody | Désérialise le corps de la requête HTTP (JSON) en objet Java. |
| @RequestHeader | Extrait la valeur d'un en-tête HTTP (Authorization, Content-Type, User-Agent, etc.). |
| @RequestMapping | Annotation de base pour mapper une URL à un contrôleur ou une méthode. Peut spécifier la méthode HTTP. |
| @RequestParam | Extrait un paramètre de la query string. Ex: /search?name=Java → @RequestParam String name. |
| @RequestPart | Extrait une partie d'une requête HTTP multipart (fichiers, images uploadés). |
| @ResponseBody | Force le retour d'une méthode en JSON/XML directement dans le corps de la réponse HTTP. |
| @ResponseStatus | Définit le code HTTP retourné par une méthode (200, 201, 204, 404, etc.) ou une exception. |
| @RestClientTest | Test spécialisé pour les clients REST. Charge uniquement la configuration client. |
| @RestController | Combinaison de @Controller + @ResponseBody. Chaque méthode retourne du JSON directement. |
| @RestControllerAdvice | Combinaison de @ControllerAdvice + @ResponseBody. Gestion globale des exceptions pour les API REST. |
| @Retryable | (Spring Retry) Réessaie automatiquement une méthode en cas d'échec (ex: erreur réseau ou BDD). |
| @RolesAllowed | (JSR-250) Spécifie les rôles autorisés pour une méthode. Alternative standard à @Secured. |
S
| Annotation | Description |
|---|---|
| @Scheduled | Planifie l'exécution périodique d'une méthode (fixedRate, fixedDelay, cron). Nécessite @EnableScheduling. |
| @Scope | Définit la portée d'un bean : singleton (défaut), prototype, request, session, application. |
| @Secured | Spécifie les rôles requis pour accéder à une méthode. Plus simple que @PreAuthorize. |
| @SendTo | (WebSocket/STOMP) Spécifie la destination de réponse pour un message WebSocket. |
| @Service | Marque une classe comme couche de logique métier. Détecté par le component scan. |
| @SessionAttributes | Stocke des attributs du modèle dans la session HTTP entre les requêtes. |
| @SessionScope | Définit la portée d'un bean comme session HTTP (un bean par session utilisateur). |
| @SpyBean | Enveloppe un vrai bean avec un spy Mockito dans les tests (appels réels sauf ceux stubés). |
| @SpringBootApplication | Point d'entrée de l'application. Combine @Configuration, @EnableAutoConfiguration et @ComponentScan. |
| @SpringBootTest | Charge le contexte Spring complet pour les tests d'intégration. |
| @Sql | Exécute des scripts SQL avant ou après un test pour préparer ou nettoyer la base de données. |
T
| Annotation | Description |
|---|---|
| @Table | Personnalise le nom de la table, le schéma, les contraintes d'unicité et les index pour une entité JPA. |
| @Test | (JUnit) Marque une méthode comme test unitaire. |
| @TestConfiguration | Fournit une configuration Spring spécifique aux tests (beans de test, mocks). |
| @Timeout | (JUnit 5) Définit un délai maximum pour l'exécution d'un test. Le test échoue si le délai est dépassé. |
| @Transactional | Gère les transactions BDD. Commit si succès, rollback si exception. readOnly = true optimise les lectures. |
| @TransactionalEventListener | Écoute un événement Spring et l'exécute seulement après le commit (ou rollback) de la transaction. |
| @Transient | Exclut un champ de la persistance JPA (pas de colonne en base de données). |
V
| Annotation | Description |
|---|---|
| @Valid | Active la validation Bean Validation sur un objet (@NotNull, @Size, @Email, etc.). |
| @Validated | Variante Spring de @Valid avec support des groupes de validation. |
| @Value | Injecte une valeur depuis le fichier de configuration. Ex: @Value("${app.name}"). Supporte les valeurs par défaut et SpEL. |
| @ValueSource | (JUnit 5) Fournit des valeurs d'entrée à un test paramétré. |
W
| Annotation | Description |
|---|---|
| @WebFluxTest | Test spécialisé pour les contrôleurs WebFlux (programmation réactive). |
| @WebMvcTest | Test spécialisé qui charge uniquement la couche contrôleur MVC (pas de BDD, pas de services réels). |
| @WebTestClient | Injecte un WebTestClient pour simuler des requêtes HTTP dans les tests WebFlux. |
Annotations de Validation (Bean Validation)
| Annotation | Description |
|---|---|
| @NotNull | Le champ ne peut pas être null. |
| @NotEmpty | Le champ ne peut pas être null ni vide (String, Collection, Map). |
| @NotBlank | Le champ ne peut pas être null, vide ou contenir uniquement des espaces. |
| @Size(min, max) | La taille doit être comprise entre min et max (String, Collection). |
| @Min(value) | La valeur numérique doit être supérieure ou égale à value. |
| @Max(value) | La valeur numérique doit être inférieure ou égale à value. |
| Le champ doit être un format d'adresse email valide. | |
| @Pattern(regexp) | Le champ doit correspondre à l'expression régulière donnée. |
| @Positive | Le nombre doit être strictement positif (> 0). |
| @PositiveOrZero | Le nombre doit être positif ou zéro (>= 0). |
| @Negative | Le nombre doit être strictement négatif (< 0). |
| @Past | La date doit être dans le passé. |
| @Future | La date doit être dans le futur. |
| @DecimalMin | La valeur décimale doit être supérieure ou égale au minimum. |
| @DecimalMax | La valeur décimale doit être inférieure ou égale au maximum. |
Statistiques
En résumé
Ce dictionnaire couvre 120+ annotations réparties en :
- Core Spring : ~25 annotations (IoC, DI, configuration, lifecycle)
- Web / REST : ~20 annotations (mapping, paramètres, réponses, erreurs)
- Data / JPA : ~20 annotations (entités, relations, requêtes, transactions)
- JSON / Jackson : ~7 annotations (format, filtre, ignore)
- Security : ~7 annotations (config, autorisation)
- Cache : ~5 annotations (cacheable, evict, put, config)
- Async / Scheduling : ~5 annotations
- Test : ~25 annotations (JUnit, Spring Test, mocks)
- Validation : ~15 annotations (Bean Validation)
- Messaging : ~5 annotations (JMS, WebSocket)
- Cloud / Resilience : ~3 annotations (CircuitBreaker, Retry, Fallback)