Seminar Kuzzle Plugin- und Backend-Framework-Entwicklung

Das Seminar entwickelt projektspezifische Geschäftslogik mit dem Kuzzle Backend Framework. Custom Controller, Services, Plugins, Hooks, Pipes, Events, Konfiguration, Secrets, Fehlerverträge, Tests, Paketierung und Release werden als wartbare Erweiterungsarchitektur umgesetzt. Theorie, Demonstration und Laborarbeit wechseln in kurzen Zyklen. Jeder technische Schritt wird durch eine Kontrollabfrage, einen Negativtest oder eine nachvollziehbare Zustandsprüfung abgeschlossen.

Inhaltsübersicht

• Zielgruppe und Voraussetzungen
• Didaktischer Zuschnitt
• Erweiterungsarchitektur und API-Vertrag
• Controller, Services und Kontextzugriffe
• Plugin-Lebenszyklus, Konfiguration und Module
• Hooks, Pipes und Custom Events
• Tests, Paketierung, Kompatibilität und Release
• Praxisprojekt und Lernerfolgskontrolle

Zielgruppe und Voraussetzungen

Kapitelinhaltsverzeichnis

• Adressierte Rollen
• Erforderliche Vorkenntnisse
• Labor- und Arbeitsmittel
• Einstiegskontrolle

Zielgruppe: Erfahrene Backend- und TypeScript-Entwicklung, Softwarearchitektur, technische Leads und Plattformerweiterung.

Voraussetzungen: Sichere TypeScript- oder JavaScript-Kenntnisse, Node.js, asynchrone Programmierung, API-Design, Tests und Kuzzle-Grundlagen.

Zu Beginn werden Vorkenntnisse, Laborzugang, Namenskonventionen und Sicherheitsregeln geprüft. Fehlende Grundlagen werden als konkrete Vorbereitungspunkte dokumentiert; produktive Systeme und reale Zugangsdaten werden in den Übungen nicht verwendet.

Didaktischer Zuschnitt

Kapitelinhaltsverzeichnis

• Begründung der Dauer
• Arbeitsweise
• Dokumentationsstandard
• Qualitätssicherung

Begründung der Dauer: Vier Tage sind erforderlich, weil API- und Serviceentwurf, Plugin-Lebenszyklus, ereignisorientierte Erweiterungen sowie Test, Paketierung und Release jeweils einen eigenen Implementierungsblock beanspruchen. Drei Tage würden den für langfristige Wartbarkeit entscheidenden Release- und Kompatibilitätsteil verkürzen.

Die Lerneinheiten folgen dem Muster Analyse, Aufbau, Funktionsnachweis, Fehlerfall und Wiederholung. Konfigurationen und Testdaten werden versionierbar gehalten. Entscheidungen werden mit Annahme, Alternative, Risiko und Prüfmethode dokumentiert. Dadurch entsteht neben dem fachlichen Verständnis ein direkt nutzbares Arbeitsverfahren.

1. Erweiterungsarchitektur und API-Vertrag

Kapitelinhaltsverzeichnis

• Standardfunktion oder Erweiterung
• Controller und Actions
• Request- und Responsevertrag
• Berechtigungen und Fehler

Dieses Kapitel verbindet Standardfunktion oder Erweiterung, Controller und Actions, Request- und Responsevertrag und Berechtigungen und Fehler. Die Arbeitsschritte werden in einer isolierten Laborumgebung ausgeführt, protokolliert und gegen einen vorher festgelegten Sollzustand geprüft. Technische Entscheidungen werden so dokumentiert, dass Umsetzung, Review und Wiederholung ohne stille Annahmen möglich bleiben.

Schritt-für-Schritt-Anleitung

1. Schritt 1 – Geschäftslogik identifizieren, die nicht sinnvoll im Client oder als reine Datenoperation liegt: Vor Beginn werden Zweck, Eingaben, Abhängigkeiten und ein messbares Erfolgskriterium notiert. Der Bezug zum behandelten Kuzzle-Funktionsbereich wird anhand des laufenden Praxisfalls nachvollzogen.
2. Schritt 2 – Controllergrenzen nach fachlicher Verantwortung und Änderungsrhythmus schneiden: Die Konfiguration wird zunächst klein aufgebaut, anschließend gespeichert und durch eine unabhängige Abfrage kontrolliert. Der Bezug zum behandelten Kuzzle-Funktionsbereich wird anhand des laufenden Praxisfalls nachvollzogen.
3. Schritt 3 – Actions mit eindeutigen Eingaben, Ausgaben und Seiteneffekten spezifizieren: Der Normalfall wird mit bekannten Testdaten ausgeführt; relevante IDs, Zeitpunkte und Rückgabewerte werden festgehalten. Der Bezug zum behandelten Kuzzle-Funktionsbereich wird anhand des laufenden Praxisfalls nachvollzogen.
4. Schritt 4 – Berechtigungsaktionen und minimal notwendige Rollen früh definieren: Mindestens ein typischer Fehlerfall wird absichtlich ausgelöst, beobachtet und ohne verdeckte manuelle Korrektur behoben. Der Bezug zum behandelten Kuzzle-Funktionsbereich wird anhand des laufenden Praxisfalls nachvollzogen.
5. Schritt 5 – Stabile Fehlerkennungen und Statuscodes für Clients festlegen: Zum Abschluss wird der Sollzustand erneut geprüft und als wiederholbare Checkliste oder automatisierter Test gesichert. Der Bezug zum behandelten Kuzzle-Funktionsbereich wird anhand des laufenden Praxisfalls nachvollzogen.

Kontrollpunkte

• Der Sollzustand für Standardfunktion oder Erweiterung ist durch eine reproduzierbare Prüfung nachgewiesen.
• Fehlkonfigurationen in Controller und Actions erzeugen verständliche und protokollierte Fehler.
• Die Umsetzung zu Berechtigungen und Fehler lässt sich ohne persönliche Einzelkenntnisse wiederholen.
• Berechtigungen, Daten und Protokolle enthalten nur die für die Aufgabe erforderlichen Informationen.

Praxisaufgabe

Eine projektspezifische API wird als versionierter Vertrag mit Berechtigungen und Fehlerfällen entworfen. Die Abnahme erfolgt anhand einer kurzen Demonstration, einer Konfigurationsprüfung und eines gezielt ausgelösten Fehlerfalls.

2. Controller, Services und Kontextzugriffe

Kapitelinhaltsverzeichnis

• Action-Implementierung
• Service-Schicht
• Requestvalidierung
• Zugriff auf Daten und Security

Dieses Kapitel verbindet Action-Implementierung, Service-Schicht, Requestvalidierung und Zugriff auf Daten und Security. Die Arbeitsschritte werden in einer isolierten Laborumgebung ausgeführt, protokolliert und gegen einen vorher festgelegten Sollzustand geprüft. Technische Entscheidungen werden so dokumentiert, dass Umsetzung, Review und Wiederholung ohne stille Annahmen möglich bleiben.

Schritt-für-Schritt-Anleitung

1. Schritt 1 – Eine Action registrieren und Eingaben vor der Fachlogik normalisieren: Vor Beginn werden Zweck, Eingaben, Abhängigkeiten und ein messbares Erfolgskriterium notiert. Der Bezug zum behandelten Kuzzle-Funktionsbereich wird anhand des laufenden Praxisfalls nachvollzogen.
2. Schritt 2 – Fachlogik in unabhängig testbare Services auslagern: Die Konfiguration wird zunächst klein aufgebaut, anschließend gespeichert und durch eine unabhängige Abfrage kontrolliert. Der Bezug zum behandelten Kuzzle-Funktionsbereich wird anhand des laufenden Praxisfalls nachvollzogen.
3. Schritt 3 – Kuzzle-Kontextzugriffe über kleine Adapter kapseln: Der Normalfall wird mit bekannten Testdaten ausgeführt; relevante IDs, Zeitpunkte und Rückgabewerte werden festgehalten. Der Bezug zum behandelten Kuzzle-Funktionsbereich wird anhand des laufenden Praxisfalls nachvollzogen.
4. Schritt 4 – Transaktionen durch idempotente Schritte und Kompensationslogik ersetzen: Mindestens ein typischer Fehlerfall wird absichtlich ausgelöst, beobachtet und ohne verdeckte manuelle Korrektur behoben. Der Bezug zum behandelten Kuzzle-Funktionsbereich wird anhand des laufenden Praxisfalls nachvollzogen.
5. Schritt 5 – Ergebnis, Fehler und Dauer strukturiert mit Request-Korrelation protokollieren: Zum Abschluss wird der Sollzustand erneut geprüft und als wiederholbare Checkliste oder automatisierter Test gesichert. Der Bezug zum behandelten Kuzzle-Funktionsbereich wird anhand des laufenden Praxisfalls nachvollzogen.

Kontrollpunkte

• Der Sollzustand für Action-Implementierung ist durch eine reproduzierbare Prüfung nachgewiesen.
• Fehlkonfigurationen in Service-Schicht erzeugen verständliche und protokollierte Fehler.
• Die Umsetzung zu Zugriff auf Daten und Security lässt sich ohne persönliche Einzelkenntnisse wiederholen.
• Berechtigungen, Daten und Protokolle enthalten nur die für die Aufgabe erforderlichen Informationen.

Praxisaufgabe

Eine eigene Action verarbeitet einen mehrstufigen Geschäftsfall mit Validierung und kontrolliertem Wiederanlauf. Die Abnahme erfolgt anhand einer kurzen Demonstration, einer Konfigurationsprüfung und eines gezielt ausgelösten Fehlerfalls.

3. Plugin-Lebenszyklus, Konfiguration und Module

Kapitelinhaltsverzeichnis

• Initialisierung und Start
• Konfiguration
• Secrets
• Wiederverwendbare Module

Dieses Kapitel verbindet Initialisierung und Start, Konfiguration, Secrets und Wiederverwendbare Module. Die Arbeitsschritte werden in einer isolierten Laborumgebung ausgeführt, protokolliert und gegen einen vorher festgelegten Sollzustand geprüft. Technische Entscheidungen werden so dokumentiert, dass Umsetzung, Review und Wiederholung ohne stille Annahmen möglich bleiben.

Schritt-für-Schritt-Anleitung

1. Schritt 1 – Initialisierung, Setup und Startphase mit zulässigen Registrierungszeitpunkten unterscheiden: Vor Beginn werden Zweck, Eingaben, Abhängigkeiten und ein messbares Erfolgskriterium notiert. Der Bezug zum behandelten Kuzzle-Funktionsbereich wird anhand des laufenden Praxisfalls nachvollzogen.
2. Schritt 2 – Konfiguration typisieren, validieren und je Umgebung extern bereitstellen: Die Konfiguration wird zunächst klein aufgebaut, anschließend gespeichert und durch eine unabhängige Abfrage kontrolliert. Der Bezug zum behandelten Kuzzle-Funktionsbereich wird anhand des laufenden Praxisfalls nachvollzogen.
3. Schritt 3 – Secrets ausschließlich über geschützte Mechanismen beziehen und niemals protokollieren: Der Normalfall wird mit bekannten Testdaten ausgeführt; relevante IDs, Zeitpunkte und Rückgabewerte werden festgehalten. Der Bezug zum behandelten Kuzzle-Funktionsbereich wird anhand des laufenden Praxisfalls nachvollzogen.
4. Schritt 4 – Wiederverwendbare Funktionen als klar abgegrenzte Module strukturieren: Mindestens ein typischer Fehlerfall wird absichtlich ausgelöst, beobachtet und ohne verdeckte manuelle Korrektur behoben. Der Bezug zum behandelten Kuzzle-Funktionsbereich wird anhand des laufenden Praxisfalls nachvollzogen.
5. Schritt 5 – Fehlende Abhängigkeiten und ungültige Konfiguration mit verständlichem Startabbruch behandeln: Zum Abschluss wird der Sollzustand erneut geprüft und als wiederholbare Checkliste oder automatisierter Test gesichert. Der Bezug zum behandelten Kuzzle-Funktionsbereich wird anhand des laufenden Praxisfalls nachvollzogen.

Kontrollpunkte

• Der Sollzustand für Initialisierung und Start ist durch eine reproduzierbare Prüfung nachgewiesen.
• Fehlkonfigurationen in Konfiguration erzeugen verständliche und protokollierte Fehler.
• Die Umsetzung zu Wiederverwendbare Module lässt sich ohne persönliche Einzelkenntnisse wiederholen.
• Berechtigungen, Daten und Protokolle enthalten nur die für die Aufgabe erforderlichen Informationen.

Praxisaufgabe

Die Erweiterung wird als konfigurierbares Plugin mit einem wiederverwendbaren Modul aufgebaut. Die Abnahme erfolgt anhand einer kurzen Demonstration, einer Konfigurationsprüfung und eines gezielt ausgelösten Fehlerfalls.

4. Hooks, Pipes und Custom Events

Kapitelinhaltsverzeichnis

• Synchrone Eingriffe
• Asynchrone Reaktionen
• Eventnamen und Payloads
• Kopplung und Fehlerfolgen

Dieses Kapitel verbindet Synchrone Eingriffe, Asynchrone Reaktionen, Eventnamen und Payloads und Kopplung und Fehlerfolgen. Die Arbeitsschritte werden in einer isolierten Laborumgebung ausgeführt, protokolliert und gegen einen vorher festgelegten Sollzustand geprüft. Technische Entscheidungen werden so dokumentiert, dass Umsetzung, Review und Wiederholung ohne stille Annahmen möglich bleiben.

Schritt-für-Schritt-Anleitung

1. Schritt 1 – Pipes nur einsetzen, wenn eine laufende Verarbeitung geprüft oder verändert werden muss: Vor Beginn werden Zweck, Eingaben, Abhängigkeiten und ein messbares Erfolgskriterium notiert. Der Bezug zum behandelten Kuzzle-Funktionsbereich wird anhand des laufenden Praxisfalls nachvollzogen.
2. Schritt 2 – Hooks für entkoppelte, asynchrone Folgeaktivitäten verwenden: Die Konfiguration wird zunächst klein aufgebaut, anschließend gespeichert und durch eine unabhängige Abfrage kontrolliert. Der Bezug zum behandelten Kuzzle-Funktionsbereich wird anhand des laufenden Praxisfalls nachvollzogen.
3. Schritt 3 – Custom Events mit Namenskonvention und versioniertem Payload definieren: Der Normalfall wird mit bekannten Testdaten ausgeführt; relevante IDs, Zeitpunkte und Rückgabewerte werden festgehalten. Der Bezug zum behandelten Kuzzle-Funktionsbereich wird anhand des laufenden Praxisfalls nachvollzogen.
4. Schritt 4 – Reihenfolge, Zeitüberschreitung und Fehlerfortpflanzung explizit testen: Mindestens ein typischer Fehlerfall wird absichtlich ausgelöst, beobachtet und ohne verdeckte manuelle Korrektur behoben. Der Bezug zum behandelten Kuzzle-Funktionsbereich wird anhand des laufenden Praxisfalls nachvollzogen.
5. Schritt 5 – Zyklische Abhängigkeiten und versteckte Seiteneffekte durch Architekturregeln verhindern: Zum Abschluss wird der Sollzustand erneut geprüft und als wiederholbare Checkliste oder automatisierter Test gesichert. Der Bezug zum behandelten Kuzzle-Funktionsbereich wird anhand des laufenden Praxisfalls nachvollzogen.

Kontrollpunkte

• Der Sollzustand für Synchrone Eingriffe ist durch eine reproduzierbare Prüfung nachgewiesen.
• Fehlkonfigurationen in Asynchrone Reaktionen erzeugen verständliche und protokollierte Fehler.
• Die Umsetzung zu Kopplung und Fehlerfolgen lässt sich ohne persönliche Einzelkenntnisse wiederholen.
• Berechtigungen, Daten und Protokolle enthalten nur die für die Aufgabe erforderlichen Informationen.

Praxisaufgabe

Eine Action löst ein Custom Event aus, das durch Pipe geprüft und durch Hook nachgelagert verarbeitet wird. Die Abnahme erfolgt anhand einer kurzen Demonstration, einer Konfigurationsprüfung und eines gezielt ausgelösten Fehlerfalls.

5. Tests, Paketierung, Kompatibilität und Release

Kapitelinhaltsverzeichnis

• Unit- und Integrationstests
• Test-Backend
• Versionierung
• Upgrade und Rollback

Dieses Kapitel verbindet Unit- und Integrationstests, Test-Backend, Versionierung und Upgrade und Rollback. Die Arbeitsschritte werden in einer isolierten Laborumgebung ausgeführt, protokolliert und gegen einen vorher festgelegten Sollzustand geprüft. Technische Entscheidungen werden so dokumentiert, dass Umsetzung, Review und Wiederholung ohne stille Annahmen möglich bleiben.

Schritt-für-Schritt-Anleitung

1. Schritt 1 – Services ohne Infrastruktur als Unit-Tests absichern: Vor Beginn werden Zweck, Eingaben, Abhängigkeiten und ein messbares Erfolgskriterium notiert. Der Bezug zum behandelten Kuzzle-Funktionsbereich wird anhand des laufenden Praxisfalls nachvollzogen.
2. Schritt 2 – Controller, Rechte, Datenzugriffe und Events in einer isolierten Integrationstestumgebung prüfen: Die Konfiguration wird zunächst klein aufgebaut, anschließend gespeichert und durch eine unabhängige Abfrage kontrolliert. Der Bezug zum behandelten Kuzzle-Funktionsbereich wird anhand des laufenden Praxisfalls nachvollzogen.
3. Schritt 3 – Kompatibilitätsmatrix für Kuzzle-, Node- und Abhängigkeitsversionen pflegen: Der Normalfall wird mit bekannten Testdaten ausgeführt; relevante IDs, Zeitpunkte und Rückgabewerte werden festgehalten. Der Bezug zum behandelten Kuzzle-Funktionsbereich wird anhand des laufenden Praxisfalls nachvollzogen.
4. Schritt 4 – Artefakt, Konfiguration und Migrationshinweise versioniert paketieren: Mindestens ein typischer Fehlerfall wird absichtlich ausgelöst, beobachtet und ohne verdeckte manuelle Korrektur behoben. Der Bezug zum behandelten Kuzzle-Funktionsbereich wird anhand des laufenden Praxisfalls nachvollzogen.
5. Schritt 5 – Gestuften Rollout, Gesundheitsprüfung und Rückfall auf die vorige Version durchführen: Zum Abschluss wird der Sollzustand erneut geprüft und als wiederholbare Checkliste oder automatisierter Test gesichert. Der Bezug zum behandelten Kuzzle-Funktionsbereich wird anhand des laufenden Praxisfalls nachvollzogen.

Kontrollpunkte

• Der Sollzustand für Unit- und Integrationstests ist durch eine reproduzierbare Prüfung nachgewiesen.
• Fehlkonfigurationen in Test-Backend erzeugen verständliche und protokollierte Fehler.
• Die Umsetzung zu Upgrade und Rollback lässt sich ohne persönliche Einzelkenntnisse wiederholen.
• Berechtigungen, Daten und Protokolle enthalten nur die für die Aufgabe erforderlichen Informationen.

Praxisaufgabe

Das Plugin wird automatisiert getestet, paketiert, aktualisiert und nach einem eingebauten Fehler zurückgerollt. Die Abnahme erfolgt anhand einer kurzen Demonstration, einer Konfigurationsprüfung und eines gezielt ausgelösten Fehlerfalls.

Praxisprojekt und Lernerfolgskontrolle

Kapitelinhaltsverzeichnis

• Projektauftrag
• Zwischenprüfungen
• Fehler- und Sicherheitsnachweis
• Technische Abnahme

Das Praxisprojekt verbindet die Kapitel zu einer konsistenten Laborlösung. Vor jedem Inkrement werden Ausgangszustand, Ziel, Eingaben und Abnahmekriterien festgelegt. Nach der Umsetzung folgen Funktionsprüfung, Negativtest, kurze Dokumentationskontrolle und Rücksetzung auf einen bekannten Zustand.

1. Projektauftrag schneiden: Ein fachlich begrenzter Anwendungsfall wird in Daten, Akteure, Schnittstellen, Berechtigungen und Betriebsanforderungen zerlegt.
2. Inkremente umsetzen: Die Kapitelbausteine werden schrittweise integriert; nach jedem Inkrement bleibt die Laborlösung lauffähig.
3. Fehler nachweisen: Mindestens ein Berechtigungs-, Daten-, Verbindungs- oder Konfigurationsfehler wird kontrolliert ausgelöst und diagnostiziert.
4. Abnahme durchführen: Eine technische Checkliste prüft Funktion, Sicherheit, Wiederholbarkeit, Protokollierung und Rückfallfähigkeit.
5. Lernstand dokumentieren: Offene Vertiefungen werden als priorisierte Aufgaben mit benötigtem Nachweis festgehalten.

Die Lernerfolgskontrolle besteht aus kurzen Verständnisfragen, beobachteten Laboraufgaben, einer Fehlersuche und der technischen Abnahme des Praxisprojekts. Bewertet werden nicht nur funktionierende Ergebnisse, sondern auch Begründung, Nachweis, sichere Fehlerbehandlung und Reproduzierbarkeit.