Strukturen af et ændringshændelsesdokument

Hver hændelse, der leveres af et change stream, er et dokument med en ændringshændelse med et standardiseret sæt felter. De vigtigste felter er operationType (hvad der skete), ns (hvilket namespace der blev påvirket), documentKey (det påvirkede dokuments _id) samt operationsspecifikke felter som fullDocument og updateDescription. Når du forstår denne struktur, kan du skrive hændelseshandlere, der reagerer korrekt på hver operationstype.

Feltet operationType identificerer hvilken type ændring der fandt sted. Almindelige værdier omfatter: 'insert' (nyt dokument tilføjet), 'update' (dokumentfelter ændret), 'replace' (hele dokumentet erstattet), 'delete' (dokument fjernet) og 'invalidate' (change streamen er blevet ugyldig, f.eks. fordi samlingen blev slettet). Der findes også 'drop', 'rename' og 'dropDatabase' til samlings- og databaseoperationer.

Feltet ns indeholder namespace for den påvirkede samling som et objekt med to egenskaber: ns.db (databasens navn) og ns.coll (samlingens navn). Dette felt er vigtigt, når du åbner et change stream på database- eller klientniveau, hvor hændelser fra flere samlinger ankommer via den samme stream. Brug ns.coll til at dirigere hændelser til den korrekte handler.

Feltet documentKey indeholder _id for det dokument, der blev påvirket af ændringen. Det findes ved alle operationstyper undtagen 'invalidate' og operationer på samlingsniveau. For sharded collections kan documentKey også indeholde shard-nøglefelterne sammen med _id. Dette felt gør det muligt at identificere præcis, hvilket dokument der blev ændret, uden at du behøver at læse hele dokumentet.

Ved 'insert'-operationer indeholder ændringshændelsen et felt med navnet fullDocument, der indeholder hele det indsatte dokument, inklusive det automatisk genererede _id. Dette er tilgængeligt som standard for inserthændelser – i modsætning til update-hændelser, hvor du skal tilvælge det med updateLookup. Brug dette til straks at behandle nye data uden at sende en efterfølgende forespørgsel.

Ved 'update'-handlinger indeholder ændringshændelsen et updateDescription-objekt i stedet for et helt dokument. Det har to underfelter: updatedFields (et map fra feltstier til deres nye værdier) og removedFields (en array med feltstier, der blev fjernet). Dette deltaformat er kompakt og effektivt – det rapporterer kun, hvad der blev ændret, ikke hele dokumentets tilstand.

En 'replace'-hændelse opstår, når replaceOne() kaldes, og erstatter hele dokumentet (bortset fra _id). Ændringshændelsen indeholder et fullDocument med det komplette nye dokument. Det adskiller sig fra en opdateringshændelse ved, at der ikke findes nogen updateDescription – du kan ikke se, hvad der blev ændret, kun hvad den nye tilstand er. Behandl erstatningshændelser som indsættelseshændelser: læs den fulde nye tilstand fra fullDocument.

Ved 'delete'-hændelser er feltet fullDocument null, fordi dokumentet allerede er væk, når du behandler hændelsen. Kun documentKey (som indeholder _id) er pålideligt tilgængeligt. Hvis din slettehåndtering har brug for dokumentets indhold, skal du gemme de relevante oplysninger før sletningen (f.eks. i en revisionslog), fordi ændringsstreams ikke kan hente dokumenter, der allerede er fjernet.

Alle ændringshændelser har et genoptagelsestoken gemt i feltet _id (et { _data: '...' }-objekt). Dette token identificerer hændelsens position i oploggen. Gem genoptagelsestokenet efter behandling af hver hændelse, så din applikation kan genoptage streamen fra det sted, hvor den slap, hvis den genstartes, ved hjælp af indstillingen resumeAfter eller startAfter. Det giver leveringsgarantier på mindst én gang.

En 'invalidate'-hændelse signalerer, at ændringsstreamen ikke længere kan fortsætte – typisk fordi den overvågede collection blev slettet, databasen blev slettet, eller replikasættet gennemførte en tilbagerulning. Efter en invalidate-hændelse lukkes ændringsstreamen automatisk. Din applikation bør håndtere dette ved at åbne streamen igen (eller underrette administratorer) i stedet for at ignorere det. Kontrollér typen 'invalidate', og afgør, om streamen skal åbnes igen eller lukkes ned.

Ved at samle alle hændelsestyper i én robust håndtering med switch-baseret routing bliver koden nemmere at vedligeholde. Hver case læser kun de felter, der med sikkerhed er til stede for den pågældende handlingstype. Struktureret logging, der indeholder operationType, namespace og documentKey, giver god indsigt i, hvad din ændringsstream behandler.

I denne lektion har du lært, at alle ændringshændelser har operationType, ns, documentKey og handlingsspecifikke felter som fullDocument og updateDescription, at insert/replace-hændelser indeholder fullDocument, mens delete-hændelser ikke gør det (dokumentet er allerede væk), og at hændelsens _id-felt er genoptagelsestokenet, der bruges til at genstarte streamen fra en kendt position. Dernæst undersøger vi filtrering af ændringsstreamhændelser med aggregeringspipelines.