Registrul schemei și evoluția datelor

De ce am nevoie de un registru schema

Registrul Schema este o sursă centralizată de adevăr pentru contractele de date (API-uri, evenimente, fire, mesaje, magazine) care oferă:

Evoluție previzibilă: reguli de compatibilitate și verificarea automată a ruperii.
Repetabilitate și transparență: istoria versiunilor, cine/când/de ce s-a schimbat.
Standardizare: nume uniforme, formate de eroare, câmpuri de urme, etichete PII.
Integrarea cu CI/CD: blocarea modificărilor de rupere înainte de producție.

Registrul leagă Protocolul în primul rând și compatibilitatea contractului, făcând schimbări rapide și sigure.

Formate și aplicații

Schema JSON: sarcini utile REST/HTTP, documente, configurații.
Avro: autobuze de evenimente (Kafka/Pulsar), compacte/evolutie prin ID-ul campului.
Protobuf: gRPC/RPC, binar tag-uri eficiente, stricte.
GraphQL SDL: schema de tip și directivă, evoluția prin „@ depreciate”.
SQL DDL ca artefact: stabilim vizualizări convenite (de exemplu, storefronturi externe) - cu precauție.

💡 Un singur registru poate stoca mai multe tipuri de artefacte simultan, dar cu politici de compatibilitate separate.

Moduri de compatibilitate

ÎNAPOI: Noile scheme citesc date/mesaje vechi. Potrivit pentru un producător care extinde sarcina utilă în mod aditiv.
FORWARD: consumatorii vechi citesc corect date noi (necesită un cititor tolerant).
FULL: combină ambele (mai stricte, mai convenabile pentru contractele de achiziții publice).
NONE: fără cecuri - numai pentru cutii de nisip.

Recomandări:

Evenimente: mai des BACKWARD (producătorul extinde sarcina utilă opțională).
API-uri publice: FULL sau BACKWARD + cititor strict tolerant pe clienți.
Prototipuri interne: temporar NONE, dar nu pe trunchi.

Sigur (aditiv) vs. modificări periculoase

Aditiv (OK):

Adăugați un câmp/tip opțional.
Extindere enum cu noi valori (cu cititor tolerant).
Adăugați proiecție/eveniment alternativ („.îmbogățit”).
Relaxarea constrângerilor („minLength”, „maxim” ↑, dar nu ↓).

Periculos (pauză):

Ștergeți/redenumiți câmpurile sau modificați tipul/obligatoriu.
Schimbarea semanticii stărilor/codecurilor/ordinii în fire.
Reutilizarea etichetelor protobuf.
Schimbarea tastei de partiționare în evenimente.

Înregistrare organizare

Denumirea și adresarea

Grupuri/spații: "plăți", "kyc'," audit ".
Nume: 'plată. autorizat. v1 '(evenimente),' plăţi. v1. CaptureRequest '(gRPC),' comenzi. v1. Ordinul "(JSON Schema).
Major în nume, minori în versiunea metadate/schemă.

Metadate

'owner' (comandă), 'domain', 'slas' (SLO/SLA), 'security. nivelul "(PII/PCI)," retenție "," compatibilitate _ mode "," apus de soare "," changelog ".

Managementul ciclului de viață

Draft Review aprobat lansat depreciat Sunset.
Validatoare/lintere automate, manual de proiectare-revizuire (API Guild), note de lansare.

Integrarea în CI/CD

1. Pre-comite: lintere locale (instrumente Spectral/Buf/Avro).
2. PR-pipeline: schema-diff → verificarea modului de compatibilitate; blocarea ruperii.
3. Artefact publică: apăsați schema consistentă pentru a înregistra + genera SDK/modele.
4. Runtime-guard (opțional): Gateway/producător validează sarcina utilă față de schema curentă.

Exemplu de etape în PR:

'openapi-diff --fail-on-breaking'
'buf break--aginst
'
'avro-compat --mode BACKWARD'
generarea de probe de aur și rularea testelor CDC.

Evoluția schemelor: practici

Aditiv-first: новые поля - 'opţional/nullable' (JSON), 'opţional' (proto3), implicit в Avro.
Modelul piramidei inverse: miezul este stabil, îmbogățirea este în apropiere și opțională.
Dual-emit/dual-write pentru major: publicăm „v1” și „v2” în paralel.
Planul de apus: date, utilizări, avertismente, adaptoare.
Cititor tolerant: clienții ignoră câmpurile necunoscute și se ocupă corect de noul enum.

Exemple de sisteme și controale

Schema JSON (fragment, câmp aditiv)

json
{
"$id": "orders.v1.Order",
"type": "object",
"required": ["id", "status"],
"properties": {
"id": { "type": "string", "format": "uuid" },
"status": { "type": "string", "enum": ["created", "paid", "shipped"] },
"risk_score": { "type": "number", "minimum": 0, "maximum": 1 }
},
"additionalProperties": true
}

💡 Adăugat 'risk _ score' ca opțional → BACKWARD este compatibil.

Avro (implicit pentru compatibilitate)

json
{
"type": "record",
"name": "PaymentAuthorized",
"namespace": "payment.v1",
"fields": [
{ "name": "payment_id", "type": "string" },
{ "name": "amount", "type": "long" },
{ "name": "currency", "type": "string" },
{ "name": "risk_score", "type": ["null", "double"], "default": null }
]
}

Protobuf (nu reutilizați etichetele)

proto syntax = "proto3";
package payments.v1;

message CaptureRequest {
string payment_id = 1;
int64 amount = 2;
string currency = 3;
optional double risk_score = 4; // additive
}
// tag=4 зарезервирован под risk_score, его нельзя менять/удалять без v2

Registrul evenimentelor și partiționarea

Denumire evenimente: 'domeniu. acțiune. v {major} '(' plata. capturat. v1 ').
Cheia de partiționare face parte din contract ('payment _ id',' user _ id').
Core vs Îmbogățit: ".v1" (nucleu) și ".Enriched. v1 '(detalii).
Compatibilitate registru: moduri la nivel temă/tip; CI refuză schimbările incompatibile.

Gestionarea migrației

Extindeți → migrați → contract (REST/gRPC):

1. Adăugați câmpuri/tabele 2) începeți să scrieți/să citiți câmpuri noi; 3) șterge vechi după apusul soarelui.

Dual-emit (Evenimente): paralel cu 'v1 '/' v2', migrarea consumatorului/proiecției, apoi eliminarea 'v1'.
Replay: reasamblarea proiecțiilor din jurnal la o nouă diagramă (numai cu compatibilitate și migratori).
Adaptoare: gateway-uri/proxy-uri care traduc „v1↔v2” pentru clienți complexi.

Siguranță și conformitate

Etichetele PII/PCI din diagramă: 'x-pii: true', 'x-sensibility: high'.
Politici de acces: cine poate publica/modifica scheme (RBAC), semna comunicate.
Criptografie: semnătura versiunilor schemei, jurnalele de audit imuabile (WORM).
Dreptul de a fi uitat: specificați câmpurile care necesită criptare/ștergere cripto; îndrumare în registru.

Observabilitate și audit

Tablouri de bord: numărul de modificări, tipuri (minore/majore), cota de PR-uri respinse, utilizarea versiunii.
Traseu de audit: cine a schimbat schema, link-uri către PR/ADR, release.
Măsurători de rulare: procentaj de mesaje care nu au reușit validarea; incidente de compatibilitate.

Instrumente (eșantion)

Schema OpenAPI/JSON: Spectral, OpenAPI Diff, Schemathesis.
Protobuf/gRPC: Buf, buf-breaking, linters.
Avro/Evenimente: Confluent/Redpanda Schema Registry, Avro-tools, Karapace.
GraphQL: GraphQL Inspector, GraphQL Codegen.
Registre/cataloage: Artifact Registry, Git-based registry, Backstage Catalog, UI personalizat.
Documentație: Redocly/Stoplight, Swagger-UI, GraphiQL.

Anti-modele

Swagger-wash: schema nu reflectă realitatea serviciului (sau invers).
Verificarea compatibilității cu handicap: „urgent” → întreruperea produsului.
Reutilizarea etichetelor protobuf: corupere silențioasă a datelor.
Modul de compatibilitate unic „pentru tot”: diferite domenii necesită moduri diferite.
CDC-uri brute ca scheme publice: scurgerea modelului DB, imposibilitatea evoluției.

Lista de verificare a implementării

Formatul artefact definit și modul de compatibilitate după domeniu.
Linters și schema-diff sunt configurate în CI, PR este blocat atunci când se rupe.
Activat pentru cititorul tolerant al clienților; 'additionalProperties = true' (dacă este cazul).
Modificările majore trec prin RFC/ADR, există un plan de apus de soare și dual-emit/dual-write.
Circuitele sunt marcate cu PII/PCI și niveluri de acces; auditul este activat.
Utilizarea versiunii și eșecuri de compatibilitate tablouri de bord.
Generarea SDK/modele din registru face parte din conductă.
Documentație și mostre de aur actualizate automat.

ÎNTREBĂRI FRECVENTE

Este posibil fără un registru pentru a stoca scheme în Git?
Da, dar registrul adaugă API-uri de compatibilitate, căutare, metadate, politică centralizată și validare on-the-fly. Cea mai bună opțiune este Git ca stocare + UI/politici pe partea de sus.

Cum aleg modul de compatibilitate?
Uitați-vă la direcția schimbării: dacă producătorul extinde sarcina utilă - BACKWARD. Pentru API public/SDK - FULL. Pentru prototipuri rapide - temporar NONE (nu pe trunchi).

Ce trebuie să faceți dacă este necesar?
Pregătirea v2: dual-emit/dual-run, sunset-date, adaptoare, telemetrie de utilizare, ghiduri de migrare.

Trebuie să validez sarcina utilă în timpul rulării?
Pentru domeniile critice, da: acest lucru împiedică mesajele nedorite și accelerează diagnosticarea.

Rezultat

Registrul schemei transformă evoluția datelor dintr-o improvizație riscantă într-un proces ușor de gestionat: reguli uniforme de interoperabilitate, validări automate, versiuni ușor de înțeles și o istorie transparentă. Adăugați la ea disciplina de aditiv-primul, tolerant cititor, dual-emit și apus de soare - și contractele se vor dezvolta rapid, fără defecțiuni și incidente de noapte.