Έλεγχος συμβάσεων

1) Πού πρέπει να εφαρμοστούν οι συμβάσεις

HTTP REST/JSON: πόροι, σελιδοποίηση, φίλτρα, ταυτότητα, κωδικοί σφάλματος.
gRPC/Protobuf: τύποι μηνυμάτων, καταστάσεις, σημασιολογία «προθεσμίας», οπισθοδρόμηση v.proto.
GraphQL: σχήματα, μη άκυρα, οδηγίες, ανεκτικά σε πεδία.
Μηνύματα/ροές (Kafka/Pulsar/SQS): συστήματα εκδηλώσεων (Avro/JSON/Protobuf), κλειδιά κατάτμησης, σειρά, idempotent κλειδιά.
Εσωτερικά ΣΒΑ/Βιβλιοθήκες: δημόσια χαρακτηριστικά/εξαιρέσεις/συμβάσεις επιδόσεων.

2) Μοντέλο CDC: Ρόλοι και αντικείμενα

Ο καταναλωτής δημοσιεύει τη σύμβαση προσδοκιών (δειγματοληπτικές αιτήσεις/απαντήσεις, ταιριαστές τύπου, αμετάβλητες).
Ο προμηθευτής διενεργεί επαλήθευση της σύμβασης με βάση την υπηρεσία/τον προσαρμογέα/τους χειριστές του.
Ο μεσίτης (Pact Broker/Backstage/repo articact) αποθηκεύει εκδόσεις, ετικέτες ('prod', 'staging', 'canary') και τον πίνακα συμβατότητας 'consumer @ v → provider @ v'.
Πολιτική αποδέσμευσης: η αποστολή ενός παρόχου απαγορεύεται σε περίπτωση παραβίασης οποιασδήποτε «σχετικής» σύμβασης.

3) Τι να καθορίσετε στη σύμβαση (παράδειγμα HTTP)

• Μέθοδος/διαδρομή/παράμετροι/κεφαλίδες (συμπεριλαμβανομένης της Auth, idempotent πλήκτρο).
• Το σώμα και οι τυπικοί ταιριαστές (τύπος/μορφή/regexp/εύρος).
• Κωδικοί και δομή σφάλματος. stable 'error _ code'.
• Σημασιολογικές αναλλοίωτες: διαλογή, μοναδικότητα, μονοτονία 'δημιουργήθηκε _ a .
• Μη λειτουργικές προσδοκίες (προαιρετικά): p95, όρια μεγέθους, κεφαλίδες ορίου ταχύτητας.

json
{
"interaction": "GET /v1/users/{id}",
"request": { "method": "GET", "path": "/v1/users/123", "headers": {"Accept":"application/json"} },
"matchers": {
"response.body.id": "type:number",
"response.body.email": "regex:^.+@.+\\..+$",
"response.body.created_at": "format:rfc3339"
},
"response": {
"status": 200,
"headers": {"Content-Type":"application/json"},
"body": {"id": 123, "email": "alice@example.com", "created_at": "2025-10-31T12:00:00Z"}
},
"error_cases": [
{
"name":"not_found",
"request":{"path":"/v1/users/9999"},
"response":{"status":404, "body":{"error_code":"USER_NOT_FOUND"}}
}
]
}

4) Συμβάσεις με γνώμονα γεγονότα

Σχήμα γεγονότων: 'τύπος', 'έκδοση', 'i ,' συνέβη _ at _ utc ',' παραγωγός ',' υποκείμενο ',' ωφέλιμο φορτίο '.
Αναλλοίωτες: αναλλοίωτη 'id' και idempotence με '(τύπος, id)', σειρά μέσα στο κλειδί του μέρους, μονοτονία 'ακολουθία'.
Schema Registry-Stores εξέλιξη και κανόνες συμβατότητας (προς τα πίσω/προς τα εμπρός/πλήρης).
Δοκιμές συμβάσεων με καταναλωτές: επανάληψη «χρυσών» γεγονότων και φάσεων αρνητικών (άγνωστα πεδία, εκμηδενίσιμα).

json
{
"type":"record","name":"UserRegistered","namespace":"events.v1",
"fields":[
{"name":"id","type":"string"},
{"name":"occurred_at_utc","type":{"type":"long","logicalType":"timestamp-millis"}},
{"name":"email","type":"string"},
{"name":"marketing_opt_in","type":["null","boolean"],"default":null}
]
}

5) Εξέλιξη και συμβατότητα

Συμβατικές εκδόσεις: σημασιολογία «MAJOR». MINOR. PATCH '(MAJOR - θραύση).

• Μην σπάσετε: μην διαγράψετε πεδία, μην αλλάξετε τον τύπο/την τιμή 'error _ code'.
• Προσθήκη προαιρετικών πεδίων με προεπιλογή. νέα τελικά σημεία αντί για «μαγεία».
• Μείωση: δήλωση, ταυτόχρονη υποστήριξη, διαγραφή με μετρήσεις.
• GraphQL: πρόσθετα μόνο πεδία, μη μηδενικά εισέρχονται σε φάσεις. θέσπιση οδηγιών.
• gRPC/Proto: μη επαναχρησιμοποιήσετε αριθμούς πεδίου· προσθήκη μόνο νέων με προαιρετική προσθήκη.
• Εκδηλώσεις: σύστημα «vN», οι καταναλωτές υποχρεούνται να αγνοούν άγνωστους τομείς (επιείκεια).

6) Αρνητικοί και αναλλοίωτοι έλεγχοι

Αρνητικό: εσφαλμένοι τύποι, απαγορευμένες τιμές, αντικρουόμενες παράμετροι, υπέρβαση ορίων.
Αναλλοίωτες: διαλογή των απαντήσεων, μοναδικότητα του 'id', ορθότητα του 'next _ cursor', σταθερότητα της idempotent απόκρισης όταν επαναλαμβάνεται.
Συμβάσεις προσωρινών πτυχών: "created _ a , η ορθή πρόβλεψη των τοπικών ημερών δεν αποτελεί μέρος της σύμβασης μεταφοράς - υποβάλλεται σε αναλλοίωτες επιχειρήσεις.

7) Παραγωγή μαχαιριών και τοπική ανάπτυξη

Από τις συμβάσεις δημιουργούνται στοίβες για την ανάπτυξη των καταναλωτών.
Για γεγονότα - γεννήτριες μηνυμάτων «έγκυρων/οριακών» σύμφωνα με το σύστημα.
Οι υπάλληλοι σημειώνονται με την έκδοση της σύμβασης και την ημερομηνία κατασκευής. δημοσίευση σε prod.

8) Ενσωμάτωση σε CI/CD (αγωγός αναφοράς)

1. CI για τους καταναλωτές:

Lint/build → contract generation → unit/test contract → publish in contract-broker (tag: 'consumer @ 1. 7. 0`).

2. Πάροχος CI:

Η αύξηση της υπηρεσίας σε τοπικό επίπεδο/στο εμπορευματοκιβώτιο → φέρει τις σχετικές συμβάσεις («prod »/« stage») → επαλήθευση → δημοσίευση του καθεστώτος του μεσίτη.

3. Πύλη απελευθέρωσης:

Η εγκατάσταση του παρόχου εμποδίζεται εάν υπάρχουν εκκρεμείς συμβάσεις.

4. Νυχτερινή μήτρα:

Πίνακας συμβατότητας «εκδόσεις καταναλωτών × εκδόσεις παρόχων», αναφορές και συναγερμοί.

9) Παραδείγματα πρακτικών ανά τομέα

9. 1 REST: σελιδοποίηση δρομέα (αμετάβλητη σύμβαση)

Η απάντηση περιέχει «στοιχεία []», «επόμενο _ δρομέα» (μηδενικό), «όριο», «σύνολο» (προαιρετικό).
Αναλλοίωτες: 'len (items) ≤ limit', επαναλαμβανόμενη κλήση με το ίδιο 'cursor' → idempotent set.
Σφάλμα αν το 'cursor' και 'page' είναι και τα δύο καθορισμένα.

9. 2 POST idempotency

Το συμβόλαιο απαιτεί κεφαλίδα 'Idempotency-Key'.
Αναλλοίωτο: Ένα επαναλαμβανόμενο ερώτημα με το ίδιο κλειδί επιστρέφει το ίδιο 'id '/status.

9. 3 Γεγονότα: εγγυήσεις τάξης

Η κλείδα κατάτμησης στη σύμβαση είναι 'κατάτμηση _ κλειδί = user_id'.
Αναλλοίωτη: η «ακολουθία» αυξάνεται μονοτονικά εντός του κλειδιού. ο καταναλωτής πρέπει να χειρίζεται τις επαναλήψεις.

10) Ασφάλεια και προστασία της ιδιωτικής ζωής στις συμβάσεις

Δεν περιλαμβάνονται δεδομένα/μυστικά προσωπικού χαρακτήρα σε παραδείγματα - μόνο συνθετικά.
Ορισμός υποχρεωτικών κεφαλίδων ασφαλείας: 'Εξουσιοδότηση', 'Υπογραφή Χ', 'Αναπαραγωγή-Πρόληψη'.
Για webhooks - υπογραφή και σύμβαση απόκρισης '2xx '/retrays.
Στα αρχεία καταγραφής των συμβατικών δοκιμών - κάλυψη ευαίσθητων πεδίων.

11) Εργαλεία

Pact/Pactflow/Pact Broker - HTTP/Message contracts, πίνακας συμβατότητας.
OpenAPI/AsyncAPI - προδιαγραφές + γεννήτριες δοκιμών (Dredd, Schemathesis).
Karate/REST Assured - έλεγχοι σεναρίων συμβάσεων REST.
Protobuf/gRPC - 'buf', 'protolint', δοκιμές συμβατότητας, Μητρώο Schema για Avro/JSON/Proto σε ρεύματα.
Δοκιμές συμμόρφωσης για GraphQL (graphql-compat), δοκιμές στιγμιαίου κυκλώματος.

12) Ψευδοκώδικας επαλήθευσης του παρόχου (απλοποιημένος)

python def verify_contract(provider, contract):
for case in contract["cases"]:
req = build_request(case["request"])
res = provider.handle(req) # локально/контейнер assert match_status(res.status, case["response"]["status"])
assert match_headers(res.headers, case["response"].get("headers", {}))
assert match_body(res.body, case["matchers"], allow_extra_fields=True)
for neg in contract.get("error_cases", []):
res = provider.handle(build_request(neg["request"]))
assert res.status == neg["response"]["status"]
assert res.json.get("error_code") == neg["response"]["body"]["error_code"]

13) Αντι-μοτίβα

«Τα στιγμιότυπα οθόνης του ταχυδρόμου είναι συμβόλαιο»: δεν υπάρχουν εκδόσεις/τυπικοί ταιριαστές/αυτόματη επικύρωση.
Υπερκάλυψη: η σύμβαση καθορίζει ακριβείς τιμές αντί για τύπους/πρότυπα → ψευδείς πτώσεις.
Μια κοινή σύμβαση για διάφορες περιφέρειες/διαύλους: αγνοεί τη μεταβλητότητα (σημαίες, γεωλογικοί κανόνες).
Συμβάσεις χωρίς μεσίτη/πίνακα: είναι αδύνατο να κατανοηθεί ποιες εκδόσεις είναι συμβατές.
Στοίχημα για e2e αντί για συμβάσεις: αργή, ακριβή, ασταθής.
Καμία αρνητική/αμετάβλητη περίπτωση: ελέγχεται μόνο η «πράσινη τροχιά».

14) Παρατηρησιμότητα και λειτουργία

Κατάσταση εξαγωγών για μεσίτες + ταμπλό «συμβάσεις υγείας».
Καταχωρίσεις: νέες μειώσεις του παρόχου έναντι συμβάσεων «prod», αύξηση του «άγνωστου πεδίου» σε γεγονότα.
Ίχνος: 'contract _ id', 'version', 'decision _ id' στα αρχεία καταγραφής επαλήθευσης.

15) Διαδικασία κατάθλιψης

1. Προσθήκη πεδίου/τελικού σημείου (μη θραύση).
2. Σημειώστε το παλιό ως 'εγκαταλελειμμένο' στην προδιαγραφή, ανακοινώστε τις ημερομηνίες.
3. Εντοπισμός των καταναλωτών από κορμοτεμάχια/μεσίτες· οδηγοί μετανάστευσης.
4. Ενεργοποίηση «σκιώδους» άρνησης στο στάδιο (ξηρό τρέξιμο), στη συνέχεια επιβολή.
5. Διαγράφεται μετά το μηδέν η χρήση και η συμβατότητα.

16) Κατάλογος ελέγχου αρχιτεκτόνων

1. Προσδιορισμός των καταναλωτών και των ιδιοκτητών τους Οι συμβάσεις εκδίδονται

2. Υπάρχει μεσίτης και πίνακας συμβατότητας με ετικέτες περιβάλλοντος

3. Περιλαμβάνονται αρνητικά και αναλλοίωτα (ιδιοτέλεια, δρομείς, διαλογή) στη σύμβαση

4. Ρυθμίζεται η λειτουργία Schema και συμβατότητας για γεγονότα

5. Ο αγωγός εμποδίζει την αποδέσμευση του παρόχου σε περίπτωση παραβίασης των συμβάσεων παραγωγής

6. Περιγράφεται η διαδικασία απερήμωσης και η πολιτική εξέλιξης

7. Οι μαχαιριές παράγονται από συμβάσεις, υπάρχουν τοπικοί παραγωγοί εκδηλώσεων

8. Τεκμηριώνεται η κάλυψη της PD και οι υποχρεωτικές επικεφαλίδες ασφαλείας

9. Συνδέονται μετρήσεις/προειδοποιήσεις για συμβάσεις, υπάρχουν παρασυρόμενες αναφορές

10. Οι συμβάσεις επανεξετάζονται στο ΚΚΠ από αμφότερα τα μέρη (καταναλωτές και πάροχοι)

Συμπέρασμα

Ο έλεγχος συμβάσεων μεταφέρει την «αλήθεια» για τις αλληλεπιδράσεις σε επαληθευμένα αντικείμενα και καθιστά προβλέψιμες τις ενσωματώσεις. Το CDC, ο μεσίτης συμβάσεων και η πειθαρχία εξέλιξης του συστήματος αντικαθιστούν τις «εκπλήξεις που σπάνε» με μια διαδικασία διαχείρισης: γρήγορους ελέγχους, σαφείς αναλλοίωτους και διαφανή συμβατότητα έκδοσης. Αυτό μειώνει το κόστος του e2e, επιταχύνει τις εκλύσεις και βελτιώνει την ποιότητα ολόκληρης της πλατφόρμας.