Subject-Benennung

Inhaltsverzeichnis

Subject-Hierarchie-Design

Die Benennung von Subjects ist die API Ihres Messaging-Systems. Eine gut durchdachte Hierarchie ermöglicht effizientes Routing, Filtern und Zugriffskontrolle und bleibt dabei für Entwickler intuitiv.


Designprinzipien

PrinzipBegründung
HierarchischWildcard-Abonnements auf jeder Ebene ermöglichen
VorhersehbarEntwickler können Subjects ohne Nachschlagen konstruieren
UmgebungsbewusstProduktion von Staging/Entwicklung trennen
FilterbarEin Fahrzeug, eine Gruppe oder die gesamte Flotte abonnieren
ErweiterbarNeue Nachrichtentypen ohne Umstrukturierung hinzufügen

Zentrales Subject-Muster

Alle Flotten-Subjects folgen diesem Muster:

fleet.<env>.veh.<vid>.<category>.<type>
SegmentBeschreibungBeispiele
fleetRoot-NamespaceImmer “fleet”
<env>Umgebungprod, staging, dev
vehRessourcentypFahrzeuge (zukünftig: gcs für die Bodenkontrolle)
<vid>Fahrzeug-IDVID-001, drone-alpha-7
<category>Nachrichtenkategoriestate, evt, cmd, cmdack
<type>Spezifischer Typposition, battery, takeoff

Nachrichtenkategorien

Zustand: fleet.<env>.veh.<vid>.state.*

Aktueller Fahrzeugzustand, wird kontinuierlich veröffentlicht:

SubjectBeschreibungRate
state.positionLat/Lon/Alt, Geschwindigkeit10 Hz
state.attitudeRoll/Pitch/Yaw10 Hz
state.batterySpannung, Strom, Restkapazität1 Hz
state.modeFlugmodus (AUTO, MANUAL, RTL)Bei Änderung
state.healthZusammenfassung des Systemzustands1 Hz

Beispiel für eine Veröffentlichung:

subject := fmt.Sprintf("fleet.prod.veh.%s.state.position", vehicleID)
nc.Publish(subject, positionJSON)

Ereignisse: fleet.<env>.veh.<vid>.evt.*

Einzelne Vorkommnisse, werden veröffentlicht, sobald sie eintreten:

SubjectBeschreibung
evt.armedFahrzeug scharfgeschaltet
evt.disarmedFahrzeug entschärft
evt.takeoffStart eingeleitet
evt.landedLandung abgeschlossen
evt.waypointWegpunkt erreicht
evt.failsafeFailsafe ausgelöst
evt.geofenceGeofence-Verletzung
evt.battery.lowWarnung bei niedrigem Akkustand

Ereignisse sind Zustandsübergänge, keine kontinuierlichen Daten. Sie sind dauerhaft – sie werden für Audit-Trails in JetStream gespeichert.

Befehle: fleet.<env>.veh.<vid>.cmd.*

An Fahrzeuge gesendete Anweisungen:

SubjectBeschreibung
cmd.armMotoren scharfschalten
cmd.disarmMotoren entschärfen
cmd.takeoffStart einleiten
cmd.landLandung einleiten
cmd.rtlRückkehr zum Startpunkt
cmd.gotoZu Position navigieren
cmd.mission.uploadMission hochladen
cmd.mission.startMission starten
cmd.param.setParameter setzen

Befehle fließen abwärts vom Flottenmanagement zu den Fahrzeugen.

Befehlsbestätigungen: fleet.<env>.veh.<vid>.cmdack.*

Antworten auf Befehle:

SubjectBeschreibung
cmdack.armErgebnis des Scharfschaltbefehls
cmdack.takeoffErgebnis des Startbefehls
cmdack.gotoErgebnis des Goto-Befehls

Der Ack-Payload enthält:

{
  "cmd_id": "cmd-123456",
  "status": "accepted|rejected|completed|failed",
  "error": "optional error message",
  "timestamp": "2024-01-15T10:30:00Z"
}

Wildcard-Abonnements

NATS-Wildcards ermöglichen flexible Abonnements:

WildcardBedeutungBeispiel
*Einzelnes Tokenfleet.prod.veh.*.state.position
>Ein oder mehrere Tokensfleet.prod.veh.VID-001.>

Gängige Abonnementmuster

MusterAnwendungsfall
fleet.prod.veh.*.state.positionAlle Fahrzeugpositionen
fleet.prod.veh.VID-001.>Alles von einem Fahrzeug
fleet.prod.veh.*.evt.>Alle Ereignisse von allen Fahrzeugen
fleet.prod.veh.*.state.batteryAlle Batteriezustände
fleet.*.veh.VID-001.>Ein Fahrzeug über alle Umgebungen hinweg

KV-Stores: Digital-Twin-Shadow

JetStream-KV-Stores verwalten den gewünschten und den gemeldeten Zustand:

Subject-Muster (KV)

fleet/<env>/veh/<vid>/desired
fleet/<env>/veh/<vid>/reported

Hinweis: KV verwendet das Trennzeichen / (Bucket-Pfad), während Pub/Sub das Trennzeichen . verwendet.

Gewünschter Zustand

Was das Fahrzeug nach dem Willen des Flottenmanagementsystems tun soll:

{
  "mode": "AUTO",
  "mission_id": "mission-456",
  "geofence_enabled": true,
  "max_altitude": 120,
  "home_position": {
    "lat": 37.7749,
    "lon": -122.4194
  }
}

Gemeldeter Zustand

Was das Fahrzeug tatsächlich meldet:

{
  "mode": "AUTO",
  "mission_id": "mission-456",
  "mission_progress": 0.45,
  "geofence_enabled": true,
  "armed": true,
  "in_flight": true,
  "battery_remaining": 0.72
}

Shadow-Abgleich

Das Vehicle Gateway führt kontinuierlich folgende Schritte aus:

  1. Liest den gewünschten Zustand aus dem KV
  2. Vergleicht ihn mit dem tatsächlichen Fahrzeugzustand
  3. Sendet Befehle, um die Realität an den gewünschten Zustand anzugleichen
  4. Aktualisiert den gemeldeten Zustand

Dies ermöglicht deklaratives Flottenmanagement – den gewünschten Zustand festlegen und die Fahrzeuge darauf zusteuern lassen.


Zugriffskontrolle

Die NATS-Autorisierung ordnet Benutzern die erlaubten Subjects zu:

# Vehicle can publish its own state/events
publish: fleet.prod.veh.VID-001.state.>
publish: fleet.prod.veh.VID-001.evt.>
publish: fleet.prod.veh.VID-001.cmdack.>

# Vehicle can subscribe to commands for itself
subscribe: fleet.prod.veh.VID-001.cmd.>

# Vehicle can read/write its own shadow
kv: fleet/prod/veh/VID-001/*
# Fleet operator can subscribe to all state/events
subscribe: fleet.prod.veh.*.state.>
subscribe: fleet.prod.veh.*.evt.>
subscribe: fleet.prod.veh.*.cmdack.>

# Fleet operator can publish commands
publish: fleet.prod.veh.*.cmd.>

# Fleet operator can manage shadows
kv: fleet/prod/veh/*/desired

Dies stellt sicher, dass Fahrzeuge sich nicht als andere Fahrzeuge ausgeben oder unautorisierte Befehle veröffentlichen können.

Eine ausführliche Darstellung des Autorisierungsmodells, einschließlich Berechtigungen für Dritte und Verwaltung von Anmeldedaten, finden Sie unter Autorisierung & Berechtigungen.


Abwägungen beim Subject-Design

Warum keine flachen Subjects?

Flache Subjects wie vehicle-001-position unterstützen Folgendes nicht:

  • Wildcard-Abonnements
  • Hierarchische Zugriffskontrolle
  • Logische Gruppierung

Warum keine tiefere Hierarchie?

Subjects wie fleet.prod.region.us-west.site.warehouse-a.veh.VID-001.state.position:

  • Sind programmatisch schwieriger zu konstruieren
  • Machen Wildcards komplex
  • Führen dazu, dass sich Änderungen durch das gesamte System ziehen

Die vierstufige Hierarchie schafft ein Gleichgewicht zwischen Flexibilität und Einfachheit.


Nachrichtenformat

Alle Nachrichten verwenden JSON mit einheitlicher Struktur:

{
  "vid": "VID-001",
  "timestamp": "2024-01-15T10:30:00.123Z",
  "seq": 12345,
  "data": {
    // message-specific payload
  }
}
FeldBeschreibung
vidFahrzeug-ID (redundant zum Subject, aber nützlich für Consumer)
timestampISO 8601 mit Millisekundengenauigkeit
seqMonotone Sequenznummer für die Reihenfolge
dataNachrichtenspezifischer Payload

Zusammenfassung

KategorieSubject-MusterRichtung
Zustandfleet.<env>.veh.<vid>.state.<type>Fahrzeug → Hub
Ereignissefleet.<env>.veh.<vid>.evt.<type>Fahrzeug → Hub
Befehlefleet.<env>.veh.<vid>.cmd.<type>Hub → Fahrzeug
Acksfleet.<env>.veh.<vid>.cmdack.<type>Fahrzeug → Hub
Gewünschtfleet/<env>/veh/<vid>/desired (KV)Hub → Fahrzeug
Gemeldetfleet/<env>/veh/<vid>/reported (KV)Fahrzeug → Hub

Weiter

Stream-Konfiguration →