Effiziente Order-API für Handelsplattformen: Architektur und Best Practices

Die Order-API einer Handelsplattform ist weit mehr als nur ein Microservice – sie fungiert als zentrales Steuerungssystem, das Nutzeranfragen mit der Marktexekution verbindet. Sobald ein Trader einen Kauf- oder Verkaufsauftrag erteilt, übernimmt diese Komponente die Validierung aller Details, leitet die Anfrage an die Börse weiter und verbreitet das Ergebnis an alle relevanten Teilsysteme.

In unserem aktuellen Projekt zur Entwicklung einer Brokerage-Plattform für die brasilianische B3-Börse haben wir bereits einzelne Komponenten wie Preisabgleich, Matching-Engine, Finanzverwahrung und Asset-Kataloge implementiert. Nun steht die kritische Schnittstelle im Fokus, die alles zusammenführt: die Broker Order-API.

Die zentralen Funktionen der Order-API

Der Dienst mit dem Namen trading-broker-order dient als einheitlicher Einstiegspunkt für sämtliche Handelsaktivitäten. Seine Hauptaufgabe besteht darin, den kompletten Lebenszyklus eines Orders zu verwalten – von der erstmaligen Einreichung bis zur finalen Bestätigung der Ausführung. Dazu gehören:

• Prüfung der Nutzerberechtigung
• Validierung der Verfügbarkeit des Assets
• Weiterleitung der Orders an die B3-Matching-Engine
• Benachrichtigung aller Subsysteme über Statusänderungen

Zur Erfüllung dieser Aufgaben kommuniziert der Service mit vier Schlüsselelementen:

• Asset-API (REST/Feign) – Bestätigt, ob das Wertpapier existiert und handelbar ist
• Wallet-API (REST/Feign) – Überprüft, ob der Nutzer über ausreichende Guthaben verfügt
• B3-Matching-Engine (RabbitMQ) – Leitet Orders zur Ausführung weiter
• Broker Wallet (Kafka) – Veröffentlicht Lebenszyklusereignisse im gesamten System

Schritt-für-Schritt: Ablauf eines Orders

Hier sehen wir, wie ein typischer Order verarbeitet wird:

1. Ein Nutzer sendet eine POST-Anfrage an /api/v1/orders mit Parametern wie Nutzer-ID, Wertpapierticker, Menge und Order-Richtung (Kauf/Verkauf)
2. Die Order-API führt folgende Schritte durch:

• Validierung des Tickers über die Asset-API
• Prüfung des Wallet-Guthabens über die Wallet-API
• Speicherung des Orders in MySQL mit Status PENDING
• Veröffentlichung der Order an RabbitMQ für die B3-Execution
• Versand einer Benachrichtigung via Kafka unter dem Ereignisnamen order-events-v1

1. Die B3-Matching-Engine verarbeitet den Order und übermittelt einen Status (FILLED oder REJECTED) zurück über RabbitMQ
2. Die Order-API aktualisiert daraufhin:

• Den Order-Status in der MySQL-Datenbank
• Veröffentlicht das finale Kafka-Ereignis
• Die Wallet-Komponente reagiert, indem sie Guthaben blockiert, liquidiert oder freigibt

Dieses Design kombiniert synchrone REST-Aufrufe für Validierungen mit asynchronen RabbitMQ/Kafka-Nachrichten zur Ereignispropagation.

Technologie-Stack der Implementierung

Die Order-API nutzt moderne Java- und Spring-Technologien:

• Java 21 + Spring Boot 3.3.5 – Kernlaufzeitumgebung und Framework
• MySQL + Flyway – Persistente Datenspeicherung mit Schema-Migrationen
• Spring Kafka – Veröffentlichung von Lebenszyklusereignissen
• Spring AMQP – Integration von RabbitMQ für die Order-Weiterleitung
• Spring Cloud OpenFeign – REST-Client für Asset- und Wallet-APIs
• SpringDoc OpenAPI – Interaktive Swagger-Dokumentation

Wichtige Implementierungsprinzipien

1. Domänenmodell: Die Order-Entität

Die Klasse Order bildet den Zustand eines Orders während seines gesamten Lebenszyklus ab:

@Entity
@Table(name = "orders")
public class Order {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String userId;
    private String ticker;

    @Column(nullable = false, precision = 19, scale = 4)
    private BigDecimal quantity;

    @Column(nullable = false, precision = 19, scale = 4)
    private BigDecimal price;

    @Column(precision = 19, scale = 4)
    private BigDecimal executedPrice; // Wird erst nach B3-Bestätigung gesetzt

    @Enumerated(EnumType.STRING)
    private OrderSide side; // KAUF | VERKAUF

    @Enumerated(EnumType.STRING)
    private OrderStatus status; // PENDING | FILLED | REJECTED | CANCELLED

    @CreationTimestamp
    private LocalDateTime createdAt;

    @UpdateTimestamp
    private LocalDateTime updatedAt;

    public OrderEventDTO mapToEvent() {
        return OrderEventDTO.builder()
            .orderId(this.getId())
            .userId(this.getUserId())
            .ticker(this.getTicker())
            .quantity(this.getQuantity())
            .price(this.getPrice())
            .executedPrice(this.getExecutedPrice())
            .side(this.getSide().name())
            .status(this.getStatus().name())
            .eventTimestamp(LocalDateTime.now())
            .build();
    }
}

Eine entscheidende Designentscheidung war die Option, executedPrice als optional zu definieren. Da der tatsächliche Ausführungspreis erst nach der Order-Einreichung von B3 übermittelt wird, würde eine erzwungene Nicht-Null-Bedingung bei der Erstellung die Domänenintegrität brechen.

2. Ticker-Validierung: Asset-Feign-Client

Ungültige Ticker müssen frühzeitig abgefangen werden, um unnötige Verarbeitungsprozesse zu vermeiden. Der AssetClient nutzt Feign, um die Asset-API aufzurufen:

@FeignClient(name = "trading-broker-asset", url = "${app.services.asset-url}")
public interface AssetClient {
    @GetMapping("/api/v1/assets/{ticker}")
    AssetDTO getByTicker(@PathVariable("ticker") String ticker);
}

Die Validierungslogik im OrderService umfasst:

• Auslösen einer RuntimeException, falls der Ticker inaktiv oder nicht gefunden wird
• Unterscheidung zwischen Business-Fehlern (FeignException.NotFound) und technischen Problemen (Timeouts, 5xx-Fehler)
• Bereitstellung nutzerfreundlicher Fehlermeldungen für jeden Fehlertyp

Dies stellt sicher, dass Händler umgehend Rückmeldung zu ungültigen Eingaben erhalten, anstatt erst später im Prozess auf stille Ablehnungen zu stoßen.

3. Guthabenprüfung: Wallet-Feign-Client

Bei Kauforders muss das System sicherstellen, dass der Nutzer über ausreichende Mittel verfügt. Der WalletClient ist ähnlich strukturiert:

@FeignClient(name = "trading-broker-wallet", url = "${app.services.wallet-url}")
public interface WalletClient {
    @GetMapping("/api/v1/wallets/summary")
    WalletSummaryDTO getWalletSummary(@RequestParam("userId") String userId);
}

Die Validierungslogik vergleicht die angeforderte Menge mit dem verfügbaren Guthaben und blockiert den Betrag unmittelbar bei Erstellung des Orders.

4. Ereignisgesteuerte Kommunikationsmuster

Das System setzt auf zwei Nachrichtenparadigmen:

• RabbitMQ für die Echtzeit-Weiterleitung von Orders an die B3-Matching-Engine
• Kafka für dauerhafte, wiederabspielbare Order-Lebenszyklusereignisse

Jede Statusänderung löst eine Reihe von Ereignissen aus, die an alle relevanten Komponenten verteilt werden. Diese Architektur ermöglicht Skalierbarkeit, Fehlertoleranz und eine nahtlose Integration in bestehende Ökosysteme.

Fazit: Eine skalierbare Grundlage für Handelsplattformen

Die Implementierung einer Order-API erfordert sorgfältige Planung und den Einsatz moderner Technologien. Durch die Kombination aus domänengetriebenem Design, asynchroner Kommunikation und robusten Validierungsmechanismen entsteht ein System, das nicht nur den Anforderungen heutiger Handelsplattformen gerecht wird, sondern auch zukünftige Erweiterungen ermöglicht. Unternehmen, die in eine solche Architektur investieren, legen den Grundstein für zuverlässige, effiziente und skalierbare Handelslösungen.