UseCase dans le développement backend : structuration de la logique métier

Patron UseCase : Structurer la logique métier en backend

Le UseCase est un patron architectural pour définir les scénarios métier dans les applications. Il organise le code autour d'actions système spécifiques — comme passer une commande ou s'inscrire — plutôt que d'opérations techniques abstraites. Cette approche améliore la lisibilité, simplifie les tests et permet d'évoluer efficacement les projets, surtout dans les systèmes backend complexes.

Qu'est-ce que le UseCase et pourquoi l'utiliser ?

Le UseCase représente un scénario métier complet au niveau de la couche applicative. Il orchestre une séquence d'étapes, en déléguant les règles métier aux services de domaine et aux entités. Par exemple, au lieu d'une opération bas niveau « écrire en base de données », un UseCase décrit « l'utilisateur passe une commande ». Cela évite que la logique métier ne se disperse dans les contrôleurs et services au fur et à mesure que le projet grandit. Sans frontières claires des scénarios, le code devient difficile à comprendre et à maintenir.

Avantages clés du UseCase :

• Structure claire : Le système est défini par des capacités métier explicites, pas par des abstractions vagues comme Service ou Manager.
• Meilleure lisibilité : L'architecture reflète la logique métier, facilitant la réponse à « Que peut faire cette app ? ».
• Tests plus simples : Les tests d'intégration au niveau scénario vérifient le parcours utilisateur complet sans casser les processus métier.

Limites et bonnes pratiques

Évitez d'appeler un UseCase depuis un autre pour prévenir les dépendances cachées et les transformer en blocs de logique réutilisables. Dans les scénarios complexes, c'est acceptable s'il n'y a pas de cycles et que les scénarios restent explicites. Pour la logique réutilisable, extrayez-la dans des services dédiés ou des composants de domaine utilisables dans plusieurs UseCases.

Où invoquer le UseCase :

• Contrôleur
• Commande console
• Job
• Écouteur d'événements

Le UseCase sert de point d'entrée à la logique métier de votre app, en médiant les interactions externes avec le système.

Pourquoi les services seuls ne suffisent pas

Les services conviennent aux projets simples, mais à mesure que la logique métier grossit, des problèmes surgissent. Ce qui commence par un simple « sauvegarder en base » pour créer une commande enfle avec des vérifications de stock, l'application de remises, la déduction de soldes et l'envoi de notifications. Cela crée des god objects — des classes gonflées de dépendances, méthodes et effets de bord — rendant le code illisible et difficile à tester.

Le UseCase suit une règle simple : un UseCase = un processus métier. La logique dupliquée va dans des services partagés ou composants de domaine, gardant le code gérable malgré l'augmentation de complexité.

Structure UseCase en PHP et Laravel

Un UseCase typique comporte trois parties :

• Handler : Orchestre les étapes et conditions du scénario, sans logique métier de domaine.
• DataInput : Objet de données d'entrée sans logique — juste des données typées, de préférence immuables.
• DataOutput : Objet résultat définissant un contrat clair (ex. : DTO).

Exemple : Créer une commande :

class StoreOrderDataInput
{
    public function __construct(
        public readonly int $userId,
        public readonly array $items,
    ) {}
}

class StoreOrderDataOutput
{
    public function __construct(
        public readonly int $orderId,
        public readonly string $status,
    ) {}
}

class StoreOrderHandler
{
    public function __construct(
        private OrderRepository $orders
    ) {}

    public function handle(StoreOrderDataInput $input): StoreOrderDataOutput
    {
        $order = new Order(
            userId: $input->userId,
        );

        $orderSaved = $this->orders->save($order);

        return new StoreOrderDataOutput(
            orderId: $orderSaved->id,
            status: $orderSaved->status
        );
    }
}

Organisation et tests des UseCases dans les projets

Dans Laravel, stockez les UseCases dans une structure comme app/UseCases/V1 avec versionnage pour des changements de contrat sécurisés. Les sous-répertoires répondent à « Que peut faire le système ? » — par ex. StoreOrder, CancelOrder, RegisterUser. Cela reflète les capacités métier, pas les détails techniques.

Tester les UseCases est simple avec des tests d'intégration au niveau scénario. Exemple de test pour StoreOrderHandler :

use Tests\TestCase;
use Illuminate\Foundation\Testing\RefreshDatabase;

class StoreOrderFeatureTest extends TestCase
{
    use RefreshDatabase;

    public function testUserCanCreateOrder(): void
    {
        $user = User::factory()->create();

        $payload = [
            'items' => [
                ['id' => 10, 'qty' => 2],
                ['id' => 15, 'qty' => 1],
            ],
        ];

        $response = $this->actingAs($user)
            ->postJson('/api/orders', $payload);

        $response->assertStatus(200);
        $response->assertJsonStructure([
            'orderId',
            'status'
        ]);
        $this->assertDatabaseHas('orders', [
            'user_id' => $user->id
        ]);
    }
}

Points clés à retenir

• UseCase définit les scénarios métier, pas les ops techniques, pour une structure d'app plus propre.
• Il résout la dispersion de logique dans les gros projets, en gardant le code maintenable.
• Un UseCase = un processus métier, avec logique partagée dans les services.
• Les tests sont simplifiés via des tests d'intégration couvrant les scénarios complets.
• La structure du projet reflète les fonctionnalités métier, accélérant l'onboarding.

— Editorial Team