Schema First Design – Produktentwicklung mit GraphQL

Zu den schwierigsten Aufgaben bei der Entwicklung neuer Produkte gehören die Koordinierung der Teams, der Featureumfang und unbekannte Faktoren in Form der „moving parts“. Laut Definition müssen wir bestimmte laufende Prozesse berücksichtigen. Ein gutes Beispiel sind Konzerne, die über verschiedene Bereiche hinweg agieren müssen und unterschiedliche Ansprechpartner mit diversen Vorstellungen und Intentionen bereitstellen.

Wir müssen sicherstellen, dass wir uns in dieselbe Richtung bewegen, mit den gleichen Zielvorstellungen, was im ersten Moment simpel klingt, aber im Alltag eine unserer schwierigsten Aufgaben ist. Wir müssen zusammen mit unseren Kunden die gleiche Sprache sprechen und uns in der gesetzten Domäne zurechtfinden. Für uns ist dies eine Grundvoraussetzung, um erfolgreich Projekte zu stemmen.

Gibt es eine Lösung für dieses Problem? Die Voraussetzung sollte eine Single Source of Truth, unser gemeinsames Working-Agreement, sein. Dabei kommt das Prinzip Schema First Design zum Einsatz und soll in der Entwicklung das gleiche Setup für die Teams bereitstellen. Ein gemeinsames Ziel muss definiert werden und eine Informationsquelle, die eindeutig ist. Ich versuche die Herangehensweise zu beschreiben und gebe einige Werkzeuge mit auf den Weg, damit wir dieses Ziel erreichen können.

Anmerkung: Ein weiterer Artikel zum Thema GraphQL folgt in Kürze. Bei Fragen könnt ihr euch gerne an mich wenden.

Traditionelle Entwicklung und einhergehende Probleme

Damit wir die Definition von Schema First Design besser nachvollziehen können, müssen wir vorerst Probleme aus bisher bekannten Projekten heranziehen und die entsprechenden Learnings, die daraus resultieren.

Bei der Entwicklung im klassischen Stil ist die Entwicklung häufig auf verschiedene Teams aufgeteilt und manchmal auch über verschiedene Bereiche verstreut. Ein gemeinsames Ziel wird definiert, ist teilweise sehr allgemein innerhalb der Teams kommuniziert und geht nicht auf wichtige Details ein. Ein Beispiel wäre die Aussage: „Wir entwickeln eine Applikation die benutzerspezifische Anfragen bearbeiten und speichern soll.“

Eine solche Zielsetzung kann zu Irrtümern in den Teams führen und ist sehr vage in der Definition wie entwickelt wird und welche Akzeptanzkriterien erfüllt werden müssen. Auf Entwickler- und Kundenseite kann hier schnell aneinander vorbei kommuniziert werden.

Die Idee des SFDs ist ein einheitliches Mindset durch alle Abteilungen hinweg zu etablieren und eine kollaborative, aber unabhängige Arbeitsweise zu festigen. In der Realität sieht es häufig anders aus und die Teams entwickeln teilweise nach unterschiedlichen Paradigmen, kommunizieren nicht ausführlich genug und bewegen sich im schlechtesten Fall in unterschiedliche Richtungen. Noch verrückter wird die Situation wenn sich bestimmte Teams in einer Art Wettstreit befinden. Ein Team wartet auf die Zuarbeiten des anderen und priorisiert ein entsprechendes Feature niedriger, weil es nicht fertiggestellt wurde. Stellt man dies fest, sollte man umgehend handeln, denn sonst kommt es zum Featurestau und das komplette Projekt kann scheitern. Eine Situation die jeder schon durch hat und die exemplarisch dafür ist, sind Veränderungen an Featureanforderungen, Umpriorisierung des Scopes… und schon haben wir die perfekte Formel für ein Fiasko im laufenden Projekt.

Diese Probleme bestehen aber nicht nur zwischen den umzusetzenden Teams. Die technische Sichtweise ist nur eine, die wir berücksichtigen müssen. Hinzu kommen die Anforderungen auf der Businessseite des Kunden und die Erwartungen der Stakeholder, die wir stets im Fokus haben. Ein klares Setup, was möglich ist und welche Einschränkungen wir im Auge behalten müssen, sollte gesetzt sein. Im weiteren Verlauf des Projektes werden wir auf neue Probleme stoßen. Aktualisierung der Dokumentation anhand neuer Features, neue Inhalte einstellen oder erneuern und Neuanforderungen an bestehende Funktionalitäten. Bei der vorher beschriebenen Arbeitsweise hemmt es die Produktivität der Teams, und entsprechende Umsetzungen werden unnötig erschwert.

Genau an diesem Punkt des initialen Setups kommt unser Schema zum Einsatz; ein Vertrag, eine eindeutige Vereinbarung. Diskutieren wir das Thema Schema, sprechen wir über eine Organisation as Code. Ein klar definiertes System, mit bekannten Einschränkungen, für das Design und die Funktionalität einer Applikation, unsere Blaupause. Ein Schema in unserem Kontext definiert Datentypen, ihre spezifischen Interaktionen und davon abgeleitete Funktionalität.

Schema First Development

Diese Herangehensweise etabliert eine Art Vertrag zwischen den Entwicklern und den operationellen Anforderungen des Kunden. Ziel dieses Vertrages ist es, die Einschränkungen und Anforderungen an das Projekt abzubilden und als Arbeitsgrundlage für alle Bereiche zu fungieren.

Ein weiteres Ziel ist ein sogenanntes „Self-documented Schema“ zu erzeugen und entsprechende Anforderungen daraus zu erkennen. Dafür nutze ich in meinem Beispiel die Schema Definition Language , da sie einen wesentlichen Bestandteil von GraphQL APIs darstellt. Somit bildet sie unseren initialen Startpunkt für die Kommunikation zwischen Back- und Frontend. Der Vorteil liegt hierbei an der entkoppelten Arbeitsweise, denn das Backend kann die SDL nutzen, um ihre Logik zu implementieren, damit entsprechende Resolver-Funktionen bereitgestellt werden. Das Frontend kann dank der SDL und Introspectionsupport Ausgaben validieren und Daten einfach mit Services wie faker.js mocken. Dies kann auch geschehen, bevor das Backend die Resolver zur Verfügung stellt.

In diesem Schema lässt sich erkennen, dass wir zwei Objekttypen benötigen und in welchem Zusammenhang diese zueinander stehen. Schön zu sehen sind die Datentypen, die gesetzt werden. Wir wissen, dass ein Name nur ein String sein kann und durch das Ausrufezeichen ein benötigter Parameter ist. Ein Produkt kann ebenso den Objekttypen einer Kategorie besitzen.

Von diesem Punkt an können wir weitere Objekte modellieren, Relationen definieren, Funktionen ableiten und in welchem Kontext diese zueinander stehen.

Vorteile durch Schema First Design

1.) Definierter Entwicklungsprozess

Durch die Modellierung der Daten in ein Schema bringen wir die Teams dazu, sich über die verschiedenen Optionen auszutauschen und ein einheitliches Bild der Struktur zu erschaffen. In der laufenden Entwicklung wird anfangs die direkte Kommunikation vermehrt stattfinden, doch mit dem wachsenden Schema und der Etablierung der Arbeitsweise erklären sich viele Dinge von selbst und benötigen weniger Kommunikationsbedarf. Durch die Definition des Vertrages und den einhergehenden Spezifikationen werden im Entwicklungsverlauf viele Dinge selbstverständlich.

Note to remind: Schema First Design etabliert definierte Entwicklungsprozesse und verhindert einen Scope Drift oder Featurecreep.

2.) Schnellere Entwicklung

Ein riesiger Vorteil liegt in der Definition der Daten, ihren Typen, den einhergehenden Funktionen und unserem gültigen Vertrag in Form der SDL. Frontend-Teams erkennen anhand des Schemas, welche Daten zur Verfügung stehen werden und können diese bereits in ihren Komponenten einbauen und mit Daten mocken. Somit muss man nicht auf die Implementierung im Backend warten. Sollten sich Endpoints ändern, hat dies bei unserem Ansatz auch nur minimale Auswirkungen, denn der Vertrag der Datenstruktur ist verbindlich, und im Normalfall sollte nur die URL zum Endpoint umgestellt werden müssen. Gleiches gilt auch in umgekehrter Richtung und aus der Perspektive des Backends. Kein Warten auf die Implementierung einer bestimmten Visualisierung, denn wir kommunizieren über unseren Vertrag, und die Darstellung ist somit für das Backend unwichtig. Sind diese Voraussetzungen erfüllt, können beide Seiten unabhängig arbeiten, und es sorgt für eine enorme Steigerung der Produktivität.

Note to remind: Schema First Design reduziert Verzögerungen in der Entwicklung und beschleunigt den Prozess.

3.) Clean Code

Unser Vertrag sorgt dafür, dass unsere Entwicklungen sauberer werden, da es eine allgemeine Vereinbarung in Form unseres Schemas gibt. Die Adaption des Schema First Design hat den positiven Effekt, inkompatible Codefragmente, Fehler zwischen Endpunkten und Resolvern zu vermeiden. Durch die Vereinbarung der Teams auf ein gemeinsames Schema werden Fehler reduziert und die Definition von Funktionalitäten und Abhängigkeiten sind darin geklärt. Dieser Ansatz kann ebenfalls dazu beitragen, das DRY-Pattern zu implementieren und duplicated Code zu vermeiden.

Note to remind: Schema First Design führt zu besserem Code, da Funktionalitäten und Abhängigkeiten im Schema festgehalten und dokumentiert sind.

4.) Ressourcenkapazität

Ein riesiger Vorteil ist das Schema auch in Hinsicht auf die Kollaboration mit externen Teams oder das Aufgleisen neuer Teams in das Projekt. Das Schema bietet auch hier wieder den Vorteil, schnell dasselbe Mindset über Struktur und Funktionalität zu etablieren. Man kann es auch mit einer Fremdsprache, die bestimmte Grammatik und Rechtschreibung voraussetzt, vergleichen. Die Regeln sind klar definiert.

Note to remind: Schema First Design erlaubt die Erzeugung einer wichtigen Datenquelle in Form von Dokumentation oder eines automatisch generierten Schemas für die weitere Arbeit mit anderen Teams als valide Arbeitsgrundlage.

5.) Single Source of Truth

All diese Vorteile münden letzten Endes in dem Ansatz der Single Source of Truth. Grob zusammengefasst kann man die SSoT als strukturiertes Informationsmodell und Schema mit klaren Datenelementen bezeichnen. Wir vermeiden somit mehrere Datenquellen und binden uns an das validierte Schema, das durch Entwicklerteams und Kunden definiert wurde, und die daraus resultierenden Funktionalitäten und Abhängigkeiten.

Sie ist unsere „lingua franca“ mit definierten Zielen und bietet uns eine Entscheidungshilfe bei neuen Umsetzungen, dient aber auch als Referenz für weitere Features. Wir können es auch praktisch festhalten, es gibt keine Desktop-, Mobil- oder Smartmediadatenquelle – alles basiert auf unserer Single Source of Truth.

Abschließende Gedanken

Schema First Design erlaubt es uns, die Ziele der Kunden mit denen der Entwickler oder anderer Beteiligter abzugleichen und auf einen gemeinsamen Nenner zu bringen. Der Ansatz dient als Richtlinie der Entwicklung, Featureplanung oder Scopeerweiterung. Ohne eine klare Definition und Übersicht des definierten Ziels kann ein Projekt schnell eskalieren und nicht entsprechend professionell und in gewünschter Qualität umgesetzt werden. Der Ansatz des Schema First Design – auch in Kombination mit Design Thinking und den einhergehenden Design Sprints – ist ein mächtiges Werkzeug in der heutigen Entwicklung.

Was haltet ihr von diesem Ansatz und ist eine Single Source of Truth von Vorteil, oder welche Nachteile und Erfahrungen habt ihr bereits mit diesem Ansatz gefahren? Lasst es mich in den Kommentaren wissen und wir diskutieren.