← C++

C++ · 20 / 24

Asynchrone HTTP-Anfragen mit Abbruch und Zeitlimit

Du lädst Aufträge ohne blockierende Oberfläche und behandelst Fehler, Abbruch, Größenbegrenzung und veraltete Antworten.

  • Groß
  • Anspruchsvoll
  • 120 min

Voraussetzungen: Deine erste Qt-Oberfläche mit Signals und Slots, Ownership, Lebensdauer und Move-Semantik, Fehlerbehandlung und starke Ausnahmegarantie

In diesem Tutorial
  1. Einen lokalen Dienst starten
  2. Ergebnisse über Signale erhalten
  3. Anfragen besitzen und begrenzen
  4. Transport und Nutzdaten prüfen
  5. Antworten reproduzierbar steuern
  6. Fehlerfälle vollständig beobachten
  7. Doppelte Aktualisierungen vermeiden
  8. Übung und Lösung
  9. Projektbezug und Quellen

Lernpaket herunterladen

Einrichtung und Prüfstand

GCC mit C++20, CMake ab 3.25, CTest und Python 3. Qt 6.8 mit Core, Widgets und Test. Zusätzlich Qt Network. Setze CMAKE_PREFIX_PATH auf deinen Qt-Installationsordner, falls Qt nicht automatisch gefunden wird. Lokal geprüft mit Qt 6.8.3. Entpacke das ZIP in einen neuen Ordner. python3 run_checks.py prüft Beispiel und Lösung in einer temporären Kopie und erhält deine Dateien. Für einen eigenen Build führe python3 verify.py aus. Danach liegt das Demo unter build/order_lab. Die Qt-Demos verwenden englische Beschriftungen. Automatische Widgettests nutzen standardmäßig offscreen. Starte die sichtbare Demo in einer Desktop-Sitzung ohne QT_QPA_PLATFORM=offscreen. Native Windows-Ausführung ist nicht verifiziert.

Geprüft am 21.10.2026 unter Linux x86_64. Lokale HTTP-Verbindungen mit Erfolg, HTTP- und JSON-Fehlern, Größenlimit, Timeout, Abbruch und tatsächlich gestarteter ersetzter Anfrage. Die Lösung prüft Doppelklickschutz. Keine externe TLS- oder Produktionsdienst-Abnahme.

Ein Netzwerkaufruf kann scheitern, langsam sein oder erst antworten, nachdem bereits eine neue Anfrage gestartet wurde. OrderDownload besitzt deshalb genau eine aktive Anfrage, eine Gesamtfrist und eine laufende Generation. Nur die aktuelle Generation darf ein Ergebnis veröffentlichen. Der mitgelieferte lokale Server macht alle wichtigen Zustände ohne fremden Dienst nachvollziehbar.

Paketinhalt und einzelne Dateien

01Einen lokalen Dienst starten

Starte python3 demo_server.py in einem Terminal. Der Server bindet ausschließlich an 127.0.0.1 und liefert künstliche Daten unter /orders. /error liefert HTTP 500, /invalid ungültiges JSON und /slow antwortet verzögert. Der Server ist ein Lernwerkzeug ohne Anmeldung und kein veröffentlichter Produktionsdienst.

demo_server.py · pythonDatei öffnen
"""Local synthetic order endpoint. Run with python3 demo_server.py."""

import argparse
import json
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from time import sleep

DOCUMENT = {
    "format": "appfabrik-order-lab",
    "version": 2,
    "orders": [
        {"id": 10, "title": "Deliver motors", "priority": 2, "status": "open"},
        {"id": 20, "title": "Move pallets", "priority": 0, "status": "done"},
    ],
}


class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        if self.path == "/slow":
            sleep(5)
        status = 500 if self.path == "/error" else 200
        body = (
            b"invalid JSON"
            if self.path == "/invalid"
            else json.dumps(DOCUMENT).encode()
        )
        self.send_response(status)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        try:
            self.wfile.write(body)
        except (BrokenPipeError, ConnectionResetError):
            pass


if __name__ == "__main__":
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--port", type=int, default=8765)
    args = parser.parse_args()
    print(f"Synthetic orders at http://127.0.0.1:{args.port}/orders", flush=True)
    ThreadingHTTPServer(("127.0.0.1", args.port), Handler).serve_forever()
Erwartetes Ergebnis

Das Terminal zeigt die lokale Adresse auf Port 8765.

02Ergebnisse über Signale erhalten

Baue mit python3 verify.py und starte ./build/order_lab. Das Programm verbindet ready und failed vor dem eigentlichen Start. QTimer::singleShot verschiebt den Start in die Ereignisschleife, damit auch eine sofortige Ablehnung den Prozess zuverlässig beendet. Eine alternative URL kann als erstes Argument übergeben werden.

main.cpp · cppDatei öffnen
#include "download.hpp"
#include <QCoreApplication>
#include <iostream>
int main(int argc, char **argv) {
  QCoreApplication app(argc, argv);
  orders::OrderDownload loader;
  QObject::connect(&loader, &orders::OrderDownload::ready, &app,
                   [&app](const QByteArray &bytes) {
                     std::cout << bytes.toStdString() << '\n';
                     app.exit(0);
                   });
  QObject::connect(&loader, &orders::OrderDownload::failed, &app,
                   [&app](const QString &error) {
                     std::cerr << error.toStdString() << '\n';
                     app.exit(1);
                   });
  QTimer::singleShot(0, &app, [&] {
    loader.load(QUrl(argc > 1 ? argv[1] : "http://127.0.0.1:8765/orders"));
  });
  return app.exec();
}
Erwartetes Ergebnis

Bei /orders erscheint das JSON. Bei /error beendet sich das Programm mit Fehlerstatus.

03Anfragen besitzen und begrenzen

QNetworkAccessManager lebt im selben Qt-Thread wie der Loader. Jede Antwort wird nach Abschluss mit deleteLater freigegeben. Ein eigener QTimer begrenzt die gesamte Anfrage auf standardmäßig drei Sekunden. Der Empfang ist auf 256 KiB begrenzt. Abbruch und Timeout räumen dieselbe aktive Anfrage auf und erzeugen jeweils nur eine Fehlermeldung.

download.hpp · cppDatei öffnen
#pragma once
#include "json_orders.hpp"
#include <QNetworkAccessManager>
#include <QNetworkReply>
#include <QPointer>
#include <QTimer>

namespace orders {
class OrderDownload final : public QObject {
  Q_OBJECT
  QNetworkAccessManager manager_{this};
  QPointer<QNetworkReply> active_;
  QTimer deadline_{this};
  QByteArray bytes_;
  quint64 generation_{0};
  void discard() {
    ++generation_;
    deadline_.stop();
    if (active_) {
      auto reply = active_;
      active_.clear();
      disconnect(reply, nullptr, this, nullptr);
      reply->abort();
      reply->deleteLater();
    }
    bytes_.clear();
  }
  void fail(const QString &message) {
    discard();
    emit busyChanged(false);
    emit failed(message);
  }
  bool collect(QNetworkReply *reply) {
    bytes_ += reply->read(maximumDocumentBytes + 1 - bytes_.size());
    if (bytes_.size() > maximumDocumentBytes) {
      fail("Response exceeds 256 KiB");
      return false;
    }
    return true;
  }

public:
  explicit OrderDownload(QObject *parent = nullptr) : QObject(parent) {
    deadline_.setSingleShot(true);
    connect(&deadline_, &QTimer::timeout, this,
            [this] { fail("Request timed out"); });
  }
  ~OrderDownload() override { discard(); }
  bool busy() const { return !active_.isNull(); }
  void cancel() {
    if (busy())
      fail("Request cancelled");
  }
  void load(const QUrl &url, int timeoutMs = 3000) {
    discard();
    if (!url.isValid() || url.host().isEmpty() || !url.userInfo().isEmpty() ||
        (url.scheme() != "http" && url.scheme() != "https") || timeoutMs < 1) {
      fail(
          "Expected an HTTP(S) URL without credentials and a positive timeout");
      return;
    }
    QNetworkRequest request(url);
    request.setAttribute(QNetworkRequest::RedirectPolicyAttribute,
                         QNetworkRequest::NoLessSafeRedirectPolicy);
    active_ = manager_.get(request);
    active_->setReadBufferSize(maximumDocumentBytes + 1);
    auto *reply = active_.data();
    const auto generation = generation_;
    connect(reply, &QIODevice::readyRead, this, [this, reply, generation] {
      if (generation == generation_)
        collect(reply);
    });
    connect(reply, &QNetworkReply::finished, this, [this, reply, generation] {
      if (generation != generation_) {
        reply->deleteLater();
        return;
      }
      if (!collect(reply))
        return;
      const auto status =
          reply->attribute(QNetworkRequest::HttpStatusCodeAttribute).toInt();
      if (reply->error() != QNetworkReply::NoError || status < 200 ||
          status >= 300) {
        fail(QString("HTTP %1: %2").arg(status).arg(reply->errorString()));
        return;
      }
      auto decoded = decode(bytes_);
      if (!succeeded(decoded)) {
        fail(QString::fromStdString(std::get<Error>(decoded).message));
        return;
      }
      auto completed = bytes_;
      discard();
      emit busyChanged(false);
      emit ready(completed);
    });
    deadline_.start(timeoutMs);
    emit busyChanged(true);
  }
signals:
  void ready(const QByteArray &document);
  void failed(const QString &message);
  void busyChanged(bool busy);
};
} // namespace orders
Erwartetes Ergebnis

Eine langsame Antwort wird abgebrochen. Der Loader bleibt anschließend erneut verwendbar.

04Transport und Nutzdaten prüfen

Ein HTTP-Status im 2xx-Bereich allein genügt nicht. Die Antwort muss ein gültiges Order-Lab-Dokument enthalten. Der Decoder prüft Formatversion, Datentypen, Grenzen und eindeutige IDs. Das Lernformat wird in Tutorial 22 genauer erklärt. SSL-Fehler werden nicht ignoriert. Weiterleitungen dürfen HTTPS nicht auf HTTP herabstufen.

json_orders.hpp · cppDatei öffnen
#pragma once
#include "order.hpp"
#include <QFile>
#include <QJsonArray>
#include <QJsonDocument>
#include <QJsonObject>
#include <QSaveFile>
#include <cmath>

namespace orders {
inline constexpr int maximumDocumentBytes = 262144;
inline bool integer(const QJsonValue &value, int minimum, int maximum) {
  if (!value.isDouble())
    return false;
  double number = value.toDouble();
  return std::isfinite(number) && std::floor(number) == number &&
         number >= minimum && number <= maximum;
}
inline Result<std::vector<Order>> decode(const QByteArray &bytes) {
  if (bytes.size() > maximumDocumentBytes)
    return Error{ErrorCode::invalid, "Document exceeds 256 KiB"};
  QJsonParseError parse;
  auto document = QJsonDocument::fromJson(bytes, &parse);
  if (parse.error != QJsonParseError::NoError || !document.isObject())
    return Error{ErrorCode::invalid, "Expected a JSON object"};
  auto root = document.object();
  if (root.value("format") != "appfabrik-order-lab" ||
      !integer(root.value("version"), 1, 2))
    return Error{ErrorCode::unsupported,
                 "Expected order-lab format version 1 or 2"};
  if (!root.value("orders").isArray() ||
      root.value("orders").toArray().size() > 1000)
    return Error{ErrorCode::invalid,
                 "Expected an array of at most 1000 orders"};
  std::vector<Order> result;
  for (const auto &value : root.value("orders").toArray()) {
    if (!value.isObject())
      return Error{ErrorCode::invalid, "Order must be an object"};
    auto object = value.toObject();
    if (!integer(object.value("id"), 1, 1000000) ||
        !object.value("title").isString())
      return Error{ErrorCode::invalid, "Invalid ID or title"};
    Order order{object.value("id").toInt(),
                object.value("title").toString().toStdString()};
    if (root.value("version").toInt() == 2) {
      if (!integer(object.value("priority"), 0, 2) ||
          (object.value("status") != "open" &&
           object.value("status") != "done"))
        return Error{ErrorCode::invalid, "Invalid priority or status"};
      order.priority = object.value("priority").toInt();
      order.status =
          object.value("status") == "done" ? Status::done : Status::open;
    }
    result.push_back(std::move(order));
  }
  auto valid = validateBatch(result);
  if (!succeeded(valid))
    return std::get<Error>(valid);
  return result;
}
inline Result<QByteArray> encode(std::span<const Order> batch) {
  auto valid = validateBatch(batch);
  if (!succeeded(valid))
    return std::get<Error>(valid);
  QJsonArray items;
  for (const auto &order : batch)
    items.append(QJsonObject{
        {"id", order.id},
        {"title", QString::fromStdString(order.title)},
        {"priority", order.priority},
        {"status", order.status == Status::open ? "open" : "done"}});
  auto bytes = QJsonDocument(QJsonObject{{"format", "appfabrik-order-lab"},
                                         {"version", 2},
                                         {"orders", items}})
                   .toJson(QJsonDocument::Compact);
  if (bytes.size() > maximumDocumentBytes)
    return Error{ErrorCode::invalid, "Encoded document exceeds 256 KiB"};
  return bytes;
}
inline Result<std::vector<Order>> loadFile(const QString &path) {
  QFile file(path);
  if (!file.open(QIODevice::ReadOnly))
    return Error{ErrorCode::storage, file.errorString().toStdString()};
  auto bytes = file.read(maximumDocumentBytes + 1);
  if (file.error() != QFileDevice::NoError)
    return Error{ErrorCode::storage, file.errorString().toStdString()};
  return decode(bytes);
}
inline Result<Done> saveFile(const QString &path,
                             std::span<const Order> batch) {
  auto encoded = encode(batch);
  if (!succeeded(encoded))
    return std::get<Error>(encoded);
  const auto &bytes = std::get<QByteArray>(encoded);
  QSaveFile file(path);
  file.setDirectWriteFallback(false);
  if (!file.open(QIODevice::WriteOnly) || file.write(bytes) != bytes.size() ||
      !file.commit())
    return Error{ErrorCode::storage, file.errorString().toStdString()};
  return Done{};
}
} // namespace orders
Erwartetes Ergebnis

Ungültiges JSON löst failed aus und erreicht kein ready-Signal.

05Antworten reproduzierbar steuern

Die Testfixture verwendet einen freien lokalen Port. Status, Antwortinhalt und Verzögerung sind kontrollierbar. Im Test für veraltete Antworten wird zunächst eine echte erste Anfrage angenommen. Erst danach startet die neue Anfrage. Damit prüft der Test einen laufenden Austausch und nicht nur zwei unmittelbar aufeinanderfolgende Funktionsaufrufe.

http_fixture.hpp · cppDatei öffnen
#pragma once
#include "json_orders.hpp"
#include <QTcpServer>
#include <QTcpSocket>
#include <QTimer>
#include <QUrl>

class HttpFixture : public QTcpServer {
public:
  QByteArray body =
      R"({"format":"appfabrik-order-lab","version":1,"orders":[{"id":7,"title":"Remote order"}]})";
  int status{200};
  int requests{0};
  int delayMs{0};
  explicit HttpFixture(QObject *parent = nullptr) : QTcpServer(parent) {
    connect(this, &QTcpServer::newConnection, this, [this] {
      while (hasPendingConnections()) {
        auto *socket = nextPendingConnection();
        connect(socket, &QTcpSocket::disconnected, socket,
                &QObject::deleteLater);
        connect(socket, &QTcpSocket::readyRead, socket,
                [this, socket, request = QByteArray{},
                 responded = false]() mutable {
                  request += socket->readAll();
                  if (responded || !request.contains("\r\n\r\n"))
                    return;
                  responded = true;
                  ++requests;
                  const auto reply = "HTTP/1.1 " + QByteArray::number(status) +
                                     " Fixture\r\nContent-Type: "
                                     "application/json\r\nContent-Length: " +
                                     QByteArray::number(body.size()) +
                                     "\r\nConnection: close\r\n\r\n" + body;
                  QTimer::singleShot(delayMs, socket, [socket, reply] {
                    if (socket->state() != QAbstractSocket::ConnectedState)
                      return;
                    socket->write(reply);
                    socket->disconnectFromHost();
                  });
                });
      }
    });
    if (!listen(QHostAddress::LocalHost, 0))
      qFatal("Local HTTP fixture cannot listen");
  }
  QUrl url() const {
    return QUrl(QString("http://127.0.0.1:%1/orders").arg(serverPort()));
  }
};
Erwartetes Ergebnis

Die neuere Antwort ist das einzige veröffentlichte Ergebnis.

06Fehlerfälle vollständig beobachten

QSignalSpy prüft Erfolg und Fehler getrennt. Die Tests behandeln HTTP 500, beschädigtes JSON, zu große Antworten, unbekannte Versionen, Timeout, wiederholten Abbruch und eine ersetzte Anfrage. QTRY-Makros warten begrenzt und verarbeiten Qt-Ereignisse. Die Abbruchprüfung verlangt außerdem, dass eine zweite cancel-Anforderung keinen weiteren Fehler erzeugt.

tests.cpp · cppDatei öffnen
#include "download.hpp"
#include "http_fixture.hpp"
#include <QSignalSpy>
#include <QtTest>
using namespace orders;
class NetworkTests : public QObject {
  Q_OBJECT
private slots:
  void successfulRequest() {
    HttpFixture server;
    OrderDownload loader;
    QSignalSpy ready(&loader, &OrderDownload::ready),
        failed(&loader, &OrderDownload::failed);
    loader.load(server.url());
    QTRY_COMPARE_WITH_TIMEOUT(ready.count(), 1, 2000);
    QCOMPARE(failed.count(), 0);
    QVERIFY(!loader.busy());
    QVERIFY(succeeded(decode(ready.at(0).at(0).toByteArray())));
  }
  void errors_data() {
    QTest::addColumn<int>("status");
    QTest::addColumn<QByteArray>("body");
    QTest::newRow("http") << 500 << QByteArray("{}");
    QTest::newRow("json") << 200 << QByteArray("broken");
    QTest::newRow("oversized")
        << 200 << QByteArray(maximumDocumentBytes + 1, 'x');
    QTest::newRow("schema")
        << 200
        << QByteArray(
               R"({"format":"appfabrik-order-lab","version":99,"orders":[]})");
  }
  void errors() {
    QFETCH(int, status);
    QFETCH(QByteArray, body);
    HttpFixture server;
    server.status = status;
    server.body = body;
    OrderDownload loader;
    QSignalSpy ready(&loader, &OrderDownload::ready),
        failed(&loader, &OrderDownload::failed);
    loader.load(server.url());
    QTRY_COMPARE_WITH_TIMEOUT(failed.count(), 1, 2000);
    QCOMPARE(ready.count(), 0);
    QVERIFY(!loader.busy());
  }
  void timeoutAndCancel() {
    HttpFixture server;
    server.delayMs = 400;
    OrderDownload loader;
    QSignalSpy failed(&loader, &OrderDownload::failed),
        ready(&loader, &OrderDownload::ready);
    loader.load(server.url(), 50);
    QTRY_COMPARE_WITH_TIMEOUT(failed.count(), 1, 1000);
    QVERIFY(failed.at(0).at(0).toString().contains("timed out"));
    loader.load(server.url());
    loader.cancel();
    QCOMPARE(failed.count(), 2);
    loader.cancel();
    QCOMPARE(failed.count(), 2);
    QCOMPARE(ready.count(), 0);
  }
  void supersededReplyCannotWin() {
    HttpFixture slow, fast;
    slow.delayMs = 300;
    fast.body.replace("Remote order", "Latest order");
    OrderDownload loader;
    QSignalSpy ready(&loader, &OrderDownload::ready),
        failed(&loader, &OrderDownload::failed);
    loader.load(slow.url());
    QTRY_COMPARE_WITH_TIMEOUT(slow.requests, 1, 2000);
    loader.load(fast.url());
    QTRY_COMPARE_WITH_TIMEOUT(ready.count(), 1, 2000);
    QVERIFY(ready.at(0).at(0).toByteArray().contains("Latest order"));
    QTest::qWait(400);
    QCOMPARE(ready.count(), 1);
    QCOMPARE(failed.count(), 0);
    loader.load(QUrl("file:///tmp/orders.json"));
    QCOMPARE(failed.count(), 1);
  }
};
QTEST_GUILESS_MAIN(NetworkTests)
#include "tests.moc"
Erwartetes Ergebnis

Alle Signal- und Fehlerprüfungen bestehen gegen lokale HTTP-Verbindungen.

07Doppelte Aktualisierungen vermeiden

Die Ausgangsklasse ersetzt eine laufende Anfrage bewusst. Für einen Aktualisieren-Button kann stattdessen gelten, dass weitere Klicks während einer Anfrage ignoriert werden. refreshIfIdle kapselt diese alternative Aufrufregel. Der Test zeigt einen abgewiesenen Doppelklick und eine erlaubte Aktualisierung nach Abschluss.

solution.cpp · cppDatei öffnen
#include "download.hpp"
#include "http_fixture.hpp"
#include <QSignalSpy>
#include <QtTest>
bool refreshIfIdle(orders::OrderDownload &loader, const QUrl &url) {
  if (loader.busy())
    return false;
  loader.load(url);
  return true;
}
class RefreshTest : public QObject {
  Q_OBJECT
private slots:
  void ignoresDoubleClick() {
    HttpFixture server;
    server.delayMs = 50;
    orders::OrderDownload loader;
    QSignalSpy ready(&loader, &orders::OrderDownload::ready);
    QVERIFY(refreshIfIdle(loader, server.url()));
    QVERIFY(!refreshIfIdle(loader, server.url()));
    QTRY_COMPARE_WITH_TIMEOUT(ready.count(), 1, 2000);
    QVERIFY(refreshIfIdle(loader, server.url()));
    QTRY_COMPARE_WITH_TIMEOUT(ready.count(), 2, 2000);
  }
};
QTEST_GUILESS_MAIN(RefreshTest)
#include "solution.moc"
Erwartetes Ergebnis

Zwei schnelle Aufrufe starten nur eine Anfrage. Nach Abschluss ist ein neuer Aufruf möglich.

Deine Übung

Implementiere refreshIfIdle. Während einer laufenden Anfrage soll die Funktion false zurückgeben, ohne diese Anfrage abzubrechen. Nach Abschluss muss ein erneuter Aufruf möglich sein.

Lösung mit Erklärung anzeigen

Die Lösung prüft busy vor load und gibt an, ob sie gestartet hat. Der Test verwendet einen verzögerten lokalen Server und wartet auf zwei getrennte erfolgreiche Ergebnisse. Automatische Wiederholungen werden hier bewusst nicht eingeführt.

solution.cpp · cppDatei öffnen
#include "download.hpp"
#include "http_fixture.hpp"
#include <QSignalSpy>
#include <QtTest>
bool refreshIfIdle(orders::OrderDownload &loader, const QUrl &url) {
  if (loader.busy())
    return false;
  loader.load(url);
  return true;
}
class RefreshTest : public QObject {
  Q_OBJECT
private slots:
  void ignoresDoubleClick() {
    HttpFixture server;
    server.delayMs = 50;
    orders::OrderDownload loader;
    QSignalSpy ready(&loader, &orders::OrderDownload::ready);
    QVERIFY(refreshIfIdle(loader, server.url()));
    QVERIFY(!refreshIfIdle(loader, server.url()));
    QTRY_COMPARE_WITH_TIMEOUT(ready.count(), 1, 2000);
    QVERIFY(refreshIfIdle(loader, server.url()));
    QTRY_COMPARE_WITH_TIMEOUT(ready.count(), 2, 2000);
  }
};
QTEST_GUILESS_MAIN(RefreshTest)
#include "solution.moc"

Projektbezug und Quellen

Eigenständiges Lernprojekt im Logistikthema von FactoryForge. Der bestehende FactoryForge-Quellstand dient als Architekturkontext. Die hier eingeführten SQLite-, Netzwerk- und Importfunktionen sind Funktionen des Lernprojekts. Das Order-Lab-JSON ist ein eigenes Format.