Dry-Run-Endpunkte, die KI-Programmieragenten zuverlässig machen

KI-Programmieragenten sollten nicht erst durch die Änderung selbst herausfinden, ob eine Änderung gültig ist. Das ist ein nachlässiges API-Design, und bei autonomen Agents werden die Kosten schnell sichtbar. Ein Agent kann schneller erneut versuchen, einen anderen Pfad einschlagen und zur nächsten Aufgabe wechseln, als ein Operator eine versehentliche Berechtigungsänderung, eine teilweise Migration oder eine falsch eingegrenzte Löschung rekonstruieren kann.

Eine Vorschauaktion verdient ihren Platz nur dann, wenn sie eine konkrete Ausführung mit ausreichender Genauigkeit vorhersagt, sodass ein Mensch oder Agent entscheiden kann, ob die Aktion fortgesetzt werden soll. Eine Antwort mit dem Inhalt «gültig» ist kein Plan. Ein Diff, der eine kaskadierende Aktualisierung auslässt, ist schlimmer als gar kein Diff, weil er trügerische Sicherheit erzeugt.

Das sinnvolle Designziel ist einfach: Den geplanten Schreibvorgang übermitteln, ihn gegen den aktuellen Zustand und die normalen Geschäftsregeln bewerten, die geplanten Auswirkungen und Fehler zurückgeben und anschließend verhindern, dass veraltete oder veränderte Pläne ausgeführt werden. Das erfordert mehr Sorgfalt als das Hinzufügen von dryRun=true. Gleichzeitig erhält ein Agent die Möglichkeit, eine ungültige Anfrage zu reparieren, bevor er einen Menschen um Genehmigung bittet.

Eine Vorschau muss den exakten Schreibvorgang beschreiben

Dry-Run-Endpunkte müssen dieselbe relevante Absicht wie die Ausführung akzeptieren und die Auswirkungen genau dieser Absicht berechnen. Wenn POST /memberships eine Rolle vergeben, eine Einladung senden, das Mitglied einer Abrechnungsgruppe hinzufügen und einen Audit-Eintrag schreiben kann, muss die Vorschau jede Auswirkung melden, die bei der Ausführung entstehen würde.

Teams veröffentlichen häufig einen «validate»-Endpunkt, der JSON-Struktur und Pflichtfelder prüft. Dafür gibt es einen sinnvollen Anwendungsfall, aber er liefert keine Vorschau auf einen Schreibvorgang. Er kann dem Aufrufer nicht mitteilen, dass die angeforderte Rolle mit einer bestehenden Rolle kollidiert, dass das Zielkonto gesperrt ist oder dass die Einladung einen begrenzten Sitz verbraucht. Nennen Sie ihn Validierung, wenn er genau das tut.

Der Unterschied ist wichtig, weil Agents erfolgreiche Aufrufe als Beleg behandeln. Eine Antwort, die nur die Validierung bestätigt, gefolgt von der Ausführung, lässt den Agenten über die zustandsabhängigen Teile der Entscheidung im Unklaren. Eine vollständige Vorschau bewertet sowohl die Anfrage als auch die aktuelle Welt.

Formulieren Sie für jede beschreibbare Operation zunächst den Ausführungsvertrag in einem Satz, bevor Sie die Vorschau entwerfen:

Bei dieser Eingabe und der beobachteten Zielrevision wird die Ausführung diese benannten Auswirkungen erstellen, aktualisieren, löschen oder auslösen.

Dieser Satz legt vages Verhalten offen. «Projekteinstellungen aktualisieren» ist zu allgemein. «retention_days von 30 auf 14 ändern, den Ablauf für 18 aktive Elemente neu berechnen und Elemente unter gesetzlicher Aufbewahrung ablehnen» gibt der Vorschau etwas Testbares zurück.

Eine gute Vorschau bewahrt die Semantik der Operation. Machen Sie aus einer Massenlöschung keine vage Anzahl, nur weil die echte Liste unbequem ist. Verwenden Sie nicht «kann betroffen sein», wenn Ihr Dienst die tatsächlichen Ressourcen bestimmen kann. Ist die Ressourcengruppe zu groß für eine Inline-Antwort, geben Sie eine Gesamtzahl, eine begrenzte Stichprobe sowie einen Cursor oder einen Berichtsverweis zurück, über den der Aufrufer die vollständige Gruppe vor der Ausführung prüfen kann.

Der Plan braucht Identität, Umfang und Konsequenzen

Niemand kann beurteilen, dass «12 Datensätze geändert werden», ohne zu wissen, welche Datensätze betroffen sind und wie sie sich ändern. Die geplante Aktion sollte ihre Eingaben, ihren Zielumfang und ihre Konsequenzen in Formen angeben, die sowohl ein Programm als auch ein Mensch prüfen können.

Bei der Aktualisierung einer einzelnen Ressource funktioniert ein Diff auf Feldebene oft gut. Bei einer Bereitstellung kann der Plan Images, Umgebungen, Konfigurationsrevisionen, Neustartverhalten und Gesundheitsprüfungen benötigen. Bei einer Abrechnungsänderung können die alte und neue Belastung, das Wirksamkeitsdatum und die Frage erforderlich sein, ob der Kunde eine Benachrichtigung erhält. Richten Sie die Ausgabe an der Fachdomäne aus, statt jede Operation in ein JSON-Patch-Array zu zwingen.

Mindestens diese Bestandteile sollten sichtbar sein:

• Ein Operationsname und ein ausdrücklicher Vorschau-Status.
• Eine stabile Kennung für jede betroffene Ressource sowie ihre Revision, sofern Ihr Dienst Revisionen unterstützt.
• Die bisherigen und geplanten Werte für jede relevante Änderung.
• Sekundäre Auswirkungen wie Jobs, Benachrichtigungen, Zugriffsänderungen oder berechnete Gebühren.
• Warnungen, Ausführungsblocker und Annahmen, die das Ergebnis verändern könnten.

«Relevant» erfordert Urteilsvermögen. Ein unveränderter Datenbankzeitstempel hilft einer genehmigenden Person selten. Ein neu zugewiesener Besitzer, eine erweiterte Gruppenmitgliedschaft oder eine geplante Löschung dagegen schon. Zeigen Sie zuerst das fachliche Ergebnis und bieten Sie niedrigere Detailstufen an, wenn ein Aufrufer sie benötigt.

Eine Vorschau muss außerdem direkte und abgeleitete Auswirkungen unterscheiden. Angenommen, ein Agent senkt das Speicherkontingent eines Teams. Die direkte Änderung betrifft ein Kontingentfeld. Das abgeleitete Ergebnis könnte sein, dass Uploads für drei bestehende Projekte gesperrt werden. Wird dies unter einer allgemeinen Warnung versteckt, wirkt die Operation sicherer, als sie ist. Legen Sie die Auswirkung in ein eigenes effects-Array und nennen Sie die Ursache.

Seien Sie auch bei Unsicherheit präzise. Eine Vorschau kann angeben, dass die Ausführung einen externen Steuerdienst abfragt oder später Arbeiten einplant. Sie sollte keinen endgültigen Steuerbetrag behaupten, wenn der Dienst noch keinen berechnet hat. Verwenden Sie einen Annahmeeintrag, der die Abhängigkeit nennt und angibt, ob die Ausführung ohne sie fortgesetzt werden kann.

Die Validierung muss Blocker und Warnungen trennen

Eine Vorschau sollte einem Agenten genau mitteilen, was die Ausführung verhindert, was geprüft werden sollte und was lediglich Kontext liefert. Werden diese Kategorien vermischt, führt das zwangsläufig zu schlechten Wiederholungsversuchen und Genehmigungsmüdigkeit.

Ein Blocker bedeutet, dass der Dienst die Ausführung unter den bewerteten Bedingungen ablehnen wird. Der Agent sollte die Eingabe reparieren, eine fehlende Berechtigung beschaffen oder anhalten. Eine Warnung bedeutet, dass die Ausführung fortgesetzt werden kann, ein vernünftiger Operator die Konsequenz aber möglicherweise prüfen möchte. Kontext liefert Informationen, ohne Gefahr anzudeuten.

Geben Sie strukturierte Fehler zurück, nicht Prosa, die ein Agent erst analysieren muss. Dieses Format ist bewusst gewöhnlich:

{
  "mode": "preview",
  "executable": false,
  "validation": [
    {
      "severity": "error",
      "code": "version_conflict",
      "path": "/if_match",
      "message": "Project prj_184 is at revision 73, not revision 71.",
      "blocks_execution": true,
      "repair": "Fetch the current project and create a new preview."
    },
    {
      "severity": "warning",
      "code": "member_count_change",
      "message": "The group will gain 42 members through nested groups.",
      "blocks_execution": false
    }
  ]
}

Stabile Codes ermöglichen es einem Agenten, eine passende Reaktion auszuwählen. Nach version_conflict kann er eine aktuelle Revision abrufen. Nach legal_hold_active kann er nicht verantwortungsvoll selbst eine Lösung erfinden. Die message ist für die Person gedacht, die die Aktion prüft. Behalten Sie beides bei.

Kennzeichnen Sie nicht jede überraschende Bedingung als Warnung. Eine Warnung, die immer eine Änderung der Anfrage erfordert, sollte ein Fehler sein. Umgekehrt sollte eine ungewöhnliche, aber erlaubte Bedingung die Ausführung nicht blockieren. Teams machen jede Warnung zum Blocker, weil sie nichts übersehen wollen. Anschließend übermitteln Agents Vorschauen, die ohne manuelle Bereinigung niemals abgeschlossen werden können. Die Schnittstelle wird zur bloßen Inszenierung.

Der nützliche Test ist einfach: Würde die Ausführung mit derselben Eingabe im selben Zustand laufen? Wenn ja, melden Sie eine Warnung oder Kontext. Wenn nein, melden Sie einen Fehler. Trennen Sie Autorisierungsfehler von fachlicher Validierung. Sie erklären unterschiedliche Probleme und benötigen unterschiedliche Maßnahmen.

Ein Dry Run darf nicht heimlich hinter dem Aufrufer schreiben

Eine Vorschau muss dauerhafte externe Auswirkungen vermeiden, auch solche, die Entwickler als Aufräumarbeit abtun. Das Erstellen einer «temporären» Zeile, das Reservieren von Bestand, das Erhöhen einer für Benutzer sichtbaren Sequenz, das Einreihen eines Webhooks, das Senden einer E-Mail oder das Aktualisieren eines Zeitstempels für den letzten Zugriff verletzt die Erwartung, dass die Anfrage gefahrlos geprüft werden kann.

Dieser Fehler tritt in ausgereiften Diensten auf, weil der Ausführungscode um praktische Abkürzungen herum gewachsen ist. Ein Create-Handler kann am Anfang eine Kennung vergeben, vor der Validierung einen ausstehenden Datensatz schreiben und vor dem Commit der Transaktion einen Event-Publisher aufrufen. Später wird nur das abschließende Einfügen mit if preview umschlossen. In einem lokalen Test wirkt die Vorschau harmlos und verbraucht in der Produktion trotzdem Kennungen, erzeugt Event-Verkehr oder hinterlässt Rückstände.

Behandeln Sie die Vorschauausführung als eigenen Modus im Anwendungsdienst, nicht nur als Bedingung im Controller. Der Modus kann gemeinsame Funktionen für Parsing, Autorisierung, Richtlinien und Planung aufrufen. Schreibvorgänge und externe Sendungen müssen jedoch über Schnittstellen laufen, die entweder eine geplante Auswirkung erzeugen oder die Anfrage ablehnen.

Eine sinnvolle Implementierungsgrenze sieht so aus:

parse request
  -\u003e authorize caller
  -\u003e load consistent current state
  -\u003e validate business rules
  -\u003e build plan
  -\u003e preview: return plan
  -\u003e execute: apply plan in a transaction, then publish committed effects

Die Reihenfolge ist wichtig. Wenn Ihre Datenbank Transaktionen unterstützt, erstellen Sie den Plan aus denselben Lesevorgängen, die auch die Ausführung steuern. Kann eine Abhängigkeit nicht an der Transaktion teilnehmen, melden Sie ihre ausstehende Interaktion als ausdrückliche Auswirkung und entwerfen Sie für Fehler eine kompensierende Aktion. Ein externer Aufruf wird nicht dadurch transaktional, dass man so tut, als wäre er es.

Auch Audit-Einträge brauchen eine bewusste Entscheidung. Sie möchten möglicherweise festhalten, dass ein Aufrufer eine Vorschau angefordert hat. Das ist vernünftig, aber schreiben Sie dieses Ereignis in einen klar getrennten Audit-Pfad und stellen Sie sicher, dass es keine für abgeschlossene Änderungen gedachten Workflows auslöst. Stellen Sie «Vorschau erstellt» nicht neben «Berechtigung erteilt» und erwarten Sie, dass nachgelagerte Verbraucher den Unterschied erraten.

Testen Sie das Ausbleiben von Änderungen, nicht nur die Ausgabe. Prüfen Sie vor und nach einer Vorschauanfrage, dass relevante Tabellen, ausgehende Warteschlangen, Objektspeicher, E-Mail-Testsenken und nachgelagerte Webhook-Empfänger unverändert sind. Unit-Tests entdecken das nur selten. Ein Integrationstest in einer kurzlebigen Umgebung schon.

HTTP-Semantik braucht einen ausdrücklichen Vertrag

HTTP kennt keine universelle Dry-Run-Methode. Wer das Gegenteil annimmt, verursacht Kompatibilitätsprobleme. RFC 9110 definiert GET, HEAD, OPTIONS und TRACE als sichere Methoden in dem Sinn, dass ein Client damit keine Zustandsänderung anfordert. Das bedeutet weder, dass ein POST mit einem Query-Parameter sicher ist, noch definiert es dryRun als standardisierte Anweisung.

Daher muss der Designer eines Endpunkts den Modus sowohl in der Anfrage als auch in der Antwort sichtbar machen. Ein POST ist oft weiterhin angemessen, weil die Planung komplexer Schreibvorgänge einen Anfrage-Body benötigt und eine aufwendige Bewertung erfordern kann. Wichtig ist, dass Clients, Logs und Menschen eine Vorschau ohne Rätselraten von einer Ausführung unterscheiden können.

Bei einer einfachen Operation ist ein ausdrückliches Feld im Body leicht lesbar und geht schwer verloren:

POST /v1/projects/prj_184/memberships/plan
Content-Type: application/json

{
  "subject_id": "usr_92",
  "role": "admin",
  "if_match": "73"
}

Ein eigener /plan-Endpunkt ist sinnvoll, wenn die Planung eine eigene Ausgabe, einen eigenen Lebenszyklus oder eigene Berechtigungen hat. Außerdem vermeidet er ein wiederkehrendes Problem mit Query-Flags: Ein generierter Client lässt das Flag weg, ein Proxy ignoriert es in der Cache-Konfiguration oder ein Aufrufer kopiert die URL falsch und führt den Schreibvorgang aus. Wenn Sie einen gemeinsamen Endpunkt mit einem mode-Feld wählen, lehnen Sie fehlende oder unbekannte Werte bei Operationen ab, bei denen eine versehentliche Ausführung schwerwiegende Folgen hätte.

Geben Sie einen Antworttyp zurück, der nicht mit der ausgeführten Ressource verwechselt werden kann. 201 Created mit einem ressourcenähnlichen Body ist auch dann eine schlechte Vorschauantwort, wenn Sie ein Feld preview: true hinzufügen. Verwenden Sie 200 OK für einen sofort verfügbaren Plan oder 202 Accepted nur dann, wenn die Planung selbst asynchron ausgeführt wird. Fügen Sie mode: "preview" in den Antwort-Body ein und setzen Sie einen ausdrücklichen Content-Type, wenn Ihre API typisierte Medientypen verwendet.

Vermeiden Sie das Caching von Vorschauen, solange Sie nicht jede Eingabe verstehen, die sie beeinflusst, einschließlich Identität und Autorisierung des Aufrufers. Die sicherste Standardeinstellung ist Cache-Control: no-store. Ein veralteter Plan ist nicht bloß eine alte Seite. Er kann einen Agenten zu einem Schreibvorgang führen, der jetzt eine andere Gruppe von Ressourcen betrifft.

Verwenden Sie OPTIONS nicht für diesen Zweck. RFC 9110 nutzt die Methode, um Kommunikationsoptionen zu beschreiben, nicht um einen Schreibvorgang mit einem beliebigen Body zu simulieren. Ein Dienst, der sie überlädt, verwirrt Bibliotheken, Sicherheitskontrollen und alle, die gewöhnliches HTTP-Verhalten erwarten.

Die Ausführung muss beweisen, dass der Plan noch aktuell ist

Eine Vorschau kann in der Zeit bis zur Ausführung falsch werden. Ein anderer Benutzer kann den Datensatz ändern, ein geplanter Job kann laufen, eine Berechtigung kann ablaufen oder der Agent kann die Anfrage nach dem Lesen der Antwort verändern. Das ist ein Time-of-Check-to-Time-of-Use-Problem. Eine beruhigende Vorschau beseitigt es nicht.

Binden Sie einen Plan an die bewertete Anfrage, die gelesenen Ressourcenrevisionen, die Identität des Aufrufers und eine kurze Gültigkeitsdauer. Der Server kann ein signiertes, undurchsichtiges plan_token zurückgeben oder den Plan speichern und eine Kennung zurückgeben. Undurchsichtige Tokens verhindern, dass ein Client den Plan als veränderbare Berechtigung behandelt. Gespeicherte Pläne erleichtern die Prüfung großer Auswirkungen und den Widerruf einer Genehmigung. Beide Ansätze funktionieren, wenn die Ausführung die richtigen Bedingungen erneut prüft.

Eine Antwort könnte enthalten:

{
  "mode": "preview",
  "plan_id": "plan_7f4c",
  "expires_at": "2025-06-18T14:05:00Z",
  "request_digest": "sha256:...",
  "read_revisions": [
    {"resource": "projects/prj_184", "revision": "73"}
  ],
  "executable": true
}

Bei der Ausführung muss der Dienst Aufrufer, Digest, Ablaufzeit und Revisionen prüfen. Anschließend muss er entweder den bereits genehmigten Plan atomar anwenden oder den Plan innerhalb der Schreibtransaktion neu erzeugen und mit dem genehmigten Plan vergleichen. Kann er die Gleichwertigkeit nicht garantieren, sollte er die Anfrage mit plan_stale ablehnen und eine neue Vorschau verlangen.

Erlauben Sie einem Agenten nicht, eine Anfrage für ein Subjekt in der Vorschau zu prüfen und die Plan-ID anschließend mit einem anderen Subjekt im Body auszuführen. Besser ist es, wenn die Ausführung nur die Plan-ID und eine erwartete Revision akzeptiert. So gibt es keine zweite veränderbare Kopie der Anfrage, die der Server abgleichen muss.

Für manche Änderungen lässt sich keine aussagekräftige Garantie geben. Ein Plan zum Senden einer Nachricht kann unangemessen werden, wenn sich die Adresse des Empfängers einen Moment später ändert. Ein Plan für den Aufruf eines Drittanbieterdienstes kann von einem Preis abhängen, der sich vor dem Aufruf verändert. Sagen Sie das in der Ausgabe, validieren Sie unmittelbar vor der irreversiblen Aktion erneut und verlangen Sie eine neue Entscheidung, wenn der Unterschied relevant ist.

Agenten-Workflows brauchen einen bewussten Stopp vor der Ausführung

Ein Agent sollte eine Vorschau als Entscheidungsgrundlage behandeln, nicht als Erlaubnis, den Schreibvorgang automatisch auszuführen. Der Agent braucht Regeln dafür, wann er ausführen darf, wann er die Anfrage reparieren sollte und wann er den Plan einem Menschen vorlegen muss.

Der zuverlässigsten Workflow umfasst vier Aktionen:

1. Den beabsichtigten Schreibvorgang im Vorschau-Modus mit einer Idempotenzreferenz und erwarteten Ressourcenrevisionen übermitteln.
2. Bei Blockern anhalten, dann nur die in der Antwort genannten Felder reparieren oder einen Menschen um die fehlende Absicht bitten.
3. Die geplanten Auswirkungen und Warnungen vorlegen, wenn die Operation die Genehmigungsgrenze des Teams überschreitet.
4. Nur den zurückgegebenen Plan ausführen, solange er aktuell ist, und anschließend das Ausführungsergebnis getrennt von der Vorschau erfassen.

Bei einer Genehmigung sollte die Konsequenz im Mittelpunkt stehen, kein roher JSON-Dump. Wer über die Vergabe von Zugriff entscheidet, möchte das Subjekt, die Rolle, die über Gruppenerweiterungen erreichten Ressourcen und die Dauer sehen. Die Person sollte diese Auswirkungen nicht aus einem Anfrage-Body voller IDs ableiten müssen.

Lassen Sie den Agenten nicht jede harmlose Aktion in der Vorschau prüfen und bei jeder Warnung eine Genehmigung anfordern. So entsteht eine Reihe von Karten, die niemand liest. Definieren Sie sinnvolle Grenzen in der Anwendung: irreversible Operationen, Änderungen an Zugriffen, Geld oder externer Kommunikation, große Ressourcengruppen und Aktionen, deren Auswirkungen der Dienst als unsicher markiert. Kleine, gut verstandene Änderungen kann der Agent innerhalb der eingeräumten Berechtigungen selbst ausführen.

Sallyport kann eine menschliche Entscheidung vor dem tatsächlichen HTTP- oder SSH-Aufruf eines Agents verlangen, während die Vorschau der API dieser Entscheidung eine konkrete Grundlage gibt. Die beiden Kontrollen lösen unterschiedliche Probleme: Die eine regelt, ob ein Prozess handeln darf, die andere erklärt, was der Zieldienst tun wird.

Eine fehlgeschlagene Massenänderung zeigt, warum Zusammenfassungen nicht ausreichen

Stellen Sie sich vor, ein Agent soll externe Mitarbeiter aus einer Produktions-Supportgruppe entfernen. Er findet einen Filter, der auf 37 Konten passt, und übermittelt eine Vorschau. Der Dienst gibt count: 37, valid: true und den allgemeinen Hinweis zurück, dass sich geerbte Mitgliedschaften ändern können. Ein Operator genehmigt die Aktion, weil das gewünschte Ergebnis routinemäßig klingt.

Bei der Ausführung wird die direkte Mitgliedschaft dieser 37 Konten entfernt. Vier behalten ihren Zugriff über verschachtelte Gruppen. Sechs weitere verlieren eine separate Bereitschaftsberechtigung, weil der Dienst auch eine verknüpfte Berechtigung entfernt. Ein Benachrichtigungsjob informiert alle 37 Personen darüber, dass sich ihr Zugriff geändert hat. Der Operator muss nun herausfinden, welche Auswirkungen beabsichtigt und welche verborgen waren und ob die Benachrichtigung den tatsächlichen Zugriffszustand beschrieben hat.

Die Vorschau war im engsten Sinn technisch wahrheitsgemäß. Sie versprach nicht, dass der Filter ausschließlich externe Mitarbeiter identifiziert. Trotzdem war sie eine schlechte Schnittstelle, weil sie eine Anzahl zurückgab, obwohl der Benutzer einen Mitgliedschaftsgraphen und eine Liste der Auswirkungen benötigte.

Eine bessere Antwort gruppiert das Ergebnis nach Konsequenz:

{
  "mode": "preview",
  "operation": "remove_group_members",
  "selected": 37,
  "effects": [
    {"type": "direct_membership_removed", "count": 37},
    {"type": "access_retained_via_nested_group", "subjects": ["usr_8", "usr_19", "usr_31", "usr_44"]},
    {"type": "on_call_entitlement_removed", "subjects": ["usr_2", "usr_7", "usr_11", "usr_24", "usr_29", "usr_35"]},
    {"type": "notification_queued", "count": 37}
  ],
  "validation": [
    {
      "severity": "warning",
      "code": "access_outcome_varies",
      "message": "Four selected subjects retain group-derived access."
    }
  ]
}

Bei größeren Mengen kann die richtige Antwort einen herunterladbaren Bericht oder paginierte Details enthalten. Es geht nicht darum, eine Person zum Lesen Tausender Zeilen zu zwingen. Es geht darum, außergewöhnliche und irreversible Ergebnisse vor dem Schreibvorgang sichtbar zu machen.

Dieses Beispiel zeigt auch eine häufige schlechte Empfehlung: «Verwenden Sie Dry Runs nur für destruktive Aktionen.» Teams wiederholen sie, weil Löschungen gefährlich wirken und Vorschauen Entwicklungsaufwand verursachen. Eine Berechtigungsvergabe, eine Konfigurationsänderung oder eine Benachrichtigung kann jedoch einen größeren Wirkungsradius haben als eine Löschung. Entscheiden Sie anhand von Konsequenz und Reversibilität, welche Operationen eine Vorschau brauchen, nicht anhand des HTTP-Verbs oder der Datenbankoperation.

Tests müssen Vorschau- und Ausführungseffekte vergleichen

Ein Vorschauendpunkt verfällt, wenn Tests nur beweisen, dass er eine 200-Antwort zurückgibt. Sein zentrales Versprechen ist Gleichwertigkeit: Stimmen Zustand und Anfrage überein, müssen die gemeldeten Auswirkungen mit der Ausführung übereinstimmen.

Erstellen Sie gepaarte Tests. Richten Sie ein Fixture ein, führen Sie die Vorschau aus, erfassen Sie den normalisierten Plan, setzen Sie das Fixture zurück, führen Sie dieselbe Absicht aus und vergleichen Sie das Ausführungsjournal mit der vorhergesagten Wirkungsmenge. Ignorieren Sie Felder, die vernünftigerweise nicht übereinstimmen können, etwa Serverzeitstempel oder erzeugte Korrelations-IDs. Ignorieren Sie keine erstellten Ressourcen, geänderten Werte, veröffentlichten Events, Benachrichtigungen oder ausgehenden Aufrufe.

Property-Tests helfen bei Filtern und Massenoperationen. Erzeugen Sie eine Sammlung von Ressourcen mit gemischten Zuständen, fordern Sie eine Vorschau anhand eines Prädikats an, führen Sie sie in einer frischen Kopie aus und prüfen Sie, ob ausgewählte Menge und Endzustand übereinstimmen. Diese Tests finden die unangenehmen Fälle, in denen eine Planungsabfrage eine Tabelle verknüpft, die Schreibabfrage aber eine andere.

Behalten Sie einen eigenen Test für Seiteneffekte der Vorschau bei. Verwenden Sie Testadapter für E-Mail, Webhooks, Warteschlangen und Zahlungsanbieter, die den Test fehlschlagen lassen, wenn der Vorschau-Modus sie aufruft. Führen Sie außerdem mindestens einen Integrationstest gegen die echte Persistenzschicht aus, weil ein ORM-Flush oder Trigger schreiben kann, obwohl der Anwendungscode sauber aussieht.

Testen Sie schließlich die Veraltung absichtlich. Prüfen Sie eine Änderung in der Vorschau, verändern Sie eine Ressource über eine andere Anfrage und führen Sie den alten Plan aus. Der Dienst sollte ihn ablehnen. Ein System, das einen alten Plan anwendet, weil das Diff «noch ähnlich genug aussieht», wird irgendwann die Arbeit eines anderen überschreiben.

Eine Vorschau ist eine API-Fähigkeit, kein Grund, Kontrollen auszulassen

Vorschauendpunkte verringern Überraschungen. Sie ersetzen keine Autorisierung, Nebenläufigkeitsprüfungen, Transaktionsgestaltung, Idempotenz, Audit-Trails oder Prüfungen für Operationen, die eine Prüfung verdienen. Ein Aufrufer ohne Berechtigung sollte durch Vorschauen keine detaillierte Karte geschützter Ressourcen erhalten. Ein Aufrufer, der eine Ausführungsanfrage wiederholt, sollte nicht denselben Seiteneffekt zweimal erzeugen, nur weil ein Plan-Token gültig war.

Beginnen Sie mit dem Schreibvorgang, der Ihrem Team in einer Probe oder Produktion am meisten geschadet hat. Listen Sie jede direkte und indirekte Auswirkung auf, implementieren Sie einen Plan, der sie meldet, und sorgen Sie dafür, dass die Ausführung veraltete Pläne ablehnt. Schreiben Sie anschließend den gepaarten Test, der beweist, dass Vorschau und Ausführung übereinstimmen. Wenn Sie nicht sagen können, was ein Schreibvorgang tun wird, bevor er läuft, ist nicht der Agent der riskante Teil des Systems. Es ist die API.