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

1) Γιατί δοκιμές επί συμβάσει

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

2) Προσεγγίσεις

Συμβάσεις με γνώμονα τους καταναλωτές (CDC): ο πελάτης δημιουργεί προσδοκίες (Σύμφωνο και ανάλογες)· ο πάροχος τις επαληθεύει τακτικά.
Προδιαγραφή: σύμβαση ως ενιαία πηγή αλήθειας (OpenAPI/Protobuf/GraphQL SDL)· οι δοκιμές επικυρώνουν την εφαρμογή με βάση τις προδιαγραφές.
Σύστημα μηνυμάτων (Avro/JSON Schema/Protobuf) + κανόνες συμβατότητας μεσίτη/μητρώου.

3) Ροή προδιαγραφών HTTP/REST

1. Σύμβαση: OpenAPI 3. x (διαγράμματα, παραδείγματα, κωδικοί).
2. Ανάλυση Lint και stat: στυλ, απαιτούμενα πεδία, ενιαίοι κωδικοί.
3. Επικύρωση εφαρμογής: γεννήτρια δοκιμών anti-OpenAPI (σχηματισμός/προσέγγιση Dredd) + χειροκίνητα αρνητικά.
4. Στιγμιότυπα: λήψη δειγμάτων απόκρισης, σημασιολογία ETag, κεφαλίδες ιδεατότητας.

yaml paths:
/v1/payments:
post:
responses:
"201": { $ref: "#/components/responses/PaymentCreated" }
"409": { description: Duplicate by Idempotency-Key }
"422": { description: Schema/Business validation failed }

4) CDC (προσέγγιση του Συμφώνου)

1. Ο καταναλωτής γράφει ένα τεστ, δημιουργεί ένα αρχείο συμφώνου (προσδοκίες).

2. Δημοσίευση σε μεσίτη (τεχνούργημα).

3. Ο πάροχος στον ΚΚΠ αυξάνει τις υπηρεσίες (ή τις συμβάσεις), επαληθεύει τις υπηρεσίες του συμφώνου.

4. Ο μεσίτης υπολογίζει τον πίνακα συμβατότητας.

js pact
.given("wallet exists")
.uponReceiving("get wallet")
.withRequest({ method:"GET", path:"/v1/wallets/w123", headers:{ "Authorization": term({generate:"Bearer x", matcher:/^Bearer\s.+/}) }})
.willRespondWith({
status: 200,
headers: { "Content-Type": "application/json" },
body: like({ id:"w123", currency: "EUR", balance: 0 })
});

5) Συμβάσεις gRPC/Protobuf

Η σύμβαση είναι ".proto 'with package/service versioning.
Συμβατότητα: μην επαναχρησιμοποιείτε ετικέτες, προσθέστε μόνο νέες με προαιρετικές, μην διαγράψετε τα χρησιμοποιούμενα πεδία. αριθμοί αποθεματικών.
Δοκιμές: server/client stab generation, αυτόματη ενοικίαση περίπτωσης + αρνητικά (άγνωστα πεδία, όρια μεγέθους).

6) Συμβάσεις γεγονότων (Kafka/NATS/...)

Μητρώο Avro/JSON Schema/Protobuf Schema.
Η πολιτική συμβατότητας είναι «BACKWARD» (συχνά αρκετά) ή «FULL».
Δοκιμές παραγωγού: επικυρώνει το μήνυμα κατά του συστήματος. δοκιμές καταναλωτή: αποδέχεται παλαιές και νέες εκδόσεις.
Αναλλοίωτα: idempotence keys, order/repreatability, deduplication semantics.

json
{"type":"record","name":"PayoutCreated","fields":[
{"name":"payoutId","type":"string"},
{"name":"amount","type":"double"},
{"name":"currency","type":{"type":"string","logicalType":"iso-4217"}}
]}

7) Συμβατότητα και εκδόσεις

Συμβατό προς τα πίσω (συνιστώμενο ελάχιστο): προσθήκη προαιρετικών πεδίων, μη θραύσματα υφιστάμενων.
Συμβατό προς το μέλλον: Οι καταναλωτές αγνοούν άγνωστα πεδία.
Πλήρες: Και τα δύο.
Έκδοση: 'διαδρομή (/v1)', 'Αποδοχή: εφαρμογή/vnd. μάρκα. v2 + json ',' proto package v2 '.
Πολιτική απόκλισης: παράθυρο εξόδου (π.χ. 90 ημέρες), κεφαλίδες/γεγονότα προειδοποίησης.

8) Αρνητικά και λάθη είναι επίσης συμβόλαιο

Τυποποιήστε τους κωδικούς: 400/401/403/404/409/422/429/5xx, υποχρεωτικά πεδία 'code', 'message', 'trace _ id'.
Τα μεγέθη/όρια αποτελούν μέρος της σύμβασης (413/414/431).
Ιδιαιτερότητα: συμπεριφορά επανάληψης (409 έναντι 201 ίδιας ταυτότητας).
Επικεφαλίδες: 'Retry-After' at 429/503, 'Idempotency-Key', 'Content-Language' κ.λπ.

json
{ "code":"validation_error", "message":"amount must be ≥ 1", "trace_id":"..." }

9) Δεδομένα που διαχειρίζεται η σύμβαση

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

10) Αγωγός σε CI/CD (αναφορά)

1. Lint/επικύρωση: OpenAPI/Proto/Avro ('επικύρωση', style- линер).
2. Δημοσίευση: Σύμβαση ως τεχνούργημα (μεσίτης/μητρώο).
3. Επαλήθευση: ο πάροχος εκτελεί τα πακέτα CDC/δοκιμές προδιαγραφών.
4. can-i-deploy πύλη: καμία απελευθέρωση δεν επιτρέπεται χωρίς πράσινη μήτρα.
5. Diff-Επαληθεύει ότι οι αλλαγές είναι σημασιολογικές diff.
6. Έκθεση: JUnit/HTML, κατάλογος παραβάσεων/ορισμών.

yaml jobs:
lint:...
publish-contract: needs: [lint]
verify-provider: needs: [publish-contract]
can-i-deploy:
if: always()
steps: [run: pact-broker can-i-deploy...]

11) Εργαλεία (ανά κατηγορία εργασίας)

Lint/επικυρωτές: openapi-linters, protobuf-lint, avro-tools.
CDC: Οικογένεια/μεσίτης του Συμφώνου, Σύμβαση εαρινού νέφους, Hoverfly (αρχεία/επαναλήψεις HTTP).
Δρομείς προδιαγραφών: σχηματοποίηση/προσέγγιση τύπου Dredd, δοκιμή Postman + JSON Schema.
Diff: σημασιολογικό-diff OpenAPI/Proto/Avro (ανιχνεύει αλλαγές θραύσης).
Εμπορευματοκιβώτια: Testcontainers για την ανύψωση του παρόχου/συμβασιούχου γραφείου.

12) Αντιπατερίδια

«Ειδική δεξαμενή» χωριστά από τον κωδικό → αποσυγχρονισμού. Κρατήστε τη σύμβαση κοντά στην υπηρεσία.
Moki μιας υπηρεσίας τρίτου μέρους αντί μιας σύμβασης → εύθραυστη κατά τη διάρκεια επικαιροποιήσεων.
Τυχαίες αντιδράσεις/παραγωγή χωρίς δέσμευση στο σύστημα → flake.
Αλλαγή τύπων/υποχρεωτικών πεδίων χωρίς έκδοση.
Σιωπηλές επεκτάσεις χωρίς κοινοποίηση/μείωση.
Δεν υπάρχουν αρνητικές συμβάσεις και κωδικοί σφάλματος.

13) Ιδιαιτερότητες του iGaming/Finance

Επισημοποιήστε τα χρηματικά πεδία: «ποσό» - δεκαδικό με κλίμακα, νόμισμα - ISO-4217, αναλλοίωτα ποσά.
Συμβόλαια πληρωμής/webhook: HMAC/mTLS, anti-replay (παράθυρο 'X-Timestamp'), idempotency, 'Retry-After'.
Περιφερειακός χαρακτήρας/ενοικιαστές: υποχρεωτικές επικεφαλίδες «X-Tenant/X-Region», εντοπισμός μηνυμάτων.
Γεγονότα: αμετάβλητα αρχεία καταγραφής (έλεγχος), κλειδιά αποπληρωμής, εγγυήσεις παράδοσης (τουλάχιστον μία φορά + idempotent handlers).

14) Παραδείγματα «σκελετών» δοκιμών

14. 1 Στυλ σχηματισμού (ψευδο)

bash schemathesis run openapi. yaml --checks all --hypothesis-deadline=200

14. 2 Ταχυδρόμος

js pm. test ("Scheme/v1/wallets/{ id} is valid," () => {
const schema = pm. collectionVariables. get("wallet_get_schema");
pm. expect(ajv. validate(JSON. parse(schema), pm. response. json())). to. be. true;
});

14. Επαλήθευση παρόχου CDC (Pseudo)

bash pact-broker can-i-deploy --pacticipant wallets --version $SHA --to-environment staging

15) Κατάλογος ελέγχου ετοιμότητας Prod

• Συμβάσεις στο αποθετήριο, ο ΚΚΠ επικυρώνει και δημοσιεύει αντικείμενα.
• Το ΚΕΕΛΠΝΟ είναι ενεργοποιημένο για κρίσιμη ολοκλήρωση. εργασίες μεσίτη/πίνακα «can-i-deploying».
• Τεκμηριωμένη πολιτική συμβατότητας (HTTP/gRPC/Events). αυτόματο σημασιολογικό diff.
• Αρνητικές συμβάσεις: σφάλματα, όρια μεγέθους, ταυτότητα, «Retry-After».
• Τα δεδομένα δοκιμών είναι καθοριστικά. Υποστηρίζονται στιγμιότυπα παραδειγμάτων.
• Έκδοση και απαλλαγή: προθεσμίες, κοινοποιήσεις, κεφαλίδες.
• Για γεγονότα - Schema Registry και λειτουργία συμβατότητας. Ο παραγωγός/καταναλωτής ελέγχει και τις δύο εκδόσεις.
• Αντικείμενα: JUnit/HTML, diff/επαλήθευση αναφορών, πίνακας συμβατότητας.
• Διαδικασία συμβάντος: ταχεία ανατροπή σύμβασης/σημαία χαρακτηριστικών, κοινοποίηση στους ενοποιητές.

16) TL· DR

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