API ვერსიები და კონტრაქტის თავსებადობა

TL; DR

თავსებადობა არის დისციპლინა და არა იღბალი. შეინარჩუნეთ ვერსიების მკაფიო პოლიტიკა (SemVer), ცვლილებების მათემატიკა (რაც „არღვევს“, რა არა), ხელშეკრულების ტესტები, სქემების რეესტრები და Sunset პროცედურები. ფულისა და შესაბამისობისთვის - მკაცრი REST/gRPC vN- ით, UI- სთვის - ევოლუციური GraphQL '@ deprecated'. ყოველთვის: კანარის ტრაფიკი, საპირისპირო თავსებადობა - ერთი გამოშვებული ციკლი, მიგრაციის ჰაიდები, მინდვრების გამოყენების ტელემეტრია.

1) ძირითადი ცნებები და მიზნები

Backwards-compatible (BC): ძველი მომხმარებლები შესაფერისია ახალი სერვერისთვის.
Forwards-Compatible (FC): ახალი მომხმარებლები (შეზღუდულია) შესაფერისია ძველი სერვერისთვის.
Wire თავსებადობა: „მავთულზე“ ფორმატი არ იშლება (განსაკუთრებით მნიშვნელოვანია GRPC/Protobuf- ისთვის).
SemVer: `MAJOR. MINOR. PATCH '- დაარღვიეთ კონტრაქტი და გაზარდეთ MAJOR.

მიზანი: დამანგრეველი ცვლილებების შემცირება და პროგნოზირებადი მიგრაციის ფანჯრების უზრუნველყოფა.

2) ცვლილებების მატრიცა: რა არის შესაძლებელი და რა - არა

3) პოლიტიკოსები API- ს სხვადასხვა სტილით

3. 1 REST

ვერსია URI ('/v1/... ') ან დომენში (' api-v1. '). სათაურის ვერსია მხოლოდ შიდა შემთხვევებისთვის არის.
დაამატეთ, ნუ ამოიღებთ: ახალი ველები - დაახლ.
სტატუსები/შეცდომები: არ შეცვალოთ კოდი და სტრუქტურა 'error. code/error. message/error. details`.
Idempotention უცვლელია: ნუ გადააქცევთ უსაფრთხო 'POST' s 'Idempotency-Key "" ქცევითი განსხვავებული "გამოწვევა.

3. 2 gRPC / Protobuf

მინდვრის ნომრები წმინდაა: ნუ გამოიყენებთ დისტანციურ ნომრებს, განათავსეთ როგორც „გამოჯანმრთელება“.
მხოლოდ ახალი ოპტიმალური/გამაგრილებელი ველების დამატება; „მკაცრი სავალდებულო“ - ვალიდაციის გზით, არა 'required'.
ვერსიის პაკეტები: 'payments. v1`, `payments. v2`.
სერვისების თავსებადობა: ახალი RPC - ახალი მეთოდი; ჩვენ არ ვცვლით ძველთა ქცევას.

proto message Payout {
reserved 4 ;//field deleted, number reserved string id = 1;
string currency = 2;
int64 amount_minor = 3;
// v2: optional string comment = 5;
}

3. 3 GraphQL

ევოლუცია v2 გარეშე: დაამატეთ ველები/ტიპები; წაშლა - '@ deprecated' მეშვეობით ფანჯრის გამოცხადებით.
Persististed Queries: გამოიყენეთ მოთხოვნების თეთრი სია საჯარო მომხმარებლებისთვის - უფრო ადვილია აკონტროლოთ თავსებადობა.
Field-level authZ და ტელემეტრია: იცოდეთ რომელი ველები ნამდვილად გამოიყენება ამოღებამდე.

graphql type Payout {
id: ID!
amountMinor: Long!
currency: String!
comment: String @deprecated(reason: "Use note")
note: String
}

3. 4 ვებჰუკი

ბილიკის ვერსია ('/webhooks/v1/payments ') და ღონისძიების ფიქსირებული კონვერტი (' event _ id ',' ტიპი ',' ts ',' data ').
ხელმოწერები/NMAS შეინარჩუნეთ უცვლელი; ახალი ალგორითმები - როგორც დროშის ვარიანტი.
გაფართოებები - მხოლოდ ახალი ველების მეშვეობით 'data.' და 'headers' - ძველების მოხსნის გარეშე.

4) API Gateway და ვერსიების მარშრუტი

Rules-based routing: პრეფიქსი '/v1 ', სათაურით' X-Api-Version ", დომენის მიხედვით.
Shadow/Canary: ასახეთ წარმოების ტრაფიკის ნაწილი ახალ ვერსიაზე „ჩრდილში“, შეადარეთ პასუხები.
Rate/Qutas per-version: იცავს ძველ მომხმარებლებს მიგრაციის დროს.

• 'Sunset: ' - ვერსიის გამორთვის თარიღი
• 'დეპრესია: ნამდვილი' - ვერსია მოძველებულია
• `Link: ; rel = "deprecation" "- მიგრაციის changelog/hayd

nginx location ~ ^/v2/ {
proxy_pass http://api_v2;
}
location ~ ^/v1/ {
add_header Deprecation "true";
add_header Sunset "Thu, 01 May 2026 00:00:00 GMT";
proxy_pass http://api_v1;
}

5) სქემების და კონტრაქტების რეგისტრაცია

OpenAPI / JSON Schema для REST; Protobuf descriptors для gRPC; SDL registry для GraphQL.
CI შემოწმებები: linters + „breaking-changes შემოწმება“ PR- ზე.
Consumer-Driven Contracts (CDC): მომხმარებელთა ტესტები (Pact/ანალოგი) - დაცვა უხილავი დარღვევებისგან.
Changelog: მანქანა readable (მაგალითად, 'CHANGELOG. md '+ გამოცემა რეესტრში).

6) ველების ევოლუცია: პრაქტიკული წესები

ID/გასაღებები: არ შეცვალოთ ფორმატი (UUID-int) ახალი ველის '_ v2' და გარდამავალი პერიოდის გარეშე.
დრო/ვალუტა: გამართეთ UTC ISO-8601/epoch და amount _ minor + currency; ნუ შეცვლით მასშტაბს (პენი/ცენტი).
Enum: დაამატეთ მნიშვნელობები - დაახლოებით; არ შეცვალოთ ძველი მნიშვნელობა. REST- სთვის - მიეცით string მნიშვნელობები და არა ints.
Pagination: cursor-based უფრო სტაბილური; ნუ შეცვლით კურსორის სემანტიკას.

7) deprication და Sunset

1. განცხადება (T-90/60): changelog, პარტნიორების გაგზავნა, სათაურები „დეპრესია/Sunset“.
2. სარეზერვო პერიოდი: V1 და V2 პარალელურად მუშაობენ; V1 აღჭურვილია გაფრთხილებებით პასუხებში/ლოგოებში.
3. გამოყენების ტელემეტრია: კიდევ ვინ ეძახის V1? წერტილოვანი კონტაქტები.
4. ყინვაგამძლე V1: მხოლოდ ბარგები/ფიკების გარეშე.
5. გამორთვა (Sunset): 410 Gone ან ბლოკის გვერდი მიგრაციის ინსტრუქციით.

8) განთავისუფლება ტკივილის გარეშე: გაანგარიშების სტრატეგია

Blue/Green ან Weighted Routing: 1-5-25-50-100% ტრაფიკი.
Compatibility window: მინიმუმ 1-2 მცირე გამოშვება, უფრო ხშირად 6-12 თვე გარე API- სთვის.
Feature Flags: ახალი ველების/ლოგიკის ფილიალების ჩართვა ვერსიის შეცვლის გარეშე.
Read/Write გაყოფა: ჯერ დაამატეთ მხარდაჭერა ახალი ველის წაკითხვისთვის, შემდეგ დაიწყეთ მისი წერა.

9) თავსებადობის ტესტირება (პრაქტიკის პაკეტი)

ოქროს ტესტები ძველი ვერსიების პასუხებზე.
სქემების Diff ტესტები: აკრძალვა CI- ში.
Replay წარმოების მარშრუტი staging for V2 (shadow).
Back/Forward სცენარი: ახალი კლიენტი ძველ სერვერზე და პირიქით (სადაც FC დავუშვათ).
ვებჰუკის საკონტრაქტო ტესტები: ხელმოწერის შემოწმება, ფორმატის, დრო.

10) მეტრიკა და SLO ვერსირების პროცესი

მომხმარებელთა% ბოლო MINOR- ში (მიზანი Sunset- ზე 80% -ს შეადგენს).
თავსებადობის შეცდომები/გამოშვების მიუწვდომლობა (მიზანი - 0).
მოძველებული ვერსიის ზარების წილი (Sunset- ის შემცირება).
კლიენტის მიგრაციის დრო (საშუალო/p95).
Latency/regression delta ვერსიებს შორის (ბაზაზე უარესი არ არის).

11) არტეფაქტების მაგალითები

yaml components:
schemas:
Payout:
type: object properties:
id: { type: string, format: uuid }
amount_minor: { type: integer }
currency: { type: string }
comment:
type: string deprecated: true description: "Use note"
note: { type: string }

proto syntax = "proto3";
package payouts. v1;
message Payout { reserved 5; string id=1; int64 amount_minor=2; string currency=3; }

graphql type Query { payout(id: ID!): Payout }

12) მიმდებარე არხების ვერსია

SDK/CLI: SemVer + დამოკიდებულება API ვერსიაზე, თავსებადობა გათვალისწინებულია README- ში.
მოვლენები/ნაკადები (WS/Kafka): ვერსია 'envelope. version`; ახალი ატრიბუტები არჩევითია; დედაპი და შეაჯამა თანაბრად მუშაობენ ვერსიებს შორის.
ანგარიში/CSV: ვერსია ფაილის/ქუდის სახელით; დაამატეთ სვეტები მარჯვნივ; ნუ შეცვლით წესრიგს/ტიპებს.

13) მთავრობა და როლები

ხელშეკრულების მფლობელი, API Steward (წესები და ლინტერები), Release Manager (Sunset/კომუნიკაციები).
RFC პროცესი სარეკრეაციო ცვლილებებისთვის: ბიზნესის დასაბუთება, მიგრაციის გეგმა, არტეფაქტები, თარიღები.
API- ის ერთიანი კატალოგი: სადაც ჩანს სქემები, ვერსიები, Sunset კალენდარი, კონტაქტი.

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

„მშვიდი“ დარღვევები: ჩვენ ვცვლით სტატუსს/შეცდომას/ველის ტიპს ვერსიის გარეშე.
Protobuf ნომრების ხელახალი გამოყენება - ანადგურებს რეფლექსს და ძველ მომხმარებლებს.
GraphQL ველების გამოყენების ტელემეტრიის გარეშე არის „შეხების“ მოცილება.
ყველაზე გლობალური v2 არის მეგამიგრაცია წერტილოვანი ევოლუციის ნაცვლად.
საზოგადოებრივი API- ის query პარამეტრის ვერსია აშკარა და დაუცველი სქემაა.
არ არსებობს მიგრაციის ჰაიდები და მაგალითები - პარტნიორები ჩერდებიან, ვადები იშლება.

15) ახალი ვერსიის Check list

• განახლებულია სქემა (OpenAPI/Protobuf/SDL), გაიარა საბრძოლო მასალები და ყუთების შემოწმებები.
• დაემატა ინტეგრაციისა და ხელშეკრულების ტესტები (CDC).
• SDK მზად არის/კოდის მაგალითი/მიგრაციის ჰაიდი და Changelog.
• ჩართულია 'დეპრესია/Sunset' (ძველი ვერსიისთვის) + გვერდი „როგორ წავიდეთ“.
• Canary/Shadow გეგმა, ალერტა და დაშბორდები მეტრიკის შედარებისთვის.
• საპირისპირო თავსებადობა შენარჩუნებულია შეთანხმებული ვადით.
• დაბრუნების გეგმა (rollback) და რისკის მატრიცა შეთანხმებულია.

რეზიუმე

სტაბილური API არის პროცესი და არა „ერთხელ და სამუდამოდ“. იცხოვრე წესების შესაბამისად: SemVer + add-only ევოლუცია + სქემების რეესტრი + საკონტრაქტო ტესტები + Sunset პროცედურები. გაიზიარეთ სტილები (REST/gRPC/GraphQL) და მათი პოლიტიკოსები, დაუკავშირდით ვერსიებს API Gateway- ზე, გადაიტანეთ კანაფები, გაზომეთ ეფექტი. ასე რომ, თავიდან აიცილებთ „გატეხილ სიურპრიზებს“, დააჩქარებთ პარტნიორების ინტეგრაციას და შეინარჩუნებთ პროგნოზირებას ფულადი და შესაბამისობის კრიტიკულ დომენებზე.