Symfony HttpClient: Der richtige Weg, externe APIs aufzurufen

Die meisten Symfony-HttpClient-Tutorials hören bei $client->request('GET', $url) auf. Das funktioniert gut, bis die externe API, von der Sie abhängen, einen schlechten Tag hat. Dann wartet ein Checkout-Request 30 Sekunden auf einen Zahlungsanbieter, der nie antworten wird, PHP-FPM-Worker stauen sich dahinter, und ein Service, den Sie nicht betreiben, reißt einen mit herunter, den Sie betreiben.

Die Komponente selbst ist solide. Was eine Demo von einer Produktionsintegration trennt, ist alles um den Request herum: wie Sie Clients scopen, wie Sie retrien, wie lange Sie zu warten bereit sind und wie Sie das Ganze testen und beobachten. Dieser Beitrag geht das Setup durch, das wir für SaaS-Projekte unserer Kunden verwenden, und endet mit einem ausgearbeiteten Beispiel eines typisierten Payment-API-Clients.

Scoped Clients: ein Service pro externer API

Der erste Fehler zeigt sich früh: das generische HttpClientInterface überall zu injizieren und Base-URL und Header an jeder Aufrufstelle zu wiederholen. Sechs Monate später rotiert der API-Key, und Sie greppen die Codebasis nach Header-Namen.

Symfony hat eine eingebaute Antwort, den Scoped Client. Sie konfigurieren Base-URI, Standard-Header und Retry-Verhalten einmal:

# config/packages/framework.yaml
framework:
  http_client:
    scoped_clients:
      payment.client:
        base_uri: 'https://api.payment-provider.com/v1/'
        headers:
          Authorization: 'Bearer %env(PAYMENT_API_KEY)%'
        timeout: 5
        max_duration: 10

Dann wickeln Sie den Scoped Client in eine typisierte Service-Klasse, sodass der Rest Ihrer Anwendung HTTP gar nicht mehr sieht:

final class PaymentApiClient
{
    public function __construct(
        private HttpClientInterface $paymentClient,
    ) {}

    public function createCharge(ChargeRequest $request): Charge
    {
        $response = $this->paymentClient->request('POST', 'charges', [
            'json' => $request->toArray(),
        ]);

        return Charge::fromArray($response->toArray());
    }
}

Controller und Handler hängen von PaymentApiClient ab und bekommen ein Charge-Objekt zurück. Die JSON-Struktur des Anbieters, seine Fehlercodes und sein Auth-Schema bleiben in einer Klasse. Wenn der Anbieter seine API ändert, haben Sie genau eine Stelle zum Aktualisieren und eine Klasse, die Tests abdecken müssen.

Retries und Rate Limits, ohne die API zu bombardieren

Netzwerke fallen aus, und die meisten transienten Fehler lösen sich innerhalb von Sekunden. Ein Retry mit exponentiellem Backoff macht aus einem Aussetzer ein Nicht-Ereignis. Symfony liefert das als Konfiguration:

framework:
  http_client:
    scoped_clients:
      payment.client:
        retry_failed:
          max_retries: 3
          delay: 500
          multiplier: 2
          jitter: 0.1
          http_codes: [423, 425, 429, 500, 502, 503, 504]

Drei Details zählen mehr als die Konfigurationssyntax.

Erstens: Wiederholen Sie nur, was sicher ist. Ein GET lässt sich blind wiederholen. Ein POST, der eine Abbuchung erzeugt, nicht, außer die API unterstützt Idempotency Keys (dazu unten mehr). Symfonys Standard-GenericRetryStrategy wiederholt POST genau aus diesem Grund nur für eine schmale Menge von Statuscodes.

Zweitens: Respektieren Sie Retry-After. Wenn eine API 429 zurückgibt, sagt sie Ihnen meist, wann Sie wiederkommen sollen. Die eingebaute Strategie honoriert diesen Header, eine rate-limitierte Antwort wartet also die angeforderte Zeit statt Ihres konfigurierten Delays. Wenn Sie ein eigenes RetryStrategyInterface schreiben, behalten Sie dieses Verhalten bei. Es zu ignorieren bringt Ihrem API-Key härteres Throttling oder einen Bann ein.

