Zum Hauptinhalt springen

Einführung

Kugelblitz ist eine Spring Boot-Anwendungsvorlage, mit der wir mit minimalem Aufwand einen REST-JSON-API-Webdienst einrichten können. Ziel ist die schnelle Produktion eines Persistenz-Webservices mit allen Elementen moderner Microservices. Zu den folgenden Funktionen gehören:

  • Explizite Schnittstelle: Kugelblitz unterstützt speziell impersonationsfreie CRUD-Operationen.
  • Technologieunabhängige API: In einer Welt ständiger und schneller Veränderungen benötigt Kugelblitz keine Integrationstechnologie, die vorgibt, welcher Technologie-Stack für Interaktionen verwendet werden soll.
  • Einfach: Kugelblitz bietet Kunden volle Freiheit bei der Technologiewahl durch API Doc Badge.

Kugelblitz ist konzipiert für:

  • Nicht-geschäftliche Persistenzfunktionen, die Funktionen maximieren und gleichzeitig die konzeptionelle Komplexität minimieren (alles basiert auf bestehenden Best Practices; keine neuen Konzepte werden entwickelt).
  • Performance-Caching.

Es ist nicht für:

  • Sicherheitsaspekte wie Authentifizierung oder Autorisierung.
  • jegliche Logik der Geschäftsebene.

Aus diesem Grund eignet sich Kugelblitz für eine Microservice-Architektur.

Schnellstart​

Podman-Image abrufen​

wget https://kugelblitz.openml.io/openml-kugelblitz.tar
podman load -i openml-kugelblitz.tar

Umgebungsvariablen festlegen​

tipp
  • Sie können die Werte von KUGELBLITZ_ARANGO_USERNAME und KUGELBLITZ_ARANGO_PASSWORD jederzeit ändern. Die folgenden Werte sind lediglich Beispiele.
  • Bitte ändern Sie jedoch NICHT die Werte http://arango-db:8529 und $KUGELBLITZ_ARANGO_PASSWORD.
export KUGELBLITZ_ARANGO_HOSTS=http://arango-db:8529 && \
export KUGELBLITZ_ARANGO_USERNAME=root && \
export KUGELBLITZ_ARANGO_PASSWORD=root && \
export ARANGO_ROOT_PASSWORD=$KUGELBLITZ_ARANGO_PASSWORD

Dienste hochfahren​

Speichern Sie die unten stehende Referenz compose.yaml für die Produktion. Führen Sie einfach Folgendes aus:

services:
  kugelblitz:
    image: localhost/openmlio-kugelblitz
    ports:
      - "8080:8080"
    environment:
      KUGELBLITZ_ARANGO_HOSTS: ${KUGELBLITZ_ARANGO_HOSTS}
      KUGELBLITZ_ARANGO_USERNAME: ${KUGELBLITZ_ARANGO_USERNAME}
      KUGELBLITZ_ARANGO_PASSWORD: ${KUGELBLITZ_ARANGO_PASSWORD}
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/actuator/health"]
      timeout: 10s
      retries: 10
    depends_on:
      arango-db:
        condition: service_healthy

  arango-db:
    image: arangodb:latest
    ports:
      - "8529:8529"
    environment:
      ARANGO_ROOT_PASSWORD: ${ARANGO_ROOT_PASSWORD}
    volumes:
      - arango-data:/var/lib/arangodb3
      - arango-app:/var/lib/arangodb3-apps
    healthcheck:
      test: [ "CMD", "arangosh", "--server.endpoint", "tcp://localhost:8529", "--server.username", "root", "--server.password", "${ARANGO_ROOT_PASSWORD}", "--javascript.execute-string", "db._version()" ]
      timeout: 3s
      retries: 10
      start_period: 20s

volumes:
  arango-data:
  arango-app:

Starten Sie den Dienst anschließend mit

podman-compose up

Wenn die Ausgabe wie folgt aussieht: folgende

arango-db-1  | 2025-05-11T15:26:29Z [1] INFO [cf3f4] {general} ArangoDB (version 3.11.13 [linux]) is ready for business. Have fun!
kugelblitz-1  |
kugelblitz-1  |   .   ____          _            __ _ _
kugelblitz-1  |  /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
kugelblitz-1  | ( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
kugelblitz-1  |  \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
kugelblitz-1  |   '  |____| .__|_| |_|_| |_\__, | / / / /
kugelblitz-1  |  =========|_|==============|___/=/_/_/_/
kugelblitz-1  |
kugelblitz-1  |  :: Spring Boot ::                (v3.4.4)
kugelblitz-1  |
...
kugelblitz-1  | 2025-05-11T15:27:29.539Z  INFO 1 --- [nio-8080-exec-1] o.s.web.servlet.DispatcherServlet        : Completed initialization in 2 ms

Das bedeutet, wir sind bereit, mit Kugelblitz zu spielen. Erstellen wir zunächst eine Buch-Entität.

curl -X 'POST' \
  'http://localhost:8080/arango/createDocument/library/books' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "Pride and Prejudice",
  "author": "Jane Austen"
}'

Als Nächstes überprüfen wir, ob die Daten in der Datenbank gespeichert wurden. Der Schnellstart verwendet ArangoDB als Persistenzdatenbank. Wir können zunächst die Arando-Webkonsole unter http://localhost:8529/ aufrufen. Sie sollte zu einer Seite wie der folgenden führen:

ArangoDB-Webkonsole-Anmeldung.

Verwenden Sie root und root als Benutzernamen bzw. Passwort. Navigieren Sie anschließend zur Datenseite, indem Sie auf Login klicken -> wählen Sie library im Datenbank-Dropdown-Menü aus -> klicken Sie auf Select DB: library -> klicken Sie auf books collection -> klicken Sie in der oberen Navigationsleiste auf Content. Wie wir sehen, sind die Daten bereits als Arango-Dokument in der Datenbank vorhanden:

Beispieldaten in ArangoDB

tipp

Weitere Endpunkte finden Sie unter http://localhost:8080/swagger-ui/index.html

Fehlerbehebung​

Healthcheck schlägt fehl​

Healthcheck-Protokolle prüfen mit podman inspect --format "{{json .State.Health }}" <container name> | jq

ArangoDB Healthcheck schlägt mit der Meldung "ArangoError: nicht verbunden" fehl​

Dies liegt meist an einem falschen Passwort bei der Verbindungsherstellung über arangosh, das im Healthcheck verwendet wurde. Ein falsches Passwort könnte sein: