Nachrichten
Eine Nachricht ist jeder Wert, der an einen Actor gesendet wird.
Das Typsystem erzwingt, welche Nachrichten ein gegebener Actor
akzeptiert (über den Actor<TMessage>-Typparameter), und die Runtime
liefert Nachrichten eine nach der anderen an das onReceive des
Actors aus.
Diese Seite deckt die Konventionen ab, denen actor-ts-Code beim Strukturieren von Nachrichten folgt — wie sie aussehen, wie du auf ihnen dispatched, was du NICHT in sie packen solltest und welche Muster am häufigsten vorkommen.
Die Discriminated-Union-Konvention
Abschnitt betitelt „Die Discriminated-Union-Konvention“Das wichtigste einzelne Muster in dieser Codebasis: Nachrichten sind
Discriminated Unions, getaggt mit einem kind-Feld.
type CounterCommand = | { readonly kind: 'increment' } | { readonly kind: 'decrement' } | { readonly kind: 'set'; readonly to: number } | { readonly kind: 'get'; readonly replyTo: ActorRef<number> };Diese Form bringt drei Dinge:
- Compile-time-Exhaustiveness.
match(command).with(...).exhaustive()(über ts-pattern) weigert sich zu kompilieren, wenn du einen neuenkindhinzufügst und vergisst, ihn zu behandeln. Die actor-ts-Codebasis verwendet dieses Muster überall — siehe Pattern Matching. - Typ-Narrowing innerhalb von Handlern. Innerhalb des
.with({ kind: 'set' }, ...)-Arms istm.toautomatisch alsnumbertypisiert — keine Casts, keinas never. - Stabilität des Wire-Formats. Die Leitung trägt keine eigene
Typidentität — sobald eine Nachricht, die eine Prozess- oder
Cluster-Grenze überquert hat, geparst ist, ist
kinddas, worauf dasmatch(...)des empfangenden Actors dispatcht. Genau deshalb muss der Diskriminator innerhalb der Payload mitreisen. Siehe Serialisierung.
Die Konvention ist kind: string, klein geschrieben, kebab-case für
mehrere Wörter. Großgeschriebenes Kind funktioniert auch, ist aber
nicht das, was das Framework verwendet.
Ein vollständiges Beispiel
Abschnitt betitelt „Ein vollständiges Beispiel“import { Actor, ActorSystem, type ActorRef } from 'actor-ts';import { match } from 'ts-pattern';
type IncrementCommand = { readonly kind: 'increment' };type DecrementCommand = { readonly kind: 'decrement' };type GetCommand = { readonly kind: 'get'; readonly replyTo: ActorRef<number> };type CounterCommand = IncrementCommand | DecrementCommand | GetCommand;
class Counter extends Actor<CounterCommand> { private count = 0;
override onReceive(command: CounterCommand): void { match(command) .with({ kind: 'increment' }, () => this.onIncrement()) .with({ kind: 'decrement' }, () => this.onDecrement()) .with({ kind: 'get' }, (m) => this.onGet(m)) .exhaustive(); }
private onIncrement(): void { this.count++; } private onDecrement(): void { this.count--; } private onGet(m: GetCommand): void { m.replyTo.tell(this.count); }}
const system = ActorSystem.create('counters');const counter = system.spawnAnonymous(Counter);
counter.tell({ kind: 'increment' });counter.tell({ kind: 'increment' });counter.tell({ kind: 'increment' });// Später nach dem Count über eine Reply-to-Ref fragen — siehe Ask-Pattern.Wenn du später eine kind: 'reset'-Variante zu CounterCommand
hinzufügst, schlägt das .exhaustive()-Compile fehl, bis du einen
.with({ kind: 'reset' }, ...)-Arm hinzufügst. Kein Runtime-Crash,
keine still verschluckte Nachricht — der Compiler fängt es ab.
Immutability-Regeln
Abschnitt betitelt „Immutability-Regeln“Nachrichten sollten unveränderlich sein, sobald sie eingereiht sind. Zwei Gründe:
- Dieselbe Nachricht kann in manchen Szenarien zweimal verarbeitet werden — Restart-nach-Fehler spielt gepufferte Nachrichten erneut ab; Reliable-Delivery sendet unbestätigte erneut. Mutation zwischen Auslieferungen führt zu “Phantom”-Zustandsänderungen.
- Cross-Process-Sends serialisieren die Nachricht beim Senden und
deserialisieren sie beim Empfangen. Der Empfänger bekommt eine
Kopie; das Mutieren des Sender-Objekts nach
tellhat keinen Effekt auf die Kopie — aber diese Asymmetrie erzeugt verwirrende Bugs (der lokale Fall sieht die Mutation, der Remote-Fall nicht).
Praktische Faustregeln:
- Verwende
readonly-Eigenschaften (readonly kind,readonly replyTo, …). Der TypeScript-Compiler fängt dann versehentliche Schreibzugriffe ab. - Bevorzuge schlichte Objekte (
{ kind: 'x', n: 1 }) gegenüber Klassen — sie serialisieren trivial, keine Methoden-Verluste über Prozessgrenzen hinweg. - Behandle Arrays / verschachtelte Objekte innerhalb einer Nachricht als tief unveränderlich. Wenn du “updaten” musst, gib eine neue Nachricht zurück; mutiere nicht die eingehende.
Request/Response: die Reply-to-Ref
Abschnitt betitelt „Request/Response: die Reply-to-Ref“tell ist Fire-and-Forget. Für Request/Response ist die Konvention,
ein replyTo: ActorRef<ReplyType>-Feld in der Request-Nachricht zu
inkludieren:
type Get = { readonly kind: 'get'; readonly replyTo: ActorRef<number> };type ReplyOK = { readonly kind: 'reply-ok'; readonly value: number };
class Counter extends Actor<Get> { private count = 42; override onReceive(command: Get): void { command.replyTo.tell(this.count); }}Der Aufrufer liefert eine Ref, an die der Actor die Antwort sendet. Drei Quellen für diese Ref:
this.self, wenn der Aufrufer ein anderer Actor ist, der die Antwort an sich selbst geliefert haben will.this.sender, wenn der Aufrufer auf eine frühere Nachricht reagiert und die Antwort an den ursprünglichen Frager gehen soll. Hinweis:this.senderistOption<ActorRef>— leer, wenn die Nachricht von außerhalb des Actor-Systems kam.- Eine wegwerfbare “Ask”-Probe — was das
Ask-Pattern für dich baut. Gibt
ein
Promise<Reply>zurück.
Das Reply-to-Ref-Idiom ist umständlicher als ein Methodenaufruf,
bringt aber drei Dinge: Requests und Replies sind zeitlich entkoppelt
(kein await-Chain), die Antwort kann von einem anderen Actor
kommen als dem, der gefragt wurde, und derselbe Code funktioniert
lokal und cross-Cluster.
Reply-Type-Generics
Abschnitt betitelt „Reply-Type-Generics“Ein häufiger Formfehler: replyTo: ActorRef<number> zu deklarieren,
wenn der Actor manchmal mit { kind: 'reply-ok' } und manchmal mit
{ kind: 'reply-error' } antwortet.
Verwende eine Discriminated Union auch für den Reply-Typ:
type GetReply = | { readonly kind: 'reply-ok'; readonly value: number } | { readonly kind: 'reply-error'; readonly reason: string };
type Get = { readonly kind: 'get'; readonly replyTo: ActorRef<GetReply> };Das onReceive des Aufrufers kann dann auf dem kind der Antwort
match()en, um die Erfolgs- und Fehlerpfade auf dieselbe Weise zu
unterscheiden, wie es seine eigenen Befehle dispatched.
Command vs Event — der Persistent-Actor-Split
Abschnitt betitelt „Command vs Event — der Persistent-Actor-Split“Für Actors, die Events persistieren (PersistentActor), trennt das Framework Commands (was zu tun ist) von Events (was bereits passiert ist):
import { match } from 'ts-pattern';
type DepositCommand = { readonly kind: 'deposit'; readonly amount: number };
type Deposited = { readonly kind: 'deposited'; readonly amount: number; readonly timestamp: number };
class Account extends PersistentActor<DepositCommand, Deposited, { balance: number }> { // Command-Handler: validieren + Event persistieren async onCommand(state, command: DepositCommand): Promise<void> { await match(command) .with({ kind: 'deposit' }, (c) => this.onDeposit(c)) .exhaustive(); }
private async onDeposit(command: DepositCommand): Promise<void> { const event: Deposited = { kind: 'deposited', amount: command.amount, timestamp: Date.now() }; await this.persist(event, () => { /* Seiteneffekte nach dem Persistieren */ }); }
// Event-Handler: nur Zustands-Update — läuft sowohl beim Schreiben als auch bei Recovery onEvent(state, event: Deposited): { balance: number } { // Ein Fold, der einen Wert berechnet — Arme bleiben inline. return match(event) .with({ kind: 'deposited' }, (e) => ({ balance: state.balance + e.amount })) .exhaustive(); }}Der Split ist wichtig, weil Events der dauerhafte Record sind, die
beim Restart erneut abgespielt werden. Commands sind transient (die
Anfrage, die das Event erzeugt hat); Events sind ewig (der
Journal-Eintrag). Sie eindeutig zu benennen — Vergangenheitsform für
Events (Deposited), Imperativ für Commands (DepositCommand) — hält die
konzeptionelle Linie klar.
Siehe PersistentActor für die vollständige Event-Sourcing-Geschichte.
Drei Grenzen, und der Check, der für sie einsteht
Abschnitt betitelt „Drei Grenzen, und der Check, der für sie einsteht“Eine Nachricht überquert bis zu drei Grenzen, und jede macht etwas anderes mit ihr:
| Grenze | Mechanismus | Was ankommt |
|---|---|---|
| In-Process | Referenz | dasselbe Objekt — Prototyp intakt, Methoden funktionieren |
| Worker-Hop (Parallelität) | Structured Clone | ein plain Object: Prototyp weg, Methoden weg; ein Feld mit einer Funktion wirft DataCloneError |
| Cluster-Wire | der Serializer | was der registrierte Serializer daraus macht — eine Klasse ohne Binding ist wieder ein plain Object |
Eine Testsuite übt fast ausschließlich die erste Grenze, sodass ein
Nachrichtentyp lokal grün sein kann, beim ersten Umschalten von
actor-ts.parallelism.workers still degradiert und auf der Wire
fehlschlägt. Der mittlere Fall ist der gefährliche: Eine an einen Worker
gesendete Klasseninstanz wirft nicht. Sie kommt als plain Object an und
scheitert später — als match-Arm, der nie feuert, als
.exhaustive(), das woanders wirft, als Methode, die undefined ist.
Die Discriminated-Union-Konvention oben ist genau die Form, die alle drei
Grenzen überlebt.
Der Message-Boundary-Check lässt den lokalen Pfad für die anderen
beiden geradestehen. Mit eingeschaltetem Modus wird jedes lokale tell
beim Senden so geprüft, wie die Grenze es prüfen würde, und was verloren
ginge, wird mit Nachrichtentyp und Empfänger gemeldet — solange der
Sender noch auf dem Stack ist:
actor-ts.diagnostics.message-boundary { structured-clone = off # off | warn | fail — the worker hop serializer-round-trip = off # off | warn | fail — the cluster wire}const messageBoundary = MessageBoundaryOptions.create().withStructuredClone('fail');const systemOptions = ActorSystemOptions.create().withMessageBoundary(messageBoundary);warn loggt einmal pro Nachrichtentyp; fail wirft einen
MessageBoundaryError aus dem tell heraus. Beide sind in Produktion
aus — der Check läuft über jede Nachricht, und ein laufendes System hat
niemanden auf dem Stack, dem es etwas sagen könnte —, und TestKit
schaltet structured-clone auf fail, weil ein Test der Ort ist, an
dem das gefunden werden soll. Eine Suite, deren Nachrichten eine
Cluster-Wire überqueren sollen, schaltet zusätzlich
serializer-round-trip ein; es ist selbst im Kit aus, weil der Round-Trip
für jede Klasse, die eine Anwendung sendet, ein Serializer-Binding braucht
und die meisten Anwendungen für Nachrichten, die den Prozess nie
verlassen, keines haben.
Was der Clone-Check meldet: jeden erreichbaren Wert, dessen Prototyp der
Clone-Algorithmus nicht erhält — eine Klasseninstanz, eine Unterklasse von
Error — und jeden Wert, der sich gar nicht klonen lässt — eine
Funktion, ein Symbol. Date, RegExp, Map, Set, Typed Arrays und
die eingebauten Fehler sind in Ordnung, und ebenso eine ActorRef
irgendwo in der Nachricht: Die Wire schreibt Refs um, bevor der Port sie
sieht. Die Klassen des Frameworks selbst — PoisonPill, Terminated,
ein Cluster-Event, ein Listing — sind ausgenommen; jede überquert die
Grenzen, die sie überqueren muss, auf eigenem Weg.
Häufige Fallstricke
Abschnitt betitelt „Häufige Fallstricke“Wie es weitergeht
Abschnitt betitelt „Wie es weitergeht“- Pattern Matching —
das
match().exhaustive()-Idiom, das in jedem Beispiel auf dieser Seite verwendet wird. - Ask-Pattern —
ref.ask(message, timeout)gibt ein Promise für die Antwort zurück und vermeidet den manuellen Reply-to-Ref-Tanz. - Actor — die Basisklasse, die
onReceive-Signatur, die Context-Referenzen, die Reply-Refs produzieren. - Serialisierung — was mit deinen Nachrichten passiert, wenn sie eine Prozess-/Cluster-Grenze überqueren; wie du eigene Serializer registrierst, wenn der JSON-Default nicht passt.
- PersistentActor — wo der Command-vs-Event-Split tragend wird.