Drittens: Fügen Sie Jitter hinzu. Wenn 50 Worker im selben Moment scheitern und alle nach exakt 500 ms erneut anfragen, empfängt die API eine synchronisierte Welle und kippt erneut. Jitter verteilt die Herde.

Für eine API mit hartem Fehlermodus können Sie einen Schritt weitergehen und Calls in einen Circuit Breaker wickeln: Nach N aufeinanderfolgenden Fehlern hören Sie für ein Cooldown-Fenster auf anzufragen und schlagen schnell fehl. Einen kleinen können Sie auf Symfonys Cache aufbauen, oder Sie nutzen die RateLimiter-Komponente, um ausgehende Request-Raten pro Anbieter zu deckeln. Der Punkt ist: Nach dem dritten Timeout in Folge sollte der vierte Request nicht fünf Sekunden warten, um zu erfahren, was Sie schon wissen.

Behandeln Sie Timeouts als Latenzbudget

Das Standard-timeout in Symfony deckt die Leerlaufzeit zwischen Chunks ab, und max_duration begrenzt den gesamten Request. Sie wollen beides, und Sie wollen beides niedrig.

Rechnen Sie rückwärts von Ihrem eigenen SLA. Wenn Ihr Endpoint in zwei Sekunden antworten muss und der externe Call einer von mehreren Schritten ist, bekommt dieser Call ein Budget von ein paar Hundert Millisekunden, nicht die 30 Sekunden Default, die Ihre HTTP-Schicht erlauben mag. Eine externe API, die langsamer ist als Ihr Budget, ist faktisch down, und sie früh so zu behandeln hält Ihren Worker-Pool am Leben.

Async-Responses helfen hier ebenfalls. HttpClient-Requests sind lazy: Der Request startet beim Aufruf von request(), blockiert aber erst, wenn Sie die Response lesen. Wenn Sie drei unabhängige APIs brauchen, feuern Sie erst alle drei ab und lesen dann die Ergebnisse. Die gesamte Wartezeit wird zum langsamsten Call statt zur Summe aller.

Responses streamen statt puffern

$response->toArray() puffert den ganzen Body im Speicher. Bei einem 200-KB-JSON-Payload interessiert das niemanden. Bei einem 2-GB-Export oder einem Server-Sent-Event-Stream ist Puffern entweder ein Out-of-Memory-Fehler oder schlicht falsch.

Die Methode stream() liefert Ihnen Chunks, sobald sie ankommen:

$response = $client->request('GET', 'exports/12345');

foreach ($client->stream($response) as $chunk) {
    fwrite($localFile, $chunk->getContent());
}

Für SSE-Endpoints, die die meisten LLM-APIs verwenden, bietet Symfony den EventSourceHttpClient. Er übernimmt das text/event-stream-Framing und die Reconnection mit Last-Event-ID, Sie konsumieren also typisierte ServerSentEvent-Objekte, statt selbst data:-Zeilen zu parsen. Wenn Sie OpenAI- oder Anthropic-Streaming in ein Symfony-Backend integrieren, ist das der Teil, den die meisten Eigenbauten falsch machen.

Symfony HttpClient testen, ohne das Netzwerk zu berühren

Integrationstests, die echte externe APIs treffen, sind langsam und flaky, und bei kostenpflichtigen Anbietern können sie echtes Geld kosten. MockHttpClient ersetzt den Transport und behält Ihren echten Client-Code, Serializer und Ihr Error Handling in der Schleife:

$mock = new MockHttpClient([
    new MockResponse('{"id":"ch_123","status":"succeeded"}', [
        'http_code' => 200,
    ]),
    new MockResponse('', ['http_code' => 429, 'response_headers' => ['retry-after' => '2']]),
]);

$apiClient = new PaymentApiClient($mock);

Reihen Sie Responses in der richtigen Reihenfolge auf, und Sie testen den Happy Path, den Rate-Limit-Pfad und den Pfad mit kaputtem JSON deterministisch. Eine Callable-Factory statt eines festen Arrays lässt Sie Assertions auf den ausgehenden Request schreiben: korrekte URL, korrekte Header, korrekter Body. Das fängt die Klasse von Bugs, bei der ein Refactoring still den Idempotency-Header verliert, was kein Happy-Path-Test bemerken würde.

Eine Gewohnheit, die sich lohnt: Zeichnen Sie einmal eine Handvoll echter Responses aus der Sandbox des Anbieters auf, speichern Sie sie als Fixtures und füttern Sie damit den MockHttpClient. Ihre Tests prüfen Verhalten dann gegen Payloads, die der Anbieter tatsächlich sendet.

Ausgehende Calls mit OpenTelemetry tracen

Wenn ein Request langsam ist, lautet die erste Frage, wo die Zeit geblieben ist. Sind externe Calls in Ihren Traces unsichtbar, wird die Antwort zum Rätselraten.

Die OpenTelemetry-PHP-Instrumentierung für Symfonys HttpClient dekoriert den Client und emittiert einen Span pro ausgehendem Request, mit URL, Methode, Statuscode und Dauer, und sie propagiert den traceparent-Header, sodass der Trace in jedem Downstream-Service weiterläuft, der mitmacht. Einmal verdrahtet, zeigt Ihr Trace für einen langsamen Checkout einen 1,8-Sekunden-Span namens POST api.payment-provider.com, und die Debatte ist beendet.

Wenn Sie kein OpenTelemetry betreiben, loggen Sie ausgehende Calls mindestens mit Dauer und Status über einen Decorator um das HttpClientInterface. Zehn Zeilen Code, und sie zahlen sich beim ersten Incident aus.

Ein ausgearbeitetes Beispiel: ein typisierter Payment-Client

So fügen sich die Teile für eine API im Stripe-Stil zusammen, bei der Retries nur deshalb sicher sind, weil jeder Write einen Idempotency Key trägt:

final class PaymentApiClient
{
    public function __construct(
        private HttpClientInterface $paymentClient,
        private LoggerInterface $logger,
    ) {}

    public function createCharge(ChargeRequest $request): Charge
    {
        $start = microtime(true);

        $response = $this->paymentClient->request('POST', 'charges', [
            'json' => $request->toArray(),
            'headers' => [
                'Idempotency-Key' => $request->idempotencyKey,
            ],
        ]);

        try {
            $data = $response->toArray();
        } catch (ClientExceptionInterface $e) {
            throw PaymentDeclined::fromResponse($e->getResponse());
        } finally {
            $this->logger->info('payment_api.create_charge', [
                'status' => $response->getStatusCode(),
                'duration_ms' => (int) ((microtime(true) - $start) * 1000),
            ]);
        }

        return Charge::fromArray($data);
    }
}

Der Idempotency Key wird einmal pro Geschäftsvorgang erzeugt, zum Beispiel aus der Bestell-ID, und mit der Bestellung gespeichert. Wenn der Request in ein Timeout läuft und die Retry-Schicht ihn erneut sendet, erkennt der Anbieter den Key und liefert das ursprüngliche Ergebnis, statt den Kunden doppelt zu belasten. Dieser eine Header macht retry_failed für POST-Requests sicher aktivierbar.

Die Scoped-Client-Konfiguration von vorhin liefert Base-URI, Auth-Header, Timeouts und Retry-Strategie. Die Klasse oben bleibt klein, weil das Framework dieses Gewicht trägt.

Wo das in echten Codebasen üblicherweise schiefgeht

In Code-Audits finden wir immer wieder dieselben drei Probleme: keine expliziten Timeouts, die App erbt also, was auch immer der Transport als Default mitbringt; Retries auf nicht-idempotenten Writes, die unter Last doppelte Seiteneffekte verursachen; und null Sichtbarkeit auf ausgehende Latenz, externe APIs werden also nach Bauchgefühl beschuldigt oder entlastet. Nichts davon ist schwer zu beheben. Es ist nur leicht zu überspringen, solange die Integration in Staging funktioniert.

Wenn Sie ein Produkt bauen, bei dem externe APIs auf dem kritischen Pfad sitzen, Payments, KYC-Anbieter, LLM-Backends, lohnt es sich, diese Schicht vor dem ersten Incident richtig zu bauen statt danach. Das ist die Art von Grundlagenarbeit, die wir in Projekten der individuellen Softwareentwicklung leisten, und sie nachträglich in eine bestehende Codebasis einzuziehen ist ein häufiger Teil der Legacy-Modernisierung.

Wenn Sie ein zweites Paar Augen für Ihre eigene Integrationsschicht wollen, schreiben Sie an hello@wolf-tech.io oder besuchen Sie wolf-tech.io. Wir lesen jede Nachricht.