Async-First — Quick Reference
Décharger les traitements > 200 ms vers des workers en arrière-plan, pour garder l'UI/API réactives.
Quand activer l'async
| Cas |
Async ? |
| Envoi d'email transactionnel |
✅ |
| Génération PDF / export CSV |
✅ |
| Appel API tierce > 200 ms |
✅ |
| Traitement batch nocturne |
✅ |
| Lecture base de données triviale |
❌ |
Cinq invariants non-négociables
- HTTP < 200 ms. Toute opération qui dépasse ce seuil doit être déportée.
- Idempotence obligatoire. Un message peut être rejoué — concevoir comme tel (idempotency keys, dedupe).
- Retry + Dead Letter Queue. 3 tentatives, backoff exponentiel + jitter. Au-delà → DLQ + alerte.
- Competing consumers. 4-8 workers en parallèle pour absorber les pics.
- Lifecycle tracking. Logs structurés, métriques (latence, taux erreur, DLQ depth) et alertes.
Frameworks recommandés
| Stack |
Framework |
Notes |
| Symfony |
Symfony Messenger |
Transport AMQP, Redis, Doctrine ; supports Stamps |
| Laravel |
Laravel Queue (Horizon en prod) |
Backed by Redis ou SQS ; supervision native |
| PHP framework-agnostic |
Ecotone |
DDD, sagas, scheduler, messaging unifié |
| Node.js |
BullMQ ou RabbitMQ |
Redis-backed avec dashboard |
Pattern minimal (Symfony Messenger)
// Message (immutable DTO)
final class SendWelcomeEmail
{
public function __construct(public readonly string $userId) {}
}
// Handler
final class SendWelcomeEmailHandler
{
public function __invoke(SendWelcomeEmail $message): void
{
// Idempotency check
if ($this->emailLog->wasSent($message->userId, 'welcome')) {
return;
}
$this->mailer->sendWelcome($message->userId);
$this->emailLog->record($message->userId, 'welcome');
}
}
// Dispatch (controller)
$this->bus->dispatch(new SendWelcomeEmail($user->id));
Anti-patterns critiques
- ❌ Mettre une opération idempotente directement dans le handler sans clé d'idempotency (replay = double effet).
- ❌
try { ... } catch (\Throwable) { /* swallow */ } dans un handler → le message est marqué traité alors qu'il a échoué.
- ❌ Stocker la payload complète d'un email/PDF dans le message → préférer un ID + lookup, sinon RabbitMQ explose.
- ❌ Pas de circuit breaker autour des appels tiers : un provider down fait monter la DLQ en flèche.
Pour aller plus loin
Détails complets, patterns Laravel/Ecotone, exemples de configuration, observabilité OpenTelemetry, lifecycle events, checklists par phase : voir @.claude/skills/async/REFERENCE.md.
1---2name: async-33description: Async-First — Quick Reference4---56# Async-First — Quick Reference78Décharger les traitements > 200 ms vers des workers en arrière-plan, pour garder l'UI/API réactives.910## Quand activer l'async1112| Cas | Async ? |13|-----|---------|14| Envoi d'email transactionnel | ✅ |15| Génération PDF / export CSV | ✅ |16| Appel API tierce > 200 ms | ✅ |17| Traitement batch nocturne | ✅ |18| Lecture base de données triviale | ❌ |1920## Cinq invariants non-négociables21221. **HTTP < 200 ms.** Toute opération qui dépasse ce seuil doit être déportée.232. **Idempotence obligatoire.** Un message peut être rejoué — concevoir comme tel (idempotency keys, dedupe).243. **Retry + Dead Letter Queue.** 3 tentatives, backoff exponentiel + jitter. Au-delà → DLQ + alerte.254. **Competing consumers.** 4-8 workers en parallèle pour absorber les pics.265. **Lifecycle tracking.** Logs structurés, métriques (latence, taux erreur, DLQ depth) et alertes.2728## Frameworks recommandés2930| Stack | Framework | Notes |31|-------|-----------|-------|32| Symfony | **Symfony Messenger** | Transport AMQP, Redis, Doctrine ; supports Stamps |33| Laravel | **Laravel Queue** (Horizon en prod) | Backed by Redis ou SQS ; supervision native |34| PHP framework-agnostic | **Ecotone** | DDD, sagas, scheduler, messaging unifié |35| Node.js | BullMQ ou RabbitMQ | Redis-backed avec dashboard |3637## Pattern minimal (Symfony Messenger)3839```php40// Message (immutable DTO)41final class SendWelcomeEmail42{43 public function __construct(public readonly string $userId) {}44}4546// Handler47final class SendWelcomeEmailHandler48{49 public function __invoke(SendWelcomeEmail $message): void50 {51 // Idempotency check52 if ($this->emailLog->wasSent($message->userId, 'welcome')) {53 return;54 }55 $this->mailer->sendWelcome($message->userId);56 $this->emailLog->record($message->userId, 'welcome');57 }58}5960// Dispatch (controller)61$this->bus->dispatch(new SendWelcomeEmail($user->id));62```6364## Anti-patterns critiques6566- ❌ Mettre une opération idempotente directement dans le handler sans clé d'idempotency (replay = double effet).67- ❌ `try { ... } catch (\Throwable) { /* swallow */ }` dans un handler → le message est marqué traité alors qu'il a échoué.68- ❌ Stocker la payload complète d'un email/PDF dans le message → préférer un ID + lookup, sinon RabbitMQ explose.69- ❌ Pas de circuit breaker autour des appels tiers : un provider down fait monter la DLQ en flèche.7071## Pour aller plus loin7273> Détails complets, patterns Laravel/Ecotone, exemples de configuration, observabilité OpenTelemetry, lifecycle events, checklists par phase : voir `@.claude/skills/async/REFERENCE.md`.