← C++

C++ · 22 / 24

Versionierte JSON-Dateien sicher migrieren

Du lädst ältere Dateien, ergänzt definierte Standardwerte und weist unbekannte Formate ohne Veränderung vorhandener Daten zurück.

  • Groß
  • Anspruchsvoll
  • 90 min

Voraussetzungen: Fehlertolerante Dateioperationen testen, Fehlerbehandlung und starke Ausnahmegarantie

In diesem Tutorial
  1. Das alte Format verstehen
  2. Das aktuelle Format festlegen
  3. Struktur und Grenzen prüfen
  4. Migration sichtbar ausführen
  5. Kompatibilität und Abweisung nachweisen
  6. Einen gefilterten Export ergänzen
  7. Übung und Lösung
  8. 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. 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. V1-zu-V2-Migration, JSON-Roundtrip, ungültige Struktur und Versionen, Größenlimit, Dateifehler und Erhalt einer gültigen Datei bei abgewiesenen Daten. Die Übung prüft einen gefilterten Export. Kein Crash-Durability-Nachweis.

Gespeicherte Dateien überleben oft die Programmversion, mit der sie erstellt wurden. Das Order-Lab-Format beginnt mit ID und Titel. Version 2 ergänzt Priorität und Status. Der Decoder übersetzt beide Versionen in dasselbe aktuelle Domänenmodell. Der Encoder schreibt ausschließlich Version 2. Dieses eigenständige Lernformat ist nicht das Projektformat der FactoryForge-Anwendung.

Paketinhalt und einzelne Dateien

01Das alte Format verstehen

Jede Datei nennt format und version ausdrücklich. appfabrik-order-lab unterscheidet diese Auftragslisten von anderen JSON-Dateien. Version 1 kennt nur id und title. Fehlende neue Eigenschaften werden nicht beliebig geraten, sondern durch die dokumentierte Migration ergänzt.

fixtures/orders-v1.json · jsonDatei öffnen
{
  "format": "appfabrik-order-lab",
  "version": 1,
  "orders": [
    {
      "id": 7,
      "title": "Legacy delivery"
    }
  ]
}
Erwartetes Ergebnis

Der Altauftrag hat nach dem Laden Priorität 0 und Status open.

02Das aktuelle Format festlegen

Version 2 verlangt zusätzlich priority zwischen 0 und 2 und status als open oder done. Eine Versionsnummer wie 1.5 ist kein gültiger Ersatz für Version 1. Unbekannte zukünftige Versionen werden abgelehnt. Der Decoder ignoriert zusätzliche Felder innerhalb einer bekannten Version, verlangt aber alle Pflichtfelder.

fixtures/orders-v2.json · jsonDatei öffnen
{
  "format": "appfabrik-order-lab",
  "version": 2,
  "orders": [
    {
      "id": 10,
      "title": "Deliver motors",
      "priority": 2,
      "status": "open"
    }
  ]
}
Erwartetes Ergebnis

Das Format lässt sich ohne Zugriff auf eine bestimmte App-Installation prüfen.

03Struktur und Grenzen prüfen

decode begrenzt Dokumente auf 256 KiB und Listen auf 1000 Einträge. Es kontrolliert Ganzzahlen, Typen, Statuswerte und eindeutige IDs. Erst nach vollständiger Validierung entsteht ein erfolgreiches Ergebnis. saveFile verwendet QSaveFile mit deaktiviertem direkten Schreibfallback. Ungültige Daten werden vor dem Öffnen der Zieldatei abgelehnt.

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

Eine abgewiesene Speicherung ersetzt keine vorhandene gültige Datei.

04Migration sichtbar ausführen

Starte ./build/order_lab nach python3 verify.py. Das Programm lädt einen eingebetteten V1-Auftrag und schreibt ihn über den aktuellen Encoder zurück. Es verändert keine Originaldatei. Vergleiche die Ausgabe mit orders-v2.json und identifiziere die beiden ergänzten Eigenschaften.

main.cpp · cppDatei öffnen
#include "json_orders.hpp"
#include <iostream>
int main() {
  auto migrated = orders::decode(
      R"({"format":"appfabrik-order-lab","version":1,"orders":[{"id":1,"title":"Legacy order"}]})");
  if (!orders::succeeded(migrated))
    return 1;
  auto encoded = orders::encode(std::get<std::vector<orders::Order>>(migrated));
  if (!orders::succeeded(encoded))
    return 1;
  std::cout << std::get<QByteArray>(encoded).toStdString() << '\n';
}
Erwartetes Ergebnis

Die Ausgabe enthält version 2, priority 0 und status open.

05Kompatibilität und Abweisung nachweisen

Die Tests prüfen V1-Migration, V2-Roundtrip und die vorhandene Datei nach einem ungültigen Speicherauftrag. Eine Tabelle negativer Fälle enthält beschädigtes JSON, falsches Wurzelformat, unbekannte oder gebrochene Versionsnummern, doppelte IDs, fehlende V2-Felder und zu große Daten. Ein Test für Stromausfallsicherheit wird damit nicht behauptet.

tests.cpp · cppDatei öffnen
#include "json_orders.hpp"
#include "test_support.hpp"
#include <QTemporaryDir>
#include <QtTest>
using namespace orders;
class FileTests : public QObject {
  Q_OBJECT
private slots:
  void migrationAndRoundTrip() {
    auto migrated = decode(
        R"({"format":"appfabrik-order-lab","version":1,"orders":[{"id":7,"title":"Legacy"}]})");
    QVERIFY(succeeded(migrated));
    auto batch = std::get<std::vector<Order>>(migrated);
    QCOMPARE(batch[0].priority, 0);
    QCOMPARE(batch[0].status, Status::open);
    auto encoded = encode(batch);
    QVERIFY(succeeded(encoded));
    QVERIFY(std::get<QByteArray>(encoded).contains("\"version\":2"));
    QVERIFY(std::get<std::vector<Order>>(
                decode(std::get<QByteArray>(encoded))) == batch);
    QTemporaryDir directory;
    auto path = directory.filePath("orders.json");
    QVERIFY(succeeded(saveFile(path, samples())));
    QVERIFY(std::get<std::vector<Order>>(loadFile(path)) == samples());
    auto invalid = samples();
    invalid[0].title.clear();
    QVERIFY(!succeeded(saveFile(path, invalid)));
    QVERIFY(std::get<std::vector<Order>>(loadFile(path)) == samples());
    QVERIFY(
        !succeeded(saveFile(directory.filePath("missing/file.json"), batch)));
    QVERIFY(!succeeded(loadFile(directory.filePath("absent.json"))));
  }
  void malformed_data() {
    QTest::addColumn<QByteArray>("input");
    QTest::newRow("syntax") << QByteArray("{");
    QTest::newRow("root") << QByteArray("[]");
    QTest::newRow("unknown") << QByteArray(
        R"({"format":"appfabrik-order-lab","version":3,"orders":[]})");
    QTest::newRow("fraction") << QByteArray(
        R"({"format":"appfabrik-order-lab","version":1.5,"orders":[]})");
    QTest::newRow("wrong-format")
        << QByteArray(R"({"format":"factory-forge","version":1,"orders":[]})");
    QTest::newRow("duplicate") << QByteArray(
        R"({"format":"appfabrik-order-lab","version":1,"orders":[{"id":1,"title":"A"},{"id":1,"title":"B"}]})");
    QTest::newRow("missing-fields") << QByteArray(
        R"({"format":"appfabrik-order-lab","version":2,"orders":[{"id":1,"title":"A"}]})");
    QTest::newRow("oversized") << QByteArray(maximumDocumentBytes + 1, ' ');
  }
  void malformed() {
    QFETCH(QByteArray, input);
    QVERIFY(!succeeded(decode(input)));
  }
};
QTEST_GUILESS_MAIN(FileTests)
#include "tests.moc"
Erwartetes Ergebnis

Gültige Altdateien werden übernommen. Jeder negative Fall liefert einen Fehler.

06Einen gefilterten Export ergänzen

encodeOpen erzeugt eine neue Liste ausschließlich offener Aufträge und verwendet anschließend den normalen Encoder. Dadurch gelten dieselben Format- und Validierungsregeln. Der ursprüngliche Bestand bleibt unangetastet. Die Lösung liest den Export wieder ein, statt nur nach einem Textstück in der Ausgabe zu suchen.

solution.cpp · cppDatei öffnen
#include "json_orders.hpp"
#include "test_support.hpp"
orders::Result<QByteArray> encodeOpen(std::span<const orders::Order> values) {
  std::vector<orders::Order> open;
  std::ranges::copy_if(values, std::back_inserter(open), [](const auto &order) {
    return order.status == orders::Status::open;
  });
  return orders::encode(open);
}
int main() {
  const auto original = samples();
  auto result = encodeOpen(original);
  require(orders::succeeded(result), "encode");
  auto decoded = orders::decode(std::get<QByteArray>(result));
  require(orders::succeeded(decoded), "decode exported file");
  require(std::get<std::vector<orders::Order>>(decoded).size() == 2,
          "only open exported");
  require(original == samples(), "source unchanged");
  require(std::get<QByteArray>(result).contains("\"version\":2"),
          "current version");
  require(orders::succeeded(encodeOpen({})), "empty export");
}
Erwartetes Ergebnis

Der Export enthält zwei offene Aufträge im aktuellen Format.

Deine Übung

Schreibe encodeOpen. Exportiere nur offene Aufträge als Version 2, ohne die Ausgangsliste zu verändern. Prüfe den erneut eingelesenen Inhalt und einen leeren Export.

Lösung mit Erklärung anzeigen

Die Lösung filtert in einen eigenen vector und ruft encode auf. Die Tests kontrollieren zwei offene Aufträge, Version 2, unveränderte Originaldaten und einen zulässigen leeren Export.

solution.cpp · cppDatei öffnen
#include "json_orders.hpp"
#include "test_support.hpp"
orders::Result<QByteArray> encodeOpen(std::span<const orders::Order> values) {
  std::vector<orders::Order> open;
  std::ranges::copy_if(values, std::back_inserter(open), [](const auto &order) {
    return order.status == orders::Status::open;
  });
  return orders::encode(open);
}
int main() {
  const auto original = samples();
  auto result = encodeOpen(original);
  require(orders::succeeded(result), "encode");
  auto decoded = orders::decode(std::get<QByteArray>(result));
  require(orders::succeeded(decoded), "decode exported file");
  require(std::get<std::vector<orders::Order>>(decoded).size() == 2,
          "only open exported");
  require(original == samples(), "source unchanged");
  require(std::get<QByteArray>(result).contains("\"version\":2"),
          "current version");
  require(orders::succeeded(encodeOpen({})), "empty export");
}

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.