Architekturentscheidungsdatensätze

Last reviewed 2023-04-11 UTC

Mithilfe von Architekturentscheidungsdatensätzen (ADRs) können Sie feststellen, warum Ihre Infrastruktur- oder Anwendungsteams bestimmte Designentscheidungen treffen. In diesem Dokument wird erläutert, wann und wie ADRs verwendet werden können, wenn Sie Anwendungen in Google Cloud erstellen und ausführen.

Ein ADR erfasst die wichtigen verfügbaren Optionen, die wichtigsten Anforderungen, die der Entscheidung zugrunde liegen, und die Designentscheidungen selbst. ADRs werden häufig in einer Markdown-Datei in der Nähe der Codebasis gespeichert, die für diese Entscheidung relevant ist. Wenn jemand den Hintergrund einer bestimmten Architekturentscheidung verstehen muss, z. B. warum Sie einen regionalen GKE-Cluster (Google Kubernetes Engine) verwenden, kann er den ADR und dann den zugehörigen Codediese prüfen.

ADRs können Ihnen auch dabei helfen, zuverlässigere Anwendungen und Dienste auszuführen. Der ADR hilft Ihnen, Ihren aktuellen Status zu verstehen und Fehler zu beheben. ADRs erstellen auch eine Sammlung technischer Entscheidungen, die zukünftige Entscheidungen und Bereitstellungen erleichtern.

Einsatz von ADRs

Mit ADRs können Sie die Schlüsselbereiche verfolgen, die Ihrer Meinung nach für die Bereitstellung wichtig sind. Ihre ADRs können die folgenden Kategorien enthalten:

Bei den folgenden Entscheidungen können Sie z. B. aufgefordert werden, einen ADR zu erstellen:

  • Wie und warum wird Hochverfügbarkeit für Ihre Cloud SQL-Instanzen eingerichtet?
  • Wie erreichen Sie die Verfügbarkeit von GKE-Clustern behandelt? Verwenden Sie regionale Cluster? Verwenden Sie Canary-Releases? Warum bzw. warum nicht?

Während Sie die zu verwendenden Produkte bewerten, hilft der ADR dabei, jede Ihrer Entscheidungen zu erläutern. Sie können den ADR noch einmal prüfen, während sich das Team weiterentwickelt und mehr über den Stack erfährt und weitere Entscheidungen getroffen oder angepasst werden. Wenn Sie Anpassungen vornehmen, schließen Sie die vorherige Entscheidung und den Grund für eine Änderung ein. Dieser Verlauf zeichnet auf, wie sich die Architektur verändert hat, wenn sich die Geschäftsanforderungen weiterentwickeln oder wenn es neue technische Anforderungen oder verfügbare Lösungen gibt.

Im Folgenden werden Situationen beschrieben, in denen ADRs erstellt werden sollten:

  • Wenn Sie eine technische Herausforderung oder Frage haben und keine Grundlage für eine Entscheidung besteht, z. B. eine empfohlene Lösung, ein Standardverfahren, eine Vorlage oder eine Codebasis.
  • Wenn Sie oder Ihr Team eine Lösung anbieten, die nicht an einer Stelle dokumentiert ist, auf die das Team zugreifen kann.
  • Wenn mindestens zwei technische Optionen vorhanden sind und Sie Ihre Gedanken und Gründe für Ihre Wahl dokumentieren möchten.

Wenn Sie einen ADR schreiben, sollten Sie potenzielle Leser im Hinterkopf haben. Die primären Leser sind Mitglieder des Teams, die an der vom ADR abgedeckten Technologie arbeiten. Größere Gruppen potenzieller Leser des ADR können angrenzende Teams sein, die Ihre Entscheidungen verstehen möchten, z. B. Architektur- und Sicherheitsteams.

Sie sollten auch bedenken, dass sich die Inhaber oder Teammitglieder der Anwendung ändern können. Ein ADR hilft neuen Mitwirkenden, den Hintergrund der getroffenen technischen Entscheidungen zu verstehen. Ein ADR erleichtert außerdem die Planung zukünftiger Änderungen.

Format eines ADR

Ein typischer ADR enthält eine Reihe von Kapiteln. Ihre ADRs sollten Ihnen helfen zu erfassen, was aus Ihrer Sicht für die Anwendung und Ihre Organisation wichtig ist. Einige ADRs können eine Seite lang sein, während andere eine längere Erklärung erfordern.

Der folgende beispielhafte ADR-Entwurf zeigt, wie Sie ein ADR formatieren können, um die Informationen einzuschließen, die für Ihre Umgebung wichtig sind:

  • Autoren und das Team
  • Kontext und Problem, das Sie lösen möchten
  • Funktionale und nicht funktionale Anforderungen, die Sie erfüllen möchten
  • Potenzielles wichtiges Nutzerverhalten (CUJ), das die Entscheidung beeinflusst
  • Übersicht über die wichtigsten Optionen
  • Ihre Entscheidung und Gründe, die zu der akzeptierten Wahl geführt haben

Damit die Entscheidungen genau erfasst werden, können Sie für jede Entscheidung einen Zeitstempel einfügen, der angibt, wann die Entscheidung getroffen wurde.

Funktionsweise von ADRs

ADRs funktionieren am besten, wenn Ingenieure, Entwickler oder Anwendungsinhaber einfach auf die Informationen zugreifen können, die sie enthalten. Wenn sie eine Frage dazu haben, warum etwas auf eine bestimmte Weise getan wurde, können sie sich den ADR ansehen, um die Antwort zu finden.

Um den ADR zugänglich zu machen, hosten einige Teams ihn in einem zentralen Wiki, das auch für Geschäftsinhaber und nicht nur in ihrem Versionsverwaltungs-Repository zugänglich ist. Wenn jemand eine Frage zu einer bestimmten technischen Entscheidung hat, liefert der ADR Antworten.

ADRs funktionieren in folgenden Szenarien gut:

  • Onboarding: Neue Teammitglieder können sich problemlos über das Projekt informieren und sich den ADR ansehen, wenn sie Fragen zum Anwendungscode oder zu anderen Implementierungen haben.
  • Übergabe der Inhaberschaft: Bei einer Übertragung von Technology Stacks zwischen Teams können die neuen Inhaber frühere Entscheidungen prüfen, um den aktuellen Status zu verstehen. Der ADR kann auch dazu beitragen, eine Wiederholung derselben Diskussionspunkte zu vermeiden oder Themen in Zukunft mit Kenntnis des historischen Kontexts noch einmal zu bearbeiten.
  • Abgleich: Teams können sich an Best Practices im gesamten Unternehmen orientieren, wenn ADRs detailliert erklären, warum bestimmte Entscheidungen getroffen und Alternativen abgelehnt wurden.

Ein ADR wird häufig in Markdown geschrieben, um ihn einfach und textbasiert zu halten. Markdown-Dateien können mit Ihrem Anwendungscode in das Versionsverwaltungs-Repository aufgenommen werden.

Speichern Sie Ihre ADRs in der Nähe Ihres Anwendungscodes, idealerweise im selben Versionsverwaltungssystem. Wenn Sie Änderungen an Ihrem ADR vornehmen, können Sie bei Bedarf frühere Versionen aus der Versionsverwaltung überprüfen.

Sie können auch ein anderes Medium wie ein freigegebenes Google-Dokument oder ein internes Wiki verwenden. Diese alternativen Standorte sind möglicherweise für Nutzer besser zugänglich, die nicht zum Team des ADR gehören. Eine weitere Option besteht darin, den ADR in einem Versionsverwaltungs-Repository zu erstellen, aber wichtige Entscheidungen auch in ein zugänglicheres Wiki aufzunehmen.

Nächste Schritte