Πρωταρχικός σχεδιασμός πρωτοκόλλου

Τι είναι το πρωτόκολλο - πρώτο

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

Σε αντίθεση με τον κώδικα-πρώτο, όπου το API είναι μόνο ένα υποπροϊόν του κώδικα, το πρωτόκολλο-πρώτο κάνει το πρωτόκολλο ένα πρωταρχικό τεχνούργημα: κατέχει έννοιες τομέα, μοντέλα δεδομένων, καταστάσεις, λάθη, σημασιολογία idempotency, SLO/SLI, ακόμη και πολιτική έκδοσης.

Γιατί το χρειάζεστε

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

Βασική προσέγγιση

1. Ενιαία πηγή αλήθειας (SSOT) - αναγνώσιμες από μηχάνημα προδιαγραφές:

Υπόλοιπο: OpenAPI/JSON Schema.
Εκδηλώσεις και ροή: AsyncAPI, Avro/JSON Schema.
RPC: Protobuf (gRPC), Thrift, Smithy.
GraphQL: SDL + οδηγίες/πολιτικές.
2. Ρυθμίσεις πριν από την εφαρμογή: γλωσσάριο τομέα, κωδικοί σφάλματος, σημασιολογία idempotency, προθεσμίες, retrays, deduplication.
3. Autogeneration: clients/server stubs, types, SDK, test contracts, moks, Postman collections, Terraform/OpenAPI Gateway config.
4. Διακυβέρνηση: τακτικές γραμμές/πολιτικές (ονοματοδοσία, επισήμανση, φίλτρα, σφάλματα), επανεξέταση μέσω συντεχνιών API, συμβουλευτική αλλαγή για σημαντικές εκδόσεις.
5. Συμβατότητα: αυστηρή επαλήθευση της διάχυσης «μόνο για πρόσθετα», σημασιολογική μετάφραση, δοκιμές με γνώμονα καναρίνια/καταναλωτές.
6. Παρατηρησιμότητα σε επίπεδο σύμβασης: οι ταυτότητες συσχέτισης, τα μοντέλα σφάλματος, οι καθυστερημένοι προϋπολογισμοί περιγράφονται στο πρωτόκολλο.

Εμφάνιση της διαδικασίας (σκελετός)

1. Έναρξη: περίληψη προϊόντων → διαδρομές χρηστών → API/PRD πρωτοκόλλου (πόροι/μέθοδοι/εκδηλώσεις, SLA/SLO, σφάλματα, όρια).
2. Μοντελοποίηση: σχέδιο προδιαγραφής (OpenAPI/AsyncAPI/Proto) + σχήματα δεδομένων, λεξικό όρων.
3. Συμβάσεις και ενοποιήσεις UX: παραδείγματα ωφέλιμου φορτίου, συμβάσεις σφάλματος, χάρτες κατάστασης, κανόνες έκδοσης.
4. Επανεξέταση και διακυβέρνηση: τακτικές γραμμές/πρότυπα, συζήτηση των αναλλοίωτων τομέων, κλειδαριά MGC (σύμβαση ελάχιστης εγγύησης).
5. Αυτόματη δημιουργία αντικειμένων: SDK, μαχαιριές, διορθώσεις δοκιμών, αποκόμματα υποδομής (Gateways, IAM scopes).
6. Δοκιμές εφαρμογής και συμβάσεων: Ο προμηθευτής και οι καταναλωτές υποβάλλονται σε ελέγχους συμβατότητας στο ΚΚΠ.
7. Παρατηρησιμότητα και SLO: ανίχνευση συσχέτισης-id, κατάλογος σφαλμάτων, προϋπολογισμοί επαναπροσδιορισμού/χρονοδιαγράμματος.
8. Εκλύσεις και εξέλιξη: πρώτη πρόσθετη ύλη, πολιτική απόρριψης, καναρίνι, σημαίες ικανοτήτων Α/Β.

Πρωτόκολλα και στυλ αλληλεπίδρασης

REST/HTTP

Πρότυπα: μοντέλο πόρων, 'GET/POST/PATCH/DELETE', pagination (δρομέας), φίλτρα, διαλογή.
Πεδία και συστήματα: JSON Schema, μορφότυποι («ώρα ημερομηνίας», «uuid»), αναλλοίωτοι (regex/enum/min-max).
Σφάλματα: ενιαία μορφή ('type', 'code', 'title', 'detail', 'trace _ id'), χαρτογράφηση σε στοίβες HTTP.
Αλλαγή ελέγχου: ETag/If-Match, idempotent πλήκτρα για POST, ρητή σημασιολογία 409/422.

gRPC/RPC

Protobuf: σταθερή αρίθμηση ετικετών, «προαιρετική», που απαγορεύει την επαναχρησιμοποίηση διαγραμμένων πεδίων.
προθεσμίες και προτεραιότητες της σύμβασης· σταθερές καταστάσεις (OK, INVALID_ARGUMENT, FAILED_PRECONDITION κ.λπ.).
Ροή: προδιαγραφή εντολής μηνύματος, αντίθλιψη, τελικά ρυμουλκούμενα.

Καθοδηγούμενο από συμβάντα (Kafka/NATS/SNS/SQS)

AsyncAPI: θέματα/κανάλια, κλειδιά κατάτμησης, βασικές συμβάσεις αφαίρεσης, κρατήσεις, ακριβώς μία φορά σημασιολογία "εναντίον" τουλάχιστον μία φορά "

Κύριο γεγονός και εμπλουτισμός: χωριστό ελάχιστο ωφέλιμο φορτίο και επεκτάσεις. έκδοση 'event _ type '/' schema _ version'.
Ταυτότητα: 'event _ id', 'production _ id', policy on retrays and deduplication.

GraphQL

SDL ως σύμβαση, οδηγίες για την υποτίμηση, όρια βάθους και πολυπλοκότητας, κωδικοί σφάλματος/σύμβαση επέκτασης.

Ενσωμάτωση με αρχιτεκτονικές αρχές

Αντίστροφη Πυραμίδα/Κρίσιμη Διαδρομή Πρώτα: στην προδιαγραφή, τονίστε MGC (υποχρεωτικό ελάχιστο), επεκτάσεις - μέσω '? συμπεριλαμβάνονται = "/ικανότητες.
Paved Roads: ένα σύνολο έτοιμων προτύπων προδιαγραφών (πληρωμή, KYC, έλεγχος, αναζήτηση, αρχεία) + linters.
API Gateways & Service Mesh: πολιτικές βάσει συμβάσεων (όρια επιτοκίων, πεδία ταχυτήτων, ανατροπές, διακόπτες κυκλωμάτων).

Έκδοση και Εξέλιξη

• Ελάχιστο = πρόσθετα πεδία/δίαυλοι μόνο.
• Μείζων = αλλαγές διακοπής (διαγραφές, μετονομασία, αλλαγή σημασιολογίας).
• Πολιτική απόρριψης: παράθυρα υποστήριξης, κεφαλίδες 'Sunset', εκδηλώσεις κοινοποίησης.
• Συμβάσεις με γνώμονα τους καταναλωτές (ΚΕΕΛΠΝΟ): Επαλήθευση ότι το ισχύον ΣΕΠΕ ικανοποιεί συγκεκριμένους καταναλωτές.
• Κατάλογος Schema: Schema Registry/Articact Registry με κανόνες ιστορικού και συμβατότητας (BACKWARD/FORWARD/FULL).

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

Επαλήθευση/αδειοδότηση στο πλαίσιο της σύμβασης (OAuth2/OIDC πεδία εφαρμογής, mTLS, απαιτήσεις JWT).
PII/PCI: κάλυψη, μορφότυποι μαρκινοποίησης, πεδία με ειδικούς τρόπους αποθήκευσης/TTL.
Πολιτικές ελέγχου: απαιτούμενα χαρακτηριστικά («παράγοντας», «υποκείμενο», «δράση», «συνέβη _ στο», «trace _ id»).
Όρια: ονομαστικές τιμές, ποσοστώσεις, μεγέθη μηνυμάτων, προθεσμίες.

Παρατηρησιμότητα των συμβάσεων

Συσχέτιση/αναγνωριστικό αίτησης: απαιτείται στις προδιαγραφές.
Σφάλμα καταλόγου - σταθερή λίστα κωδικών και SLA για επίλυση.
SLI/SLO: p50/p95 καθυστέρηση, αναλογία επιτυχών απαντήσεων, αναλογία συμβατών γεγονότων, αναλογία idempotent επαναλήψεις.

Έλεγχος και ποιότητα

Δοκιμές συμβάσεων (πάροχος ↔ καταναλωτής), schema diff σε CI, παραγωγή διακομιστών mock.
Χρυσά δείγματα: παραδείγματα αναφοράς αιτήσεων/απαντήσεων, εξαρτήματα για το e2e.
Χάος/έγχυση καθυστέρησης: έλεγχος χρόνου/επανασυσκευασίας, υποβάθμιση των επεκτάσεων κατά την εξοικονόμηση MGC.

Υποδείγματα τομέα δείγματος

Πληρωμή (REST + Γεγονότα)

'POST/πληρωμές' '201 Δημιουργήθηκε' με 'payment _ i ,' status = εγκεκριμένο '.
Πληρωμή γεγονότος. έχει εγκριθεί. v1 '(ядро):' {payment_id, ποσό, νόμισμα, μέθοδος, occurred_at} '.
Πληρωμή παράτασης. εμπλουτισμένος. v1 ': ποσοστό κινδύνου, γεω, δακτυλικό αποτύπωμα συσκευής.
Σφάλματα: '422' (επικύρωση), '402' (απαιτούμενη πληρωμή), '409' (αντίγραφο).
SLA: έγκριση ≤ 800ms p95, εκδήλωση πυρήνα ≤ 2c lag p95.

KYC (gRPC + ουρές αναμονής)

RPC 'StartVerification (user_id)' → 'operation _ id'.
Εκδηλώσεις προόδου στο θέμα 'kyc. κατάσταση. v1 '(' ΕΚΚΡΕΜΕΙ '→' ΕΓΚΡΙΘΗΚΕ/ΑΠΟΡΡΙΦΘΗΚΕ ').
Η σύμβαση ορίζει πεδία PII, διάρκεια ζωής, κάλυψη, κωδικούς αιτιώδους αποτυχίας.

Έλεγχος (μόνο περιστατικό)

"audit. έχει καταγραφεί. v1 '(ядро):' ηθοποιός ',' υποκείμενο ',' δράση ',' συνέβη _ ',' ίχνος _ id '.
Εμπλουτισμός: IP, συσκευή, geo - ένα ξεχωριστό συμβάν/νήμα, δεν εμποδίζει τον πυρήνα.

Εργαλεία και αυτοματοποίηση (κατά προσέγγιση στοίβα)

: OpenAPI/AsyncAPI/Protobuf/Avro/GraphQL SDL.
: Spectral, OpenAPI Diff, Buf (protobuf), Confluent SR έλεγχοι συμβατότητας.
: OpenAPI Generator, Buf/ Генерация, GraphQL Codegen, AsyncAPI Generator.
Πύλη: Kong/Apigee/Azure/GCP GW, Απεσταλμένος.
: Σύμφωνο/CDC, Dredd, Schemathesis, Hoverfly, MockServer.
Μητρώο: Git-directory of schemes + Schema Registry/Artifact Registry.
Τεκμηρίωση: Redocly/Stoplight/Swagger-UI/GraphiQL/Explorer.

Αντι-μοτίβα

Κωδικός-πρώτα κατά ατύχημα: «MVP πρώτα για τους ελεγκτές», μετα-πραγματικές προδιαγραφές, απόκλιση μεταξύ τεκμηρίωσης και συμπεριφοράς.
Swagger-wash: ένα επίσημο OpenAPI χωρίς πραγματικούς κανόνες (σφάλματα, όρια, SLA, εκδόσεις).
Διακοπή συμβατότητας: αφαιρέθηκε το πεδίο/άλλαξε ο τύπος χωρίς σημαντική έκδοση. επαναχρησιμοποίηση ετικετών protobuf.
απόκριση «πάχους» χωρίς επισήμανση/φίλτρα· έλλειψη ευελιξίας.
Ασφάλεια εκτός σύμβασης: auth/scopes περιγράφονται στο wiki, αλλά όχι στις προδιαγραφές.

Σχέση με την οργάνωση της επεξεργασίας

API Guild: διαχειριστές προτύπων, επανεξετάσεις αλλαγών, κατάρτιση.
Έγγραφα σχεδιασμού: για κάθε API - PRD, ADR (λύσεις), SLA, πίνακας κινδύνου.
Διαχείριση αλλαγών: διαδικασία RFC, σημειώσεις απελευθέρωσης, οδηγοί μετανάστευσης, χρονοδιάγραμμα απόκλισης.
Paved Road & Templates: γεννήτριες-πλαίσιο υπηρεσιών από τις προδιαγραφές (χειριστής σκελετός, επικύρωση, υλοτομία).

Κατάλογοι ελέγχου

Πριν από την έναρξη

• Υπάρχει ένα PRD και ένα γλωσσάριο τομέα.
• Επιλεγμένο στυλ (REST/gRPC/Event/GraphQL) και μορφή σχήματος.
• MGC, σφάλματα, SLA/SLO, ορισμένοι κανόνες ταυτότητας.

Υπό ανάπτυξη

• Η προδιαγραφή περνά τα χιτώνια και την ανασκόπηση.
• Η αυτόματη παραγωγή SDK/Stable/Fixture είναι ρυθμισμένη.
• Οι δοκιμές επί συμβάσει (CDC) περιλαμβάνονται στο CI. Το σχήμα-diff μπλοκάρει ασύμβατες αλλαγές.

Πριν την απελευθέρωση

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

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

Πώς διαφέρει το πρώτο πρωτόκολλο από το πρώτο API

Συχνά οι όροι χρησιμοποιούνται εναλλακτικά. Σε αυτό το άρθρο βάσει του Πρωτοκόλλου-πρώτα, τονίζουμε την ακαμψία της σύμβασης και την κάλυψη όλων των στυλ (REST/RPC/Events/GraphQL), συμπεριλαμβανομένης της SLA, της ασφάλειας και της παρατηρησιμότητας.

Αυτό θα επιβραδύνει την ανάπτυξη

Η αρχή μπορεί να είναι λίγο μεγαλύτερη, αλλά στη συνέχεια κερδίζουμε με ολοκλήρωση, σταθερότητα και παράλληλες ταχύτητες ανάπτυξης (αυτόματη γενιά, σταθερά SDK).

Τι να κάνουμε με τα γρήγορα πειράματα

Χρήση «σχεδίων» εκδόσεων συστημάτων (σχέδιο), σημαιών και αμμοκιβωτίων, χωρίς όμως να παραλείπεται η χρήση γραμμών και βασικών κανόνων συμβατότητας.

Σύνολο

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