Kontoeinstellungen bereitstellen

Einführung

Eine Website kann sich Anzeigeeinstellungen wie ein dunkles Design oder die bevorzugte Sprache merken. Solche Einstellungen werden oft bei jedem Besuch gelesen, aber nur selten geändert. Damit eignen sie sich gut als Beispiel für Workers KV. Statt ein einzelnes Wort als Feature-Flag zu speichern, speichern Sie JSON: Text, der benannte Felder zu einem Wert zusammenfasst. Ihr Worker wandelt diesen Text wieder in nutzbare Einstellungen um.

In diesem Lab sind Alice und Bob fiktive Kontobezeichnungen und keine echten Benutzer. Sie weisen beiden unterschiedliche Einstellungen zu und sorgen dafür, dass fehlende oder beschädigte Einträge einen sinnvollen Standardwert zurückgeben. Außerdem fügen Sie Metadaten hinzu – eine kurze Beschreibung, die zusammen mit einem Wert gespeichert wird –, um die Revision einer Einstellung zu kennzeichnen. Revisionsnummern helfen dabei zu erklären, welche Daten gelesen wurden. Sie garantieren nicht, dass jeder Standort sofort den neuesten Wert sieht.

Schließen Sie zuerst „Create a Feature Flag Store“ ab. Dieses Lab beginnt in einer frischen VM unter /home/labex/project/account-preferences. Node.js 22.22.0 und das projektspezifische Wrangler 4.131.1 sind bereits installiert. Sie erstellen in Ihrem Lernkonto einen neuen Worker und Namespace und verwenden dabei dieselben Berechtigungen zum Lesen des Kontos sowie zum Schreiben von Workern und KV. Die öffentliche Demo stellt nur synthetische Anzeigeeinstellungen bereit; die Kontobezeichnung in der URL dient nicht zur Authentifizierung. Für diese kleine Übung sind kein kostenpflichtiges Upgrade und keine gekaufte Domain erforderlich. Führen Sie die Ressourcenbereinigung durch, bevor Sie die VM verlassen.

Einen Einstellungs-Namespace verbinden

In diesem Schritt verbinden Sie einen unabhängigen Namespace für beispielhafte Kontoeinstellungen. Ein Namespace fasst die Werte dieses Dienstes zusammen. Das Binding PREFERENCES gibt Ihrem Worker einen festen Namen für den Zugriff darauf. Diese frische VM verwendet Ihr vorhandenes Kontowissen erneut, aber nicht den Namespace oder die Autorisierung aus dem vorherigen Lab.

Wechseln Sie in das vorbereitete Projekt:

cd /home/labex/project/account-preferences

Generieren Sie einmalig einen eindeutigen Namen. openssl rand -hex 6 gibt ein zufälliges Suffix aus; $(...) fügt es in den Namen ein. Die Shell-Variable stellt diesen Namen für die folgenden Befehle in diesem Terminal bereit.

WORKER_NAME="labex-prefs-$(openssl rand -hex 6)"

printf '%s\n' "$WORKER_NAME"

Autorisieren Sie diese VM. Neben dem Lesen Ihrer Kontoidentität erlaubt Workers Scripts Write die Bereitstellung und Löschung. Workers KV Write erlaubt die Verwaltung des Namespace und der Schlüssel für dieses Lab.

npx wrangler login --device --browser=false --scopes account:read user:read workers_scripts:write workers_kv:write

Öffnen Sie den angezeigten Geräte-Link im Browser, geben Sie den aktuellen Code ein, prüfen Sie die angeforderten Berechtigungen und das Lernkonto und autorisieren Sie Wrangler. Auf der Zustimmungsseite kann außerdem ein Zugriff im Hintergrund angezeigt werden. Kehren Sie zum Terminal zurück und warten Sie, bis die Anmeldung abgeschlossen ist.

Erweitern Sie Developer Platform, um Workers Scripts Write und Workers KV Storage Write zu prüfen. Dies sind dieselben Berechtigungen zur Ressourcenverwaltung, die in „Create a Feature Flag Store“ eingeführt wurden.

npx wrangler whoami --json

Bestätigen Sie loggedIn: true sowie den name des Lernkontos, auch wenn nur ein Konto aufgeführt ist. Kopieren Sie die id dieses Kontos. Tragen Sie sie in der folgenden Konfiguration ein und ersetzen Sie YOUR_ACCOUNT_ID, bevor Sie den Befehl ausführen. Das cat-Here-Dokument schreibt alles zwischen den beiden JSON-Zeilen in eine Datei; > ersetzt die Datei. Das nicht in Anführungszeichen gesetzte Trennzeichen erlaubt es der Shell, $WORKER_NAME einzusetzen.

cat > wrangler.jsonc <<JSON
{
  "name": "$WORKER_NAME",
  "main": "src/index.js",
  "compatibility_date": "2026-07-30",
  "account_id": "YOUR_ACCOUNT_ID",
  "workers_dev": true
}
JSON

Erstellen Sie in diesem Konto einen Namespace. Sein Titel enthält denselben eindeutigen Namen wie der Worker, damit Sie beide später erkennen können. --update-config=false lässt die erforderliche Änderung am Binding sichtbar für Sie, statt die Datei automatisch zu ändern.

npx wrangler kv namespace create "$WORKER_NAME-preferences" --update-config=false

Die Ausgabe enthält die ID des neuen Namespace. Kopieren Sie sie und ersetzen Sie anschließend YOUR_ACCOUNT_ID und YOUR_NAMESPACE_ID in dieser vollständigen Konfiguration. Der Binding-Name PREFERENCES wird für Ihren Code gewählt; die ID identifiziert die tatsächliche Cloudflare-Ressource.

cat > wrangler.jsonc <<JSON
{
  "name": "$WORKER_NAME",
  "main": "src/index.js",
  "compatibility_date": "2026-07-30",
  "account_id": "YOUR_ACCOUNT_ID",
  "workers_dev": true,
  "kv_namespaces": [
    { "binding": "PREFERENCES", "id": "YOUR_NAMESPACE_ID" }
  ]
}
JSON

npx wrangler kv namespace list

Suchen Sie den Namespace-Titel dieses Labs und vergleichen Sie seine ID mit der ID in der Datei. Andere Namespaces können vorhanden sein; lassen Sie sie unverändert. Diese Konfiguration legt fest, welches Konto und welche Ressource die späteren Befehle verwenden sollen. Ein Binding ist eine Referenz auf einen Namespace, keine Kopie seiner Daten.

JSON-Werte und Revisionsmetadaten speichern

In diesem Schritt bereiten Sie einen kleinen Datensatz vor, der normale Einstellungen und zwei realistische Datenfehler enthält. JSON verwendet doppelte Anführungszeichen für Feldnamen und Zeichenketten. Die einfachen Anführungszeichen um das Befehlsargument verhindern, dass die Shell diese JSON-Anführungszeichen interpretiert.

Schreiben Sie die lokalen Einträge. Alice bevorzugt den dunklen Modus und Englisch; Bob bevorzugt den hellen Modus und Französisch. --metadata fügt dem Schlüssel ein separates JSON-Objekt hinzu. Die revision-Nummer ist hier eine Bezeichnung für die gespeicherte Version, keine Sicherheitsentscheidung und kein automatischer Aktualisierungszähler.

npx wrangler kv key put account:alice '{"theme":"dark","language":"en"}' --binding PREFERENCES --local --metadata '{"revision":7}'

npx wrangler kv key put account:bob '{"theme":"light","language":"fr"}' --binding PREFERENCES --local --metadata '{"revision":8}'

npx wrangler kv key put account:broken 'not-json' --binding PREFERENCES --local

npx wrangler kv key put account:invalid '{"theme":"neon","language":"en"}' --binding PREFERENCES --local

account:broken enthält Text, der nicht als JSON analysiert werden kann. account:invalid enthält gültiges JSON, nennt aber ein Design, das die Anwendung nicht unterstützt. Anhand beider Fälle können Sie Parsing – das Lesen der Textstruktur – von Validierung – der Prüfung, ob die Felder für die Anwendung sinnvoll sind – unterscheiden. Erstellen Sie keinen Eintrag für Charlie. Damit testen Sie später den Pfad für einen fehlenden Schlüssel.

npx wrangler kv key list --binding PREFERENCES --local

Finden Sie vier Schlüsselnamen. Alice und Bob sollten die Revisionsmetadaten 7 beziehungsweise 8 besitzen. Die beiden anderen Einträge haben keine Metadaten. Die Auflistung zeigt Namen und Metadaten, aber nicht jeden Wert.

npx wrangler kv key get account:alice --binding PREFERENCES --local --text

Erwarten Sie {"theme":"dark","language":"en"}. Der Befehl liest nur den Wert. Daher ist die Revision nicht Teil dieses JSON-Texts.

Schreiben Sie nun dieselben vier synthetischen Testdaten in den Cloud-Namespace dieses Labs. Diese expliziten Remote-Befehle sind separate Vorgänge: Lokale Schreibvorgänge laden niemals Daten zu Cloudflare hoch.

npx wrangler kv key put account:alice '{"theme":"dark","language":"en"}' --binding PREFERENCES --remote --metadata '{"revision":7}'

npx wrangler kv key put account:bob '{"theme":"light","language":"fr"}' --binding PREFERENCES --remote --metadata '{"revision":8}'

npx wrangler kv key put account:broken 'not-json' --binding PREFERENCES --remote

npx wrangler kv key put account:invalid '{"theme":"neon","language":"en"}' --binding PREFERENCES --remote

npx wrangler kv key list --binding PREFERENCES --remote

Bestätigen Sie dieselben vier Schlüsselnamen und ihre Revisionsmetadaten. Diese Datensätze dienen nur der Demonstration und können gelöscht werden. Lassen Sie nicht zugehörige Namespaces unverändert.

Einstellungen mit sicheren Standardwerten lesen

In diesem Schritt schreiben Sie einen Handler, der Wert und Metadaten gemeinsam abruft. getWithMetadata() gibt ein Objekt mit den Feldern value und metadata zurück. Bei einem fehlenden Schlüssel ist der Wert null. Auch die Metadaten können null sein, selbst wenn ein Wert vorhanden ist.

Schreiben Sie diesen Handler. Das in Anführungszeichen gesetzte JS-Here-Dokument bewahrt den Code unverändert. Die Route akzeptiert eine kurze kleingeschriebene Kontobezeichnung und erstellt daraus einen eindeutigen Schlüssel wie account:alice. Sie speichert niemals das Konto einer vorherigen Anfrage in einer globalen Variable.

cat > src/index.js <<'JS'
function fallback(account, source) {
  return Response.json({
    account, theme: "light", language: "en", source, revision: null
  });
}

export default {
  async fetch(request, env) {
    const match = new URL(request.url).pathname.match(/^\/preferences\/([a-z]{1,20})$/);
    if (!match) return new Response("Not found", { status: 404 });
    const account = match[1];
    let entry;
    try {
      entry = await env.PREFERENCES.getWithMetadata(`account:${account}`, "text");
    } catch {
      return Response.json({ error: "Preferences temporarily unavailable" }, { status: 503 });
    }
    if (entry.value === null) return fallback(account, "missing");

    let preferences;
    try {
      preferences = JSON.parse(entry.value);
    } catch {
      return fallback(account, "invalid");
    }
    if (!preferences || typeof preferences !== "object" || Array.isArray(preferences) ||
        !["light", "dark"].includes(preferences.theme) ||
        !["en", "fr"].includes(preferences.language)) {
      return fallback(account, "invalid");
    }
    const revision = Number.isInteger(entry.metadata?.revision) && entry.metadata.revision > 0
      ? entry.metadata.revision : null;
    return Response.json({
      account, theme: preferences.theme, language: preferences.language,
      source: "stored", revision
    });
  }
};
JS

Der erste try/catch behandelt einen nicht verfügbaren KV-Lesevorgang mit HTTP 503. Das bedeutet, dass der Dienst vorübergehend nicht verfügbar ist. Der Handler tut nicht so, als würde das Konto fehlen. Durch das Lesen als "text" und das anschließende Parsen in einem separaten try/catch können Sie beschädigtes JSON erkennen, ohne es mit einem Speicherfehler zu verwechseln. Die Option "json" kann das Parsen automatisch durchführen. In dieser Lektion werden die beiden Vorgänge jedoch getrennt, damit ihre Fehlerpfade sichtbar sind.

Sowohl fehlende als auch ungültige Einstellungen verwenden als Fallback den hellen Modus und Englisch. Das Feld source erklärt, warum der Fallback verwendet wurde. Bei einem gültigen Wert verwendet die Antwort nur die unterstützten Felder für Design und Sprache. entry.metadata?.revision behandelt fehlende Metadaten sicher. Eine positive Ganzzahl als Revision wird angezeigt, andernfalls ist der Wert null. Diese Standardwerte halten optionale Anzeigeeinstellungen nutzbar. Sie sind kein Ersatz für Authentifizierung oder Berechtigungen.

Starten Sie den lokalen Worker, speichern Sie seine Prozess-ID und warten Sie auf die Bereitschaftsmeldung:

npx wrangler dev --local --ip 0.0.0.0 --port 8080 > local.log 2>&1 &

DEV_PID=$!

cat local.log

Der Hintergrundprozess hält das Terminal frei; local.log enthält seine Ausgabe. Wiederholen Sie den Log-Befehl, falls der Start noch nicht abgeschlossen ist. Rufen Sie nun die einzelnen Fälle ab:

curl -i http://127.0.0.1:8080/preferences/alice

curl -i http://127.0.0.1:8080/preferences/bob

curl -i http://127.0.0.1:8080/preferences/charlie

curl -i http://127.0.0.1:8080/preferences/broken

curl -i http://127.0.0.1:8080/preferences/invalid

Alle fünf Anfragen sollten HTTP 200 mit JSON zurückgeben. Prüfen Sie die Unterschiede:

Der Body für Alice lautet beispielsweise {"account":"alice","theme":"dark","language":"en","source":"stored","revision":7}. Rufen Sie Alice nach Bob erneut ab. Die Einstellungen müssen weiterhin zu Alice gehören. Lassen Sie den lokalen Server bis zur Bereinigung laufen.

Den bereitgestellten Einstellungsdienst überprüfen

In diesem Schritt führen Sie dieselben Tests gegen den Cloud-Namespace aus. Die unabhängige Cloud-Prüfung bestätigt das ausgewählte Konto, das Binding des bereitgestellten Workers, die gespeicherten Datensätze und die tatsächlichen HTTP-Antworten.

npx wrangler deploy

Bestätigen Sie in der Ausgabe den generierten Worker-Namen und das Binding PREFERENCES. Kopieren Sie die bereitgestellte öffentliche Adresse in die folgende Variable und ersetzen Sie das Beispiel:

WORKER_URL="https://YOUR_WORKER.YOUR_SUBDOMAIN.workers.dev"

curl -i "$WORKER_URL/preferences/alice"

curl -i "$WORKER_URL/preferences/bob"

curl -i "$WORKER_URL/preferences/charlie"

curl -i "$WORKER_URL/preferences/broken"

curl -i "$WORKER_URL/preferences/invalid"

Vergleichen Sie alle fünf Antworten mit der lokalen Tabelle. Alice und Bob müssen ihre eigenen Einstellungen und Revisionsmetadaten behalten. Charlie sowie die beiden beschädigten Datensätze müssen die erklärten Standardwerte verwenden. Falls ein kürzlich geschriebener Eintrag noch nicht sichtbar ist, warten Sie auf die KV-Weitergabe und wiederholen Sie die Anfrage. Auch ein öffentlicher Hostname benötigt nach der ersten Bereitstellung möglicherweise etwas Zeit. Zählen Sie einen Verbindungsfehler nicht als Fallback-Antwort.

Wählen Sie im Dashboard das Lernkonto aus, öffnen Sie Storage & databases → Workers KV und suchen Sie den Namespace labex-prefs-...-preferences dieses Labs. Wählen Sie KV Pairs, prüfen Sie die vier Datensätze und klicken Sie neben account:alice auf View, um den JSON-Wert mit der Terminalausgabe zu vergleichen. Diese Ansicht zeigt Schlüssel und Werte; vergleichen Sie die Revisionsmetadaten anhand der vorherigen Wrangler-Schlüsselliste und der API-Antwort. Ihr eindeutiger Namespace-Name und die IDs unterscheiden sich vom Beispiel.

Der öffentliche Endpunkt ist nur eine Demo für synthetische Anzeigeeinstellungen. Ein echter privater Einstellungsdienst würde den Aufrufer identifizieren, bevor er entscheidet, auf welchen Kontoschlüssel dieser zugreifen darf.

Nicht benötigte Cloud-Ressourcen löschen

In diesem Schritt entfernen Sie beide Ressourcen, solange Wrangler noch autorisiert ist. Ein Namespace kann länger als sein Worker bestehen. Deshalb entfernt das Löschen der Anwendung allein die darin gespeicherten Daten nicht.

Stoppen Sie den lokalen Entwicklungsprozess, den Sie in diesem Terminal gestartet haben:

kill "$DEV_PID"

Prüfen Sie Ihre gespeicherten Ressourcenreferenzen, bevor Sie etwas löschen:

cat wrangler.jsonc

Bestätigen Sie den Worker-Namen labex-prefs-... und die Namespace-ID des Bindings PREFERENCES. Löschen Sie den Worker, der durch diese Konfiguration ausgewählt wird:

npx wrangler delete

Falls Sie dazu aufgefordert werden, prüfen Sie, ob der angezeigte Name zu diesem Lab gehört, und bestätigen Sie mit y. Löschen Sie anschließend nur den Namespace, auf den PREFERENCES verweist:

npx wrangler kv namespace delete --binding PREFERENCES

Prüfen Sie den Namespace in jeder Bestätigungsabfrage, bevor Sie zustimmen. Lassen Sie wrangler.jsonc unverändert, damit die unabhängige Prüfung erkennen kann, welche Ressourcen nicht mehr vorhanden sein dürfen.

npx wrangler kv namespace list

Der Namespace dieses Labs sollte nicht mehr vorhanden sein. Nicht zugehörige Namespaces müssen erhalten bleiben. Aktualisieren Sie die Listen im Dashboard und bestätigen Sie, dass der Worker und der Namespace dieses Labs verschwunden sind. Eine fehlgeschlagene Anfrage oder eine abgelaufene Anmeldung beweist keine Löschung. Führen Sie die Prüfung dieses Schritts aus, bevor Sie sich abmelden, damit sie den autorisierten Bestand untersuchen kann.

Die VM-Autorisierung beenden

In diesem Schritt trennen Sie Wrangler, nachdem die Bereinigungsprüfung erfolgreich war. Das Abmelden beendet die gespeicherte Wrangler-Autorisierung dieser VM. Cloud-Ressourcen werden dadurch nicht gelöscht, und Ihre normale Dashboard-Browsersitzung wird nicht abgemeldet.

npx wrangler logout

npx wrangler whoami --json

Bestätigen Sie, dass das strukturierte Ergebnis "loggedIn": false meldet. Dieser nicht authentifizierte Befehl kann mit einem Status ungleich null beendet werden. Das ist hier erwartungsgemäß. Falls nur ein Verbindungsfehler und kein ausdrücklicher Authentifizierungsstatus angezeigt wird, wiederholen Sie den Befehl, sobald die Verbindung funktioniert.

Die verbleibenden lokalen Dateien und der lokale KV-Zustand gehören zu dieser temporären VM. Sie sind von den Cloud-Ressourcen getrennt, die Sie bereits gelöscht haben. Sie können das Lab nun abschließen.

Zusammenfassung

Sie haben strukturierte Einstellungen und Revisionsmetadaten in Workers KV gespeichert und anschließend über ein Worker-Binding gelesen. Die Einstellungen von Alice und Bob blieben getrennt. Fehlende, fehlerhafte und nicht unterstützte Werte führten zu erklärten Standardwerten. Außerdem haben Sie einen Speicherfehler von einem fehlenden Datensatz unterschieden, statt beide Fälle hinter derselben Antwort zu verbergen.

Nach dem Vergleich der lokalen und Cloud-Antworten haben Sie den temporären Worker und Namespace entfernt und sich abgemeldet. Als Nächstes geben Sie temporären Hinweisen eine Anwendungsfrist und ein KV-Ablaufdatum.