Quarkus — Cheat Sheet

Der Spickzettel zum Quarkus Grundlagentraining — Annotationen, Prioritäten und Kurzformen zum Nachschlagen. Die vollständige und immer aktuelle Doku steht auf quarkus.io; hier steht die Auswahl, die im Alltag tatsächlich gebraucht wird.

Konfiguration

Höhere Quellen überschreiben niedrigere — nur Hardcoding schlägt System-Properties.

@ConfigProperty(name = "werkbank.betreiber", defaultValue = "Werkbank")
String betreiber;

Modul: Quarkus

REST mit Jakarta REST

Der Body wird nicht annotiert. @RestPath darf entfallen, wenn Parametername und Pfadvariable gleich heißen. Die Extension heißt quarkus-rest (plus quarkus-rest-jackson) — ältere Anleitungen nennen noch quarkus-resteasy-reactive.

@POST @Transactional
@ResponseStatus(201)
public Kunde add(Kunde k) { repo.persist(k); return k; }

@GET @Path("/{id}")
public Kunde byId(@RestPath Long id) {
    Kunde k = repo.findById(id);
    if (k == null) throw new NotFoundException();   // → HTTP 404
    return k;
}

Modul: REST

Dev Services

Liegt eine Datenbank-Extension im Projekt und ist keine Verbindung konfiguriert, startet Quarkus die Datenbank in dev und test selbst — eine laufende Container-Runtime (Docker oder Podman) vorausgesetzt.

quarkus.datasource.db-kind=postgresql
quarkus.hibernate-orm.schema-management.strategy=drop-and-create
# keine jdbc.url in dev — sonst kein Dev Service
%prod.quarkus.datasource.jdbc.url=${DB_URL}

Der Schlüssel hieß früher quarkus.hibernate-orm.database.generation. Testdaten kommen aus src/main/resources/import.sql; jede Anweisung braucht dort ein Semikolon. Gilt genauso für Kafka, AMQP und RabbitMQ.

Modul: Datenzugriff

Datenzugriff und Panache

Ein Panache-Repository bringt listAll(), findById(), persist() und count() ohne eine Zeile Code mit:

@ApplicationScoped
public class LeistungRepository implements PanacheRepository<Leistung> { }

// Finder ergänzen:
public Kunde findByEmail(String email) {
    return find("email", email).firstResult();
}
public Anbieter findByName(String name) {                // case-insensitiv
    return find("lower(name)", name.toLowerCase()).firstResult();
}

lower() gehört auf beide Seiten des Vergleichs — sonst schlägt er fehl. In der Query steht der Entity-Feldname, nicht der Spaltenname.

Modul: Datenzugriff

GraphQL

Modul: GraphQL

Reaktiv, Messaging, Observability

Uni steht für einen Wert, Multi für einen Strom mehrerer Werte:

@GET @Path("/{id}")
public Uni<Leistung> finde(Long id) { return repo.findById(id); }

Reaktiv ist eine Kette, keine Einzelentscheidung: Der Datenzugriff muss durchgängig reaktiv sein — ein reaktiver Treiber ist Pflicht, dazu Hibernate Reactive mit Panache Reactive.

Modul: Reaktiv

Typische Fallen

• Dev-Broker in Produktion. Dev Services liefern Datenbank und Broker zur Laufzeit — nur in dev und test. Produktion braucht echte Instanzen; über Profile trennen.
• Gesetzte jdbc.url schaltet die Dev Services ab. Deshalb gehört die Produktionsadresse ins %prod-Profil und nicht in die allgemeine Konfiguration.
• Readiness prüft keine Abhängigkeiten. „Ready”, aber die Datenbank ist noch nicht oben.
• traceId und spanId fehlen im Log. Ohne sie wird Debugging über Servicegrenzen hinweg zur Sucharbeit.
• GraalVM lokal installiert. Nötig ist es nur im Native-Build; zum Entwickeln genügt ein gewöhnliches JDK.
• CDI Portable Extensions. Von ArC nicht direkt unterstützt — Workaround über Beans am Application-Context.
• OpenTelemetry ist nicht überall stabil. Traces ja; Metriken und Logs laufen dort als Tech Preview. Für Metriken Micrometer nehmen.