პროტოკოლის პირველი დიზაინი

რა არის Protocol-first

Protocol-first არის მიდგომა, რომელშიც კომპონენტებს შორის ურთიერთქმედების ხელშეკრულება (სერვისები, მომხმარებლები, გარე პარტნიორები) შექმნილია და ფიქსირდება განხორციელებამდე. კოდი, შენახვა, ინფრასტრუქტურა და დოკუმენტაცია ემორჩილება კონტრაქტს და ავტომატურად წარმოიქმნება მისგან და არა პირიქით.

Code-first- ისგან განსხვავებით, სადაც API მხოლოდ კოდის გვერდითი პროდუქტია, Protocol-first პროტოკოლს პირველადი არტეფაქტად აქცევს: იგი ფლობს დომენის, მონაცემთა მოდელის, სტატუსის, შეცდომების, იდემპოტენტურობის სემანტიკას, SLO/SLI და თუნდაც ვერსიის პოლიტიკას.

რატომ გჭირდებათ ეს

ინტერფეისების კოორდინაცია და პროგნოზირება ორგანიზაციის მასშტაბით.
სწრაფი onboarding (ავტომატური წარმოება SDK/სტაბილურობა/კლიენტები, შეცდომები და კოდები).
საიმედო ევოლუცია (სქემების თავსებადობა, ტესტის კონტრაქტები, ვერსიის მკაფიო პოლიტიკა).
პროდუქტის ფოკუსი: კოდის დაწერამდე განვიხილავთ ქცევას, SLA და UX ინტეგრაციას.
ავტომატიზაცია: CI/CD აგროვებს ნივთებს (მომხმარებლები, სერვერის დანამატები, დამადასტურებლები) ჭეშმარიტების ერთი წყაროდან.
უსაფრთხოება და შესაბამისობა: უფლებები, PII შენიღბვა, რეტენციული პოლიტიკა გათვალისწინებულია ხელშეკრულებაში.

მიდგომის ბირთვი

1. ჭეშმარიტების ერთი წყარო (SSOT) არის მანქანების წაკითხული სპეციფიკაციები:

REST: OpenAPI/JSON Schema.
მოვლენები და ნაკადი: AsyncAPI, Avro/JSON Schema.
RPC: Protobuf (gRPC), Thrift, Smithy.
GraphQL: SDL + დირექტივები/პოლიტიკა.
2. შეთანხმებები განხორციელებამდე: დომენის ტერმინალი, შეცდომების კოდები, immpotention სემანტიკა, ვადები, rettray, დედაპლიკაცია.
3. ავტომწარმოებელი: მომხმარებლები/სერვერის სტაბილურობა, ტიპები, SDK, სატესტო კონტრაქტები, ხიდები, Postman კოლექციები, Terraform/OpenAPI Gateway კონფისკაცია.
4. მთავრობა: ლინტერი/პოლიტიკა (დანამატი, პაგინაცია, ფილტრები, შეცდომები), მიმოხილვა API გილდიის საშუალებით, ძირითადი ვერსიებისთვის გადაკეთება-ადაპტაცია.
5. თავსებადობა: „additive-only“ დიფების მკაცრი გადამოწმება, სემანტიკური ვერსია, კანარი/consumer-driven ტესტები.
6. დაკვირვება ხელშეკრულების დონეზე: კორელაციის ID, შეცდომების მოდელები, შეფერხებების ბიუჯეტები ასახულია ოქმში.

როგორ გამოიყურება პროცესი (ჩონჩხი)

1. ინიციაცია: სასურსათო ბრიფინგი - სამომხმარებლო ჟურნალი API/Protocol PRD (რესურსები/მეთოდები/მოვლენები, SLA/SLO, შეცდომები, ლიმიტები).
2. მოდელირება: სპეციფიკაციის პროექტი (OpenAPI/AsyncAPI/Proto) + მონაცემთა სქემები, ტერმინების ლექსიკონი.
3. ხელშეკრულებები და UX ინტეგრაცია: დატვირთვის მაგალითები, შეცდომების კონტრაქტები, სტატუსის ბარათები, ვერსიის წესები.
4. Review and governance: linters/სტანდარტები, დომენის ინვარიანტების განხილვა, lock-in MGC (მინიმალური საგარანტიო ხელშეკრულება).
5. არტეფაქტების ავტომატური წარმოება: SDK, სტაბილურობა, სატესტო ფიქსაცია, ინფრასტრუქტურის დანამატები (Gateways, IAM scopes).
6. განხორციელება და კონტრაქტის ტესტები: მიმწოდებლები და მომხმარებლები შეამოწმებენ თავსებადობას CI- ში.
7. დაკვირვება და SLO: correlation-id, error catalog, retray/Taimaut- ის ბიუჯეტები.
8. გამოშვებები და ევოლუცია: additive-first, deprecation policy, canary, A/B კაპიტალური flags.

ოქმები და ურთიერთქმედების სტილი

REST/HTTP

სტანდარტები: რესურსების მოდელი, 'GET/POST/PATCH/DELETE', პაგინაცია (cursor), ფილტრები, დახარისხება.
ველები და სქემები: JSON Schema, ფორმატები ('date-time', 'uuid'), ინვარიანტები (regex/enum/min-max).
შეცდომები: ერთი ფორმატი ('ტიპი', 'code', 'title', 'detail', 'trace _ id'), HTTP მინა.
ცვლილების კონტროლი: ETag/If-Match, idempotent გასაღებები POST- სთვის, ექსპლიციტური სემანტიკა 409/422.

gRPC/RPC

Protobuf: ჭდეების სტაბილური ნუმერაცია, 'optional', დისტანციური ველების ხელახალი გამოყენების აკრძალვა.
Deadlines და პრიორიტეტები ხელშეკრულებაში; სტაბილური სტატუსები (OK, INVALID _ ARGUMENT, FAILED _ PRECONDITION, etc.).
Streaming: შეტყობინებების პროცედურის სპეციფიკაცია, backpressure, საბოლოო ტრეილერები.

Event-driven (Kafka/NATS/SNS/SQS)

AsyncAPI: თემები/არხები, განაწილების გასაღებები, ხელშეკრულებები დედუპლიკაციის კლავიშების, რეტენციების შესახებ, სემანტიკა „ზუსტად ერთხელ“ vs „ერთხელ მაინც“.
მოვლენა ბირთვი და გამდიდრება: გაიზიარეთ მინიმალური payload და გაფართოება; მიუთითეთ 'event _ type '/' schema _ version'.
Idempotention: 'event _ id', 'producer _ id', პოლიცია ჭრილობებზე და შუამდგომლობებზე.

GraphQL

SDL, როგორც კონტრაქტი, დეპრესიის დირექტივები, სიღრმე და სირთულეები, შეცდომის ხელშეკრულება (error codes/extensions).

ინტეგრაცია არქიტექტურულ პრინციპებთან

Inverse Pyramid/Critical Path First: სპეციფიკაციაში განასხვავეთ MGC (სავალდებულო მინიმუმი), გაფართოებები - '? include = '/capabilities.
Paved Roads: მზა სპეციფიკაციის შაბლონების ნაკრები (payment, KYC, audit, search, files) + ლინტერი.
API Gateways & Service Mesh: ხელშეკრულებაზე დაფუძნებული პოლიტიკოსები (საბაზო ლიმიტები, auth scopes, retries, circuit-breakers).

ვერსია და ევოლუცია

• Minor = მხოლოდ დანამატის ველები/არხები.
• მაიორი = დაშლის ცვლილებები (წაშლა, შეცვლა, სემანტიკის ცვლილება).
• Deprecation Policy: დამხმარე ფანჯრები, სათაურები 'Sunset', შეტყობინებების მოვლენები.
• Consumer-Driven Contracts (CDC): ჩვენ ვამოწმებთ, რომ ამჟამინდელი API აკმაყოფილებს კონკრეტულ მომხმარებლებს.
• სქემების კატალოგი: რეესტრი (Schema Registry/Artifact Registry) ისტორიისა და თავსებადობის წესებით (BACKWARD/FORWARD/FULL).

უსაფრთხოება და შესაბამისობა

ავთენტიფიკაცია/ავტორიზაცია, როგორც ხელშეკრულების ნაწილი (OAuth2/OIDC scopes, mTLS, JWT კლასები).
PII/PCI: შენიღბვა, ტოკენიზაციის ფორმატები, სპეციალური შენახვის რეჟიმები/TTL.
აუდიტის პოლიტიკოსები: სავალდებულო ატრიბუტები ('actor', 'subject', 'action', 'occurred _ at', 'trace _ id').
ლიმიტები: rate limit headers, კვოტები, შეტყობინებების ზომა, ვადა.

ხელშეკრულების დაკვირვება

Correlation/Request-ID: აუცილებელია სპეციფიკაცია.
Error Catalog: ფიქსირებული კოდების სია და SLA აღმოფხვრის მიზნით.
SLI/SLO: p50/p95 ლატენცია, წარმატებული პასუხების წილი, თავსებადი მოვლენების წილი, იდემპოტენტური გამეორების პროპორცია.

ტესტირება და ხარისხი

Contract tests (მიმწოდებელი - მომხმარებელი), schema diff in CI, mock სერვერების წარმოება.
Golden samples: მოთხოვნის/პასუხების საცნობარო მაგალითები, ფიქსაცია e2e- სთვის.
Chaos/latence injection: Taimauts/retray- ის შემოწმება, გაფართოების დეგრადაცია MGC- ის შენარჩუნებისას.

სავარაუდო დომენის შაბლონები

გადახდა (REST + მოვლენები)

'POST/payments' (idempotent გასაღები) - '201 Created' s 'payment _ id', 'status = authorized'.
ღონისძიება authorized. v1` (ядро): `{ payment_id, amount, currency, method, occurred_at }`.
გაფართოება enriched. v1 ': რისკი, გეო, მოწყობილობა-fingerprint.
შეცდომები: '422' (შესაბამისობა), '402', '409'.
SLA: საავტორო უფლებები 800ms p95; ბირთვის მოვლენა 2c lag p95.

KYC (GRPC + რიგები)

RPC `StartVerification(user_id)` → `operation_id`.
პროგრესის მოვლენები ტოპიკაში 'kyc. status. v1` (`PENDING` → `APPROVED/REJECTED`).
კონტრაქტი ითვალისწინებს PII ველს, შენახვის ვადას, შენიღბვას, უარის თქმის მიზეზებს.

Audit (Event-only)

`audit. recorded. v1` (ядро): `actor`, `subject`, `action`, `occurred_at`, `trace_id`.
გამდიდრება: IP, მოწყობილობა, geo - ცალკეული მოვლენა/ნაკადი, არ ბლოკავს ბირთვს.

ინსტრუმენტები და ავტომატიზაცია (სავარაუდო დასტის)

Спеки: OpenAPI/AsyncAPI/Protobuf/Avro/GraphQL SDL.
Линтеры: Spectral, OpenAPI Diff, Buf (protobuf), Confluent SR compatibility checks.
Генерация: OpenAPI Generator, Buf/Protoc, GraphQL Codegen, AsyncAPI Generator.
გეითვეი: Kong/Apigee/Azure/GCP GW, Envoy.
Тесты: Pact/CDC, Dredd, Schemathesis, Hoverfly, MockServer.
რეესტრი: სქემების Git კატალოგი + Schema Registry/Artifact Registry.
დოკუმენტაცია: Redocly/Stoplight/Swagger-UI/GraphiQL/Explorer.

ანტი შაბლონები

Code-first backident: „პირველი MVP კონტროლერებზე“, პოსტ-ფაქტორის დაზუსტება, დოკუმენტაციისა და ქცევის შეუსაბამობა.
Swagger-wash: ოფიციალური OpenAPI რეალური წესების გარეშე (შეცდომები, ლიმიტები, SLA, ვერსიები).
თავსებადობა: წაშალა ველი/შეიცვალა ტიპი მაიორი ვერსიის გარეშე; Protobuf ჭდეების გადამუშავება.
„სქელი“ პასუხი პაგინაციის/ფილტრების გარეშე; იდემპოტენტურობის არარსებობა.
Security ხელშეკრულების გარეთ: auth/Scopes აღწერილია ვიკში, მაგრამ არა სპეციფიკაციაში.

ურთიერთობა პროცესის ორგანიზებასთან

API Guild: სტანდარტების რწმუნებულები, ცვლილებების შურისძიება, ტრენინგი.
Design Docs: თითოეული API - PRD, ADR (გადაწყვეტილებები), SLA, რისკის მატრიცა.
Change Management: RFC პროცესი, release notes, მიგრაციის haids, deprecation timline.
Paved Road & Templates: სპეციფიკაციის სერვისის ჩარჩოების გენერატორები (ჰენდლერის ჩონჩხი, შესაბამისობა, ლოჯისტიკა).

ჩეკის ფურცლები

დაწყებამდე

• არსებობს PRD და დომენის ტერმინალები.
• შეირჩა სტილი (REST/gRPC/Event/GraphQL) და სქემების ფორმატი.
• განსაზღვრულია MGC, შეცდომები, SLA/SLO, იდემპოტენტურობის წესები.

განვითარებაში

სპეციფიკაცია გადის ლინზებსა და მიმოხილვას.

• SDK/სტაბილური/ფიქსირებული ავტომატური წარმოება რეგულირდება.
• კონტრაქტის ტესტები (CDC) შედის CI- ში; schema-diff ბლოკავს შეუთავსებელ ცვლილებებს.

გამოსვლამდე

• დოკუმენტაცია ინტეგრატორებისთვის შეცდომების მაგალითებითა და კოდებით.
• ხელშეკრულების დაკვირვება: correlation-id, error catalog, SLI dashbords.

გამოცხადდა ვერსიისა და დეპრესიის პოლიტიკა.

FAQ

როგორ განსხვავდება Protocol-first API first- ისგან?
ხშირად ტერმინები გამოიყენება სინონიმებად. ამ სტატიაში, Protocol-first- ის ქვეშ, ჩვენ ხაზს ვუსვამთ ხელშეკრულების სიმკაცრეს და ყველა სტილის გაშუქებას (REST/RPC/Events/GraphQL), მათ შორის SLA, უსაფრთხოება და დაკვირვება.

შეანელებს ეს განვითარებას?
დაწყება შეიძლება ცოტა გრძელი იყოს, მაგრამ შემდეგ ჩვენ მოვიგებთ პარალელური განვითარების ინტეგრაციას, სტაბილურობას და სიჩქარეს (ავტომწარმოებელი, სტაბილური SDK).

რა უნდა გავაკეთოთ სწრაფი ექსპერიმენტებით?
გამოიყენეთ სქემების „უხეში“ ვერსიები (draft), feature flags და ქვიშის ყუთები, მაგრამ არ გამოტოვოთ ლინზები და თავსებადობის ძირითადი წესები.

შედეგი

Protocol-first დიზაინი კონტრაქტს ხდის არქიტექტურის ცენტრად: ჩვენ კოორდინაციას უწევს ქცევას, ვაწარმოებთ სქემებს, ავტომატიზაციას უწევს თაობას და ტესტებს, ევოლუციურად განვავითარებთ დანამატს. შედეგად, ჩვენ ვიღებთ პროგნოზირებულ ინტეგრაციას, განვითარების მაღალ სიჩქარეს და სისტემების გამძლეობას მასშტაბის და გუნდის ცვლილებებისადმი.