Utiliser HeaderBag de Symfony en tant que service : une superpuissance de débogage dans les contextes API

Introduction

Créer des API signifie gérer des couches complexes de cache, de middleware et d'optimisation des performances. Bien que ces couches soient utiles à la production, elles peuvent également masquer le flux réel de données. Comment savoir si un cache a été atteint ou manqué dans une requête particulière ? Un moyen simple consiste à ajouter des en-têtes personnalisés à la réponse, vous donnant ainsi des informations précieuses.

Dans cet article, je vais vous montrer comment le HeaderBag de Symfony, lorsqu'il est enregistré en tant que service, peut être un outil puissant pour déboguer les API en production. En attachant des en-têtes personnalisés qui indiquent les succès et les échecs du cache, vous pouvez comprendre instantanément ce qui se passe dans votre API sans ajouter de journalisation inutile ni interrompre le flux d'exécution.

Pourquoi HeaderBag ?

Le HeaderBag de Symfony fait partie du composant HttpFoundation et est utilisé en interne par les objets de requête et de réponse de Symfony. Il fournit un moyen structuré d'interagir avec les en-têtes HTTP, vous permettant d'ajouter, de modifier et de récupérer des en-têtes de manière propre et orientée objet. Cela en fait la solution idéale pour gérer les en-têtes personnalisés lors de l'exécution de l'API, en particulier dans les scénarios de débogage.

Mais il y a plus : vous pouvez enregistrer HeaderBag en tant que service et l'utiliser dans votre application, en gardant votre code propre et votre débogage cohérent.

Étape 1 : enregistrement de HeaderBag en tant que service

Vous pouvez facilement enregistrer HeaderBag en tant que service de deux manières.

Option 1 : étendre HeaderBag dans un service personnalisé

Vous pouvez créer un service personnalisé qui étend HeaderBag puis l'utiliser dans votre application :

<?php
declare(strict_types=1);

namespace App\Service;

use Symfony\Component\HttpFoundation\HeaderBag;

class ResponseHeaderService extends HeaderBag
{
}

Option 2 : Définissez-le dans services.yaml

Vous pouvez également enregistrer directement HeaderBag en tant que service dans services.yaml :

my.awesome.headerbag:
    class: 'Symfony\Component\HttpFoundation\HeaderBag'

Les deux méthodes atteignent le même objectif : permettre à HeaderBag d'être disponible en tant que service dans toute votre application.

Étape 2 : ajout d'en-têtes personnalisés via un abonné à l'événement

Une fois que vous avez enregistré HeaderBag en tant que service, l'étape suivante consiste à le faire interagir avec l'objet de réponse de Symfony. C’est là que les abonnés aux événements entrent en jeu. En vous abonnant à l'événement KernelEvents::RESPONSE, vous pouvez injecter des en-têtes personnalisés dans la réponse avant qu'elle ne soit renvoyée au client.

Voici un exemple de création d'un abonné à un événement qui ajoute des en-têtes stockés dans HeaderBag :

<?php
declare(strict_types=1);

namespace App\EventSubscriber;

use App\Service\ResponseHeaderService;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\HttpKernel\Event\ResponseEvent;
use Symfony\Component\HttpKernel\KernelEvents;

readonly class ResponseHeadersEventSubscriber implements EventSubscriberInterface
{
    public function __construct(
        private ResponseHeaderService $responseHeaderService
    )
    {}

    public static function getSubscribedEvents(): array
    {
        return [
            KernelEvents::RESPONSE => 'onKernelResponse'
        ];
    }

    public function onKernelResponse(ResponseEvent $event): void
    {
        $response = $event->getResponse();

        $response->headers->add($this->responseHeaderService->all());
    }
}

Si vous préférez enregistrer votre HeaderBag en tant que service dans services.yaml, vous devrez utiliser l'attribut Autowire :

<?php
declare(strict_types=1);

namespace App\Service;

use Symfony\Component\HttpFoundation\HeaderBag;

class ResponseHeaderService extends HeaderBag
{
}

Étape 3 : implémentation des diagnostics du cache

Vient maintenant la partie amusante : utiliser ce service pour suivre les succès et les échecs du cache. Voici un exemple de service qui calcule un résultat, vérifie les accès au cache et ajoute un en-tête personnalisé à la réponse indiquant si le cache a été atteint ou manqué :

my.awesome.headerbag:
    class: 'Symfony\Component\HttpFoundation\HeaderBag'

Dans cet exemple, chaque fois que UniverseService interagit avec le cache, il définit un en-tête X-Universe-Cache, indiquant si le cache a été touché ou manqué. Cet en-tête est ensuite automatiquement ajouté à la réponse par l'abonné à l'événement. Le résultat ? Chaque réponse de l'API contiendra un en-tête simple et informatif qui vous donnera un aperçu immédiat de l'utilisation du cache.

Votre réponse pourrait ressembler à ceci :

<?php
declare(strict_types=1);

namespace App\EventSubscriber;

use App\Service\ResponseHeaderService;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\HttpKernel\Event\ResponseEvent;
use Symfony\Component\HttpKernel\KernelEvents;

readonly class ResponseHeadersEventSubscriber implements EventSubscriberInterface
{
    public function __construct(
        private ResponseHeaderService $responseHeaderService
    )
    {}

    public static function getSubscribedEvents(): array
    {
        return [
            KernelEvents::RESPONSE => 'onKernelResponse'
        ];
    }

    public function onKernelResponse(ResponseEvent $event): void
    {
        $response = $event->getResponse();

        $response->headers->add($this->responseHeaderService->all());
    }
}

Conclusion

L'utilisation de HeaderBag de Symfony en tant que service est un outil puissant dans le développement d'API, en particulier lorsque vous travaillez dans des environnements de production avec des couches de mise en cache complexes. En ajoutant des en-têtes personnalisés à vos réponses API, vous pouvez déterminer rapidement les statuts du cache, améliorant ainsi vos processus de débogage et d'optimisation.

La prochaine fois que vous vous demanderez si une requête particulière a été mise en cache, jetez un œil aux en-têtes que vous avez ajoutés : vous aurez votre réponse ici !

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!