Einer mehrsprachigen Infrastructure-as-Code-Bibliothek Funktionen hinzufügen, ohne bestehende Nutzer zu stören

## Bestehenden Nutzercode lauffähig halten und die ganze Plattform zugänglich machen Arbeite für die Benutzer der Bibliothek, ihre Betreuer und das gesamte Ökosystem, nicht nur für die Person, die eine Änderung anfordert. - Bewahre die Rückwärtskompatibilität; vorhandener Benutzercode und erzeugte Infrastruktur müssen standardmäßig weiterhin funktionieren. - Beachte das Prinzip der geringsten Überraschung: APIs sollen dem gedanklichen Modell der Benutzer entsprechen. - Stelle den gesamten Funktionsumfang der Plattform bereit und biete zugleich sinnvolle, überschreibbare Standardwerte. - Erhalte einen Ausweg zum generierten ressourcennahen Grundelement, damit fehlende Funktionen der höheren Ebene Benutzer niemals blockieren. - Wenn Regeln mehrdeutig sind, halte Entscheidung und Begründung in der Änderungsbeschreibung fest, statt stillschweigend zu raten. Wenn die angeforderte Arbeit außerhalb der Codeerstellung oder -prüfung für eine solche Bibliothek liegt, halte an und weise auf die Abweichung vom Aufgabenbereich hin. Wende diese besonderen Regeln nicht auf sachfremde Arbeiten an. ## Die meisten Funktionen in die handgeschriebene API der Ebene 2 legen Bewahre drei klar getrennte Abstraktionsebenen: - Ebene 1 besteht aus generierten Hüllen um das Ressourcenschema des Anbieters. Bearbeite sie niemals von Hand. - Ebene 2 besteht aus handgeschriebenen, absichtsorientierten APIs mit nützlichen Standardwerten. Die meisten Funktionsänderungen gehören hierher. - Ebene 3 besteht aus Mustern, die mehrere Ressourcen verbinden. Füge neue Muster nur hinzu, wenn das Repository diese Abstraktionsebene ausdrücklich zulässt. Richte Ebene 2 an der Absicht der Benutzer aus und nicht am Rohschema des Anbieters. Verbirg Details des generierten Schemas, interne Verdrahtung, Berechtigungsaktionen und physische Kennungen vor gewöhnlichen Aufrufern, während der vollständige Funktionsumfang des Anbieters weiterhin zugänglich bleibt. Stelle Ressourcenverträge als Schnittstellen dar, damit Implementierungen Dritter sich wie integrierte Implementierungen verhalten können. Bevorzuge die kleinste Schnittstelle, die für einen Parameter genügt: zuerst einen Verweis nur mit Kennung, eine vollständige Verhaltensschnittstelle nur dann, wenn Komfortoperationen erforderlich sind, und konkrete Klassen nur in Ausnahmefällen. ## Für jede neue Funktion zwischen Mixin, Fassade und Trait wählen Ordne jede Funktion danach ein, worauf sie wirkt: 1. Die direkte, logikfreie Weitergabe einer ressourcennahen Eigenschaft gehört in eine schlanke Eigenschaftserweiterung. 2. Logik, die Eigenschaften oder Lebenszyklus der Ressource selbst verändert, gehört in eine eigenständige Erweiterung. 3. Verhalten für externe Verbraucher, etwa Berechtigungen, Messwerte oder Ereignisse, gehört in eine Fassade. 4. Eine übergreifende Fähigkeit, die andere Konstrukte abfragen, gehört in ein Merkmal. 5. Andernfalls verwende eine Methode des Konstrukts auf Ebene 2. Vermische diese Rollen nicht. Erweiterungen wirken nach innen, Fassaden nach außen, und Merkmale weisen auf dienstunabhängige Fähigkeiten hin. Verwende statische Typprüfungen anhand stabiler Laufzeitmarkierungen statt `instanceof`, weil Objekte Paket- oder Sprachgrenzen überschreiten können. Halte abstrakte Basisklassen für Implementierungen verfügbar, akzeptiere sie jedoch nicht als öffentliche Parameter. ## Öffentliche Namen einheitlich wählen und Typen meiden, die andere Sprachen nicht kennen Verwende einheitliche öffentliche Namen: PascalCase für Klassen und Aufzählungen, camelCase für Eigenschaften und Methoden, das Präfix `I` für Verhaltensschnittstellen, kein Präfix für Datenstrukturen und Großbuchstaben mit Unterstrichen für Aufzählungswerte. Bewahre die offizielle Plattformterminologie und gib Einheiten an, wenn kein starker Typ verfügbar ist. Eigenschaftsobjekte müssen schreibgeschützt und flach sein und nach dem Konstrukt benannt werden. Jede optionale Eigenschaft benötigt einen dokumentierten Standardwert, der das Verhalten erklärt, statt lediglich zu sagen, sie sei nicht definiert. Bevorzuge starke Typen für Dauer, Größe und Ressourcenverweise gegenüber bloßen Zahlen oder Kennungszeichenfolgen. Gib generierte ressourcennahe Typen nicht über Eigenschaften der höheren Ebene nach außen. Vermeide Vereinigungsdatentypen und andere Konstrukte, die der Generator für Sprachanbindungen nicht unterstützt; verwende stattdessen aufzählungsähnliche Klassen, getrennte Eigenschaftsobjekte oder Fabrikmethoden. Die Speicherorte öffentlicher Typdateien sind Teil des externen Vertrags. Verschiebe sie nicht leichtfertig. Vermeide abgebildete oder bedingte Typen, überladene Funktionen, sprachspezifische Namensräume und exportierte Objektkonstanten, wenn sie sich in den Zielsprachen nicht einheitlich darstellen lassen. Verwende keine verkettbaren Methoden, die `this` zurückgeben; sie lassen sich schlecht in andere Sprachen übertragen und verbergen Änderungen hinter einer Methodenkette. ## Klare Validierungsfehler melden und nicht aufgelöste Werte zuerst prüfen Verwende bereichsgebundene Validierungsfehler, wenn ein Konstruktkontext vorhanden ist, andernfalls ungebundene Validierungsfehler. Fehlercodes müssen zur Übersetzungszeit feststehende Literale sein, bei gleicher Ursache und Lösung wiederverwendbar sein, und Meldungen sollen den falschen Wert, die erwarteten Werte und die nötige Korrektur nennen. Bevorzuge die automatische Korrektur sicherer Konfigurationen gegenüber dem Auslösen eines Fehlers. Scheitere bei API-Fehlgebrauch frühzeitig, füge für angesammelten Zustand eine Validierung nach der Konstruktion hinzu und gib bei Umgebungsproblemen Diagnosen während der Infrastrukturerzeugung aus. Fange nicht behebbare Konstruktionsfehler nicht ab; stelle tatsächlich behebbare Ergebnisse in Rückgabewerten dar. Nicht aufgelöste Werte können Zeichenfolgen, Zahlen, Listen oder Ressourcenattribute darstellen. Prüfe vor der Validierung von Länge, Wertebereich, Iteration oder Wahrheitswert, ob ein Wert nicht aufgelöst ist. Listen mit Platzhaltern können Markierungslängen zeigen, und skalare Werte mit Platzhaltern können fälschlich als falsch erscheinen. Prüfe optionale Werte ausdrücklich auf Nichtdefiniertheit, verwende eine platzhalterfähige Zahlenumwandlung und beziehe niemals nicht aufgelöste Ressourcenattribute in Hashwerte für physische Namen ein. Verwende für nach der Konstruktion angesammelten Zustand einen Behälter für verzögerte Werte, der die Aufrufstellen von Änderungen erfasst. Nutze Listen-, Wert-, Zuordnungs- oder Mengenbehälter; übergib sie über Platzhalteradapter an ressourcennahe Eigenschaften; ändere sie über Behälteroperationen; und verändere den Konstruktbaum niemals innerhalb eines verzögerten Rückrufs oder Behälterrückrufs. ## Berechtigungen eng halten und Verhaltensänderungen mit Funktionsschaltern absichern Bevorzuge konkrete Berechtigungsaktionen gegenüber dienstweiten Platzhaltern, begrenze Ressourcenkennungen auf das engstmögliche Präfix und gruppiere zusammengehörige Aktionen nach Ressourcenbereich. Verwende die Berechtigungshilfen der Bibliothek, statt Richtlinienanweisungen von Hand zusammenzusetzen. Vertrauensrichtlinien müssen Bedingungen für das Quellkonto und die Quellressource enthalten, wenn das Risiko eines Stellvertreterangriffs besteht. Berechtigungen für Verschlüsselung sollen die Nutzung auf den vorgesehenen Dienst beschränken. Gib während der Infrastrukturerzeugung eine Warnung aus, sobald eine Konfiguration öffentlichen Zugriff schafft. Wenn sich das beobachtbare Verhalten einer bestehenden API ändert, sichere die Kompatibilität mit einem Funktionsschalter: - Verwende einen Fehlerkorrekturschalter, wenn das alte Verhalten falsch war. - Verwende einen Schalter für API-Standardwerte, wenn das alte Verhalten weiterhin gültig, aber nicht mehr empfohlen ist, und dokumentiere die Kompatibilität mit dem alten Verhalten. - Nicht konfigurierte Anwendungen müssen ihr bisheriges Verhalten beibehalten. - Sicherheitsschalter dürfen Vertrauen oder Berechtigungen einschränken, sie aber nicht stillschweigend erweitern; umfassenderer Zugriff erfordert eine ausdrückliche API-Option. Verwende einen Schalter nicht allein deshalb, weil ein Ersatzkonstrukt vorhanden ist. Kennzeichne stattdessen das alte Konstrukt als veraltet und warne über den üblichen Anmerkungsmechanismus vor Verhaltensänderungen. ## Zuerst das betroffene Paket bauen und Integrations-Snapshots aktualisieren Erstelle das betroffene Paket, bevor du Tests, Stilprüfungen, Integrationsmomentaufnahmen oder Prüfungen von Dokumentationsbeispielen ausführst. Verwende während der Arbeit das engste passende Modul oder Testziel; kehre vor der Übergabe zu den vom Repository verlangten Paket- und Kompatibilitätsprüfungen zurück. Kenne die generierten Dateien, die Speicherorte stabiler und experimenteller Integrationstests und die für Agenten bestimmten Entwurfsreferenzen, die Vorrang vor längeren, für Menschen bestimmten Leitfäden haben. Bearbeite generierte Quellen der Ebene 1 niemals direkt. Verwende die paketbezogenen Befehle und Arbeitsverzeichnisse des Repositorys, statt eigene Erstellungswege zu erfinden. Führe automatische Korrekturen von Stilprüfungen nur aus, wenn die daraus entstehenden Änderungen im angeforderten Umfang bleiben. Wenn du logische Kennungen änderst, aktualisiere alle betroffenen Integrationsmomentaufnahmen, einschließlich paketübergreifender Momentaufnahmen. Ein erfolgreicher lokaler Komponententest belegt nicht, dass generierte Sprachanbindungen, Dokumentationsbeispiele oder Integrationsvorlagen weiterhin übersetzt werden können. ## Jede neue öffentliche API dokumentieren und Beispiele kompilierbar halten Dokumentiere jede neue öffentliche Klasse, Methode, Eigenschaft und Schnittstelle. Verwende eine knappe Zusammenfassung, danach eine Leerzeile und einen erläuternden Text. Füge bei Bedarf Kennzeichnungen für Parameter, Rückgabewert, Standardwert, Querverweis, Beispiel und generiertes Attribut hinzu. Attributnamen sollen mit dem Ressourcentyp beginnen, statt mehrdeutige Namen zu verwenden. Übernimm nach Möglichkeit maßgebliche Plattformbeschreibungen, aber dupliziere keine Dokumentation für Überschreibungen, die sie von einer Basisschnittstelle erben. Jeder Modulleitfaden soll den Reifegrad nennen, nahe am Anfang ein einfaches Beispiel zeigen und Beispiele für die wichtigsten Anwendungsfälle enthalten. Alle gewöhnlichen typisierten Beispiele müssen übersetzbar sein; verwende die ausdrückliche Ausnahmemarkierung des Repositorys nur, wenn eine Prüfvorrichtung tatsächlich nicht anwendbar ist. Jede Funktionsänderung muss den entsprechenden Modulleitfaden aktualisieren. Reiner Dokumentationstext ersetzt keine API-Tests, und eine API-Implementierung rechtfertigt keine veralteten Beispiele. ## In Komponententests bestimmte Eigenschaften gezielt prüfen und Integrationstests ergänzen Prüfe in Komponententests die konkreten erzeugten Eigenschaften, auf die es ankommt, statt vollständige Vorlagen zu vergleichen oder beliebige Werte zu akzeptieren. Verwende bewusst Prüfer für Teilobjekte, exakte Objekte, Felder, reguläre Ausdrücke und Abwesenheit. Decke Grenzwerte mit datengesteuerten Tests ab. Fehlertests müssen die genaue Diagnose prüfen und das Fehlerverhalten im Testnamen nennen. Teste Hilfsfunktionen getrennt von Konstrukten und bewahre Tests für veraltete APIs. Neue optionale Eigenschaften erfordern Rückwärtskompatibilitätstests, die belegen, dass das Standardverhalten unverändert bleibt. Berechtigungshilfen müssen mit neu erstellten und importierten Rollen, Benutzern und Dienstprinzipalen getestet werden. Integrationstests sollen das Integrationstest-Konstrukt des Repositorys ohne zusätzlichen Aufruf zur Infrastrukturerzeugung verwenden. Prüfungen werden für alle neuen Tests bevorzugt und sind für benutzerdefinierte Ressourcen vorgeschrieben. Vermeide offene Netzwerkteilnehmer, außer wenn offener Zugriff das geprüfte Verhalten ist. Füge Integrationsabdeckung für neue generierte Ressourcentypen oder -eigenschaften, dienstübergreifendes Verhalten, neue Versionen und benutzerdefinierte Ressourcen hinzu. Trenne Tests nach Funktionsbereich und halte Erweiterungen sowie Speicherorte der Momentaufnahmen einheitlich. ## Änderungstitel mit Issue schreiben und stabile Kennungen nie ändern Verwende herkömmliche Änderungstitel und nenne gegebenenfalls das betroffene Modul. Funktions- und Fehlerkorrekturen müssen auf einen Vorgang verweisen. Funktionsänderungen erfordern Komponententests, Integrationsmomentaufnahmen und Aktualisierungen der Moduldokumentation. Inkompatible Änderungen sind nur in ausdrücklich experimentellen Paketen zulässig und müssen in der Änderungsbeschreibung deutlich angekündigt werden. Behandle pro Änderung nur ein Anliegen; reiche rein optische Änderungen getrennt ein. Füge niemals spekulative Abstraktionen hinzu, ändere keine stabilen Konstruktkennungen, lasse keinen auskommentierten oder ungenutzten Code stehen und unterdrücke keine Stilregeln, um Verstöße zu verbergen. Änderungen an Kennungen können bereitgestellte Ressourcen ersetzen und Datenverlust verursachen. Bevor du einer bestehenden API eine Validierung hinzufügst, ermittle, ob zuvor akzeptierte Eingaben erfolgreich bereitgestellt werden konnten. Falls ja, sichere die neue Ablehnung durch einen Kompatibilitätsschalter ab. Falls die Bereitstellung immer scheiterte, bevorzuge einen frühen Fehler bei der Infrastrukturerzeugung und dokumentiere, warum die strengere Validierung gerechtfertigt ist. Prüfe vor der Übergabe die Änderungen auf Bearbeitungen generierter Dateien, Verschiebungen öffentlicher Typen, mit Sprachanbindungen unvereinbare Syntax, veraltete Momentaufnahmen, fehlende Dokumentation, Kompatibilitätsrückschritte und sachfremde Änderungen.