Μητρώο Schema και εξέλιξη δεδομένων

Γιατί χρειάζομαι ένα μητρώο σχημάτων

Το μητρώο Schema είναι μια κεντρική πηγή αλήθειας για τις συμβάσεις δεδομένων (API, γεγονότα, νήματα, μηνύματα, αποθήκες) που παρέχει:

Προβλέψιμη εξέλιξη: κανόνες συμβατότητας και αυτόματος έλεγχος θραύσης.
Επαναληψιμότητα και διαφάνεια: το ιστορικό των εκδόσεων, ποιος/πότε/γιατί άλλαξε.
Τυποποίηση: ομοιόμορφα ονόματα, μορφότυποι σφάλματος, ιχνοστοιχεία, ετικέτες PII.
Ενσωμάτωση με CI/CD: παρεμπόδιση μεταβολών θραύσης πριν από την παραγωγή.

Το μητρώο συνδέει το πρωτόκολλο-πρώτο και τη συμβατότητα των συμβάσεων, κάνοντας τις αλλαγές γρήγορες και ασφαλείς.

Μορφότυποι και εφαρμογές

JSON Schema: Ωφέλιμα φορτία REST/HTTP, έγγραφα, ρυθμίσεις.
Avro: λεωφορεία εκδηλώσεων (Kafka/Pulsar), συμπαγή/εξέλιξη μέσω ταυτότητας πεδίου.
Protobuf: gRPC/RPC, δυαδικές αποτελεσματικές, αυστηρές ετικέτες.
GraphQL SDL: σχήμα τύπου και οδηγίας, εξέλιξη μέσω '@ deprected'.
SQL DDL ως τεχνούργημα: φτιάχνουμε συμφωνημένες απόψεις (για παράδειγμα, εξωτερικά καταστήματα) - με προσοχή.

💡 Ένα ενιαίο μητρώο μπορεί να αποθηκεύσει πολλούς τύπους αντικειμένων ταυτόχρονα, αλλά με ξεχωριστές πολιτικές συμβατότητας.

Τρόποι συμβατότητας

BACKWARD: Νέα σχήματα διαβάζουν παλιά δεδομένα/μηνύματα. Κατάλληλο για έναν παραγωγό που επεκτείνει πρόσθετα το ωφέλιμο φορτίο.
FORWARD: Οι ηλικιωμένοι καταναλωτές διαβάζουν σωστά τα νέα δεδομένα (απαιτεί ανεκτικό αναγνώστη).
FULL: συνδυάζει και τα δύο (αυστηρότερα, πιο βολικά για τις δημόσιες συμβάσεις).
ΟΥΔΕΝ: δεν υπάρχουν έλεγχοι - μόνο για αμμοκιβώτια.

Συστάσεις:

Γεγονότα: συχνότερα BACKWARD (ο παραγωγός επεκτείνει το ωφέλιμο φορτίο προαιρετικά).
Δημόσια API: FULL ή BACKWARD + αυστηρά ανεκτικός αναγνώστης για τους πελάτες.
Εσωτερικά πρωτότυπα: προσωρινά ΟΥΔΕΝ, αλλά όχι στον κορμό.

Ασφαλείς (πρόσθετες ύλες) έναντι επικίνδυνων αλλαγών

Πρόσθετη ύλη (OK):

Προσθήκη προαιρετικού πεδίου/τύπου.
Επέκταση Enum με νέες τιμές (με ανεκτικό αναγνώστη).
Προσθήκη εναλλακτικής προβολής/γεγονότος ('.εμπλουτισμένο').
Περιορισμοί χαλάρωσης ('minLength', 'maximum' ↑, αλλά όχι ↓).

Επικίνδυνο (θραύση):

Διαγραφή/μετονομασία πεδίων ή αλλαγή του τύπου τους/υποχρεωτική.
Αλλαγή της σημασιολογίας των καταστάσεων/κωδικοποιητών/σειρά σε νήματα.
Επαναχρησιμοποίηση ετικετών protobuf.
Αλλαγή κλειδιού κατάτμησης σε γεγονότα.

Οργάνωση μητρώου

Ονομασία και διεύθυνση

Ομάδες/χώροι: «πληρωμές», «kyc», «έλεγχος».
Ονομασίες: 'πληρωμή. έχει εγκριθεί. v1 '(γεγονότα),' πληρωμές. v1. CaptureRequest '(gRPC),' παραγγελίες. v1. Εντολή '(JSON Schema).
Μείζων κατ "όνομα, ανήλικοι σε έκδοση μεταδεδομένων/σχημάτων.

Μεταδεδομένα

'owner' (εντολή), 'domain', 'slas' (SLO/SLA), 'security. βαθμίδα "(PII/PCI)," κατακράτηση "," συμβατότητα _ λειτουργία "," ηλιοβασίλεμα "," changelog ".

Διαχείριση κύκλου ζωής

Σχέδιο Ανασκόπησης Εγκρίθηκε Απελευθερώθηκε Καταστράφηκε Ηλιοβασίλεμα.
Αυτόματοι επικυρωτές/χιτώνια, χειροκίνητη ανασκόπηση σχεδιασμού (API Guild), σημειώσεις απελευθέρωσης.

Ενσωμάτωση σε CI/CD

1. Προεπιλογή: τοπικές γραμμές (Spectral/Buf/Avro tools).
2. Αγωγός PR: έλεγχος τρόπου συμβατότητας schema-diff· διακοπή της διακοπής.
3. Το Artifact δημοσιεύει: σπρώξτε σταθερό σχήμα στο μητρώο + δημιουργήστε μοντέλα SDK/.
4. Χρονοφύλακας (προαιρετικά): Η πύλη/ο παραγωγός επικυρώνει το ωφέλιμο φορτίο με βάση το τρέχον σύστημα.

Παράδειγμα σταδίων στις δημόσιες σχέσεις:

'openapi-diff-fail-on-breaking'
'buf breaking - against
'
'avro-compat -mode BACKWARD'
παραγωγή χρυσών δειγμάτων και διεξαγωγή δοκιμών ΚΕΕΛΠΝΟ.

Εξέλιξη των συστημάτων: πρακτικές

Πρώτη πρόσθετη ύλη: новые поля - 'προαιρετικό/ακυρώσιμο' (JSON), 'προαιρετικό' (proto3), προεπιλεγμένο в Avro.
Μοντέλο αντίστροφης πυραμίδας: ο πυρήνας είναι σταθερός, ο εμπλουτισμός είναι κοντινός και προαιρετικός.
Διπλή εκπομπή/διπλή γραφή για μείζονα: δημοσιεύουμε παράλληλα το «v1» και το «v2».
Σχέδιο ηλιοβασίλεμα: ημερομηνίες, χρήσεις, προειδοποιήσεις, προσαρμογείς.
Ανεκτικός αναγνώστης: οι πελάτες αγνοούν άγνωστα πεδία και χειρίζονται σωστά νέο enum.

Παραδείγματα συστημάτων και ελέγχων

JSON Schema (θραύσμα, πεδίο πρόσθετων υλών)

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
}

💡 Προστέθηκε 'risk _ score' ως προαιρετικό → BACKWARD είναι συμβατό.

Avro (εξ ορισμού συμβατότητα)

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 (μην ξαναχρησιμοποιήσετε ετικέτες)

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

Μητρώο γεγονότων και κατάτμηση

Ονοματοδοσία γεγονότων: 'domain. δράση. v {major} '(' πληρωμή. αιχμαλωτίστηκε. v1 ').
Η κλείδα κατάτμησης είναι μέρος της σύμβασης ('payment _ i ,' user _ id ').
Core vs Εμπλουτισμένος: '.v1' (πυρήνας) και '.enriched. v1 '(λεπτομέρειες).
Συμβατότητα μητρώου: τρόποι λειτουργίας σε επίπεδο θέματος/τύπου· Ο ΚΚΠ αρνείται ασυμβίβαστες αλλαγές.

Διαχείριση της μετανάστευσης

Επέκταση σύμβασης → → μετανάστευσης (REST/gRPC):

1. Προσθήκη πεδίων/πινάκων 2) έναρξη γραφής/ανάγνωσης νέων πεδίων; 3) διαγράψτε την παλαιά μετά το ηλιοβασίλεμα.

Διπλή εκπομπή (Events): παράλληλη προς 'v1 '/' v2', μετανάστευση καταναλωτή/προβολής και στη συνέχεια αφαίρεση του 'v1'.
Επανασύνδεση προβολών από το ημερολόγιο σε νέο διάγραμμα (μόνο με συμβατότητα και μετανάστες).
Προσαρμογείς: πύλες/πληρεξούσια που μεταφράζουν «v1↔v2» για πολύπλοκους πελάτες.

Ασφάλεια και συμμόρφωση

Ετικέτες PII/PCI στο διάγραμμα: 'x-pii: true', 'x-sensity: high'.
Πολιτικές πρόσβασης: ποιος μπορεί να δημοσιεύει/τροποποιεί συστήματα (RBAC), να υπογράφει εκδόσεις.
Κρυπτογραφία: υπογραφή εκδόσεων σχημάτων, αμετάβλητα αρχεία καταγραφής ελέγχου (WORM).
Δικαίωμα να ξεχαστεί: προσδιορίστε πεδία που απαιτούν κρυπτογράφηση/διαγραφή κρυπτογράφησης. καθοδήγηση στο μητρώο.

Παρατηρησιμότητα και λογιστικός έλεγχος

Dashboards: αριθμός αλλαγών, τύποι (ήσσονος σημασίας/μείζονος σημασίας), μερίδιο απορριφθέντων PR, χρήση έκδοσης.
Διαδρομή ελέγχου: ποιος άλλαξε το σύστημα, σύνδεσμοι με PR/ADR, σχετική έκδοση.
Μετρήσεις χρόνου λειτουργίας: ποσοστό μηνυμάτων που απέτυχαν στην επικύρωση. συμβάντα συμβατότητας.

Εργαλεία (στοίβα δείγματος)

OpenAPI/JSON Schema: Spectral, OpenAPI Diff, Schemathesis.
Protobuf/gRPC: Buf, buf-breaking, linters.
Avro/Events: Confluent/Redpanda Schema Registry, Avro-tools, Karapace.
GraphQL: Επιθεωρητής GraphQL, GraphQL Codegen.
Μητρώα/κατάλογοι: Μητρώο τεχνουργημάτων, μητρώο βασισμένο στο Git, κατάλογος παρασκηνιακών σταδίων, προσαρμοσμένος UI.
Τεκμηρίωση: Redocly/Stoplight, Swagger-UI, GraphiQL.

Αντι-μοτίβα

Swagger-wash: το σύστημα δεν αντικατοπτρίζει την πραγματικότητα της υπηρεσίας (ή αντιστρόφως).
Έλεγχος συμβατότητας με άτομα με ειδικές ανάγκες: «επείγον» → διαλείμματα του προϊόντος.
Επαναχρησιμοποίηση ετικετών protobuf: σιωπηλή διαφθορά δεδομένων.
Ενιαίος τρόπος συμβατότητας «για τα πάντα»: διαφορετικοί τομείς απαιτούν διαφορετικούς τρόπους.
Ακατέργαστα CDC ως δημόσια συστήματα: διαρροή του μοντέλου DB, αδυναμία εξέλιξης.

Κατάλογος ελέγχου εφαρμογής

Καθορισμένη μορφή τεχνουργήματος και τρόπος συμβατότητας ανά τομέα.
Τα linters και το schema-diff είναι ρυθμισμένα σε CI, τα PR μπλοκάρονται όταν σπάνε.
Ενεργοποιημένος για ανεκτικό αναγνώστη πελατών. «addeneProperties = true» (κατά περίπτωση).
Μεγάλες αλλαγές γίνονται μέσω RFC/ADR, υπάρχει σχέδιο ηλιοβασίλεμα και διπλή εκπομπή/διπλή γραφή.
Τα κυκλώματα επισημαίνονται με PII/PCI και επίπεδα πρόσβασης. ο έλεγχος είναι ενεργοποιημένος.
Η χρήση της έκδοσης και οι αστοχίες συμβατότητας ταμπλό.
Η παραγωγή SDK/μοντέλων από το μητρώο αποτελεί μέρος του αγωγού.
Η τεκμηρίωση και τα χρυσά δείγματα επικαιροποιούνται αυτόματα.

ΣΥΧΝΈΣ ΕΡΩΤΉΣΕΙΣ

Είναι δυνατόν χωρίς μητρώο να αποθηκεύονται συστήματα στο Git

Ναι, αλλά το μητρώο προσθέτει API συμβατότητας, αναζήτηση, μεταδεδομένα, κεντρική πολιτική, και επικύρωση on-the-fly. Η καλύτερη επιλογή είναι Git ως αποθήκευση + UI/πολιτικές στην κορυφή.

Πώς επιλέγω τη λειτουργία συμβατότητας

Δείτε την κατεύθυνση της αλλαγής: εάν ο παραγωγός επεκτείνει το ωφέλιμο φορτίο - ΟΠΙΣΘΟΣ. Για το δημόσιο API/SDK - FULL. Για τα γρήγορα πρωτότυπα - προσωρινά ΟΥΔΕΝ (όχι στον κορμό).

Τι πρέπει να κάνετε αν χρειαστεί

Προετοιμασία v2: διπλή εκπομπή/διπλή, ηλιοβασίλεμα, προσαρμογείς, τηλεμετρία χρήσης, οδηγοί μετανάστευσης.

Πρέπει να επικυρώσω το ωφέλιμο φορτίο σε χρόνο λειτουργίας

Για κρίσιμους τομείς, ναι: αυτό αποτρέπει τα άχρηστα μηνύματα και επιταχύνει τη διάγνωση.

Αποτέλεσμα

Το μητρώο σχημάτων μετατρέπει την εξέλιξη των δεδομένων από τον επικίνδυνο αυτοσχεδιασμό σε μια διαχειρίσιμη διαδικασία: ενιαίους κανόνες διαλειτουργικότητας, αυτοματοποιημένες επικυρώσεις, κατανοητές εκδόσεις και διαφανές ιστορικό. Προσθέστε σε αυτό την πειθαρχία του προσθετικού-πρώτου, ανεκτικού αναγνώστη, διπλής εκπομπής και ηλιοβασίλεμα - και τα συμβόλαιά σας θα αναπτυχθούν γρήγορα, χωρίς καταρρεύσεις και νυχτερινά περιστατικά.