საპირისპირო თავსებადობა

რა არის საპირისპირო თავსებადობა

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

გასაღები: არ დაარღვიოთ შეთანხმებები. ნებისმიერი ევოლუცია - დამატების გზით, და არა უკვე გამოშვებული ცვლილების გზით.

ძირითადი პრინციპები

1. Additive-first

ახალი ველები/მეთოდები/მოვლენები სურვილისამებრ ემატება. არაფერი არსებულია და არ ცვლის მნიშვნელობას.

2. მინიმალური საგარანტიო ხელშეკრულება (MGC)

განსაზღვრეთ ბირთვი - ველების/ოპერაციების ერთობლიობა, რომლის გარეშეც სცენარი კარგავს მნიშვნელობას. ბირთვი სტაბილურია. ყველაფერი დანარჩენი გაფართოებაა.

3. Tolerant reader

მომხმარებლები უგულებელყოფენ უცნობ ველებს და სწორად ამუშავებენ ახალ მნიშვნელობებს enum (fallback).

4. ვერსიის პოლიტიკა

დარღვევის ცვლილებები - მხოლოდ მაიორი ხაზის მეშვეობით ('/v2 ',' payments. v2`, `event. v2`). უმცირესობები - დანამატები.

5. დაკვირვება - ხელშეკრულების ნაწილი

კლიენტის ვერსია, ფორმატი, კაპიტალური დროშები ჩანს ლოგებში/ტრასებსა და მეტრიკებში. ეს საშუალებას გაძლევთ მართოთ მიგრაცია.

უსაფრთხო საშიში ცვლილებები

ჩვეულებრივ უსაფრთხოა (BC-OK)

არჩევითი ველების დამატება (JSON/Avro/Protobuf 'optional '/' nullable').
ახალი endpoints/მეთოდების/მოვლენების დამატება.
enum- ის გაფართოება დამატებითი მნიშვნელობებით (ტოლერანტული მიმოხილვით).
ვალიდაციის შესუსტება (მაქსიმუმის ზრდა, ალტერნატიული ფორმატების დამატება).
სათაურების/მეტამონაცემების დამატება, რომლებიც გავლენას არ ახდენს მნიშვნელობაზე.

საშიში

ველების მოცილება/შეცვლა, არსებული ველების ტიპის ან სავალდებულო შეცვლა.
სტატუსის/შეცდომის კოდების სემანტიკის შეცვლა.
Protobuf ჭდეების ხელახალი გამოყენება სხვა ველებისთვის.
ღონისძიების კონვერტაციის გასაღების შეცვლა (არღვევს დანაყოფის წესრიგს).
SLA/Timauts- ის გამკაცრება, რის გამოც ძველი მომხმარებლები იწყებენ დაცემას.

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

REST/HTTP + JSON

დანამატი: ახალი ველები - 'optional', სერვერი არ მოითხოვს მათ ძველი მომხმარებლებისგან.
ვერსიები: მაიორი - გზაზე ('/v2 ') ან მედია; minor - გაფართოების გზით და '? include = '/'? fields ='.
შეცდომები: ერთი ფორმატი; არ შეცვალოთ კოდი/სემანტიკა მაიორი.
ETag/If-Match: უსაფრთხო რბოლებისთვის.
IDempotence: 'Idempotency-Key' POST- ისთვის - ძველი მომხმარებლები არ „აორმაგებენ“ ეფექტს თხრილების დროს.

gRPC / Protobuf

ჭდეები უცვლელია. დისტანციური ჭდეების გამოყენება შეუძლებელია.
ახალი ველები - 'optional '/' repeated'; ნაგულისხმევი მნიშვნელობები სწორად დამუშავებულია ძველი კოდით.
ნაკადი: არ შეცვალოთ შეტყობინებების შეკვეთა/სავალდებულო მინორი.
შეცდომები - სტატუსის სტაბილური ნაკრები; ახალი სემანტიკა - ახალი მეთოდი/მომსახურება ('.v2').

Event-driven (Kafka/NATS/Pulsar) + Avro/JSON/Proto

სახელწოდება: 'domain. action. v{major}`.
Core vs Enriched: ბირთვი სტაბილურია; გამდიდრება - ინდივიდუალური ტიპები/თემები ('.enriched').
სქემების თავსებადობის რეჟიმი: უფრო ხშირად BACKWARD; CI ბლოკავს შეუთავსებელ ცვლილებებს.
განაწილება: გასაღები (მაგალითად, 'payment _ id') - ხელშეკრულების ნაწილი; მისი შეცვლა არის breaking.

GraphQL

ველების/ტიპების დამატება - OK; წაშლა/სახელის შეცვლა - '@ deprecated' და მიგრაციის ფანჯარა.
ნუ გაზრდით „უნებართვო - არა-უნებლიე“ მაიორის გარეშე.
აკონტროლეთ complexity/depth - ლიმიტების შეცვლა = ხელშეკრულების ცვლილება.

პატერნები BC- ს შენარჩუნებაში

საპირისპირო პირამიდის მოდელი: ბირთვის სტაბილიზაცია, სურვილისამებრ გაფართოება.
კაპიტალური ნეგოტია: კლიენტი აცნობებს მხარდაჭერილ შესაძლებლობებს ('X-Capabilities '/handshake), სერვერი ადაპტირებულია.
ორმაგი რუნი/ორმაგი ემიტი: მიგრაციის დროს ერთდროულად შეინარჩუნეთ 'v1' და 'v2'.
გადამყვანები: მარიონეტული/გეითვეი თარგმნის მოთხოვნებს 'v1-v2 "" მძიმე "მომხმარებლებისთვის.
გამოცდა და კონტრაქტი (BD- სთვის): ჯერ დაამატეთ ახალი, დაიწყეთ წერა/კითხვა, მხოლოდ ამის შემდეგ ამოიღეთ ძველი.

მთავრობის და პროცესი

1. კონტრაქტების კატალოგი (სქემების რეესტრი): ჭეშმარიტების ერთი წყარო თავსებადობის პოლიტიკოსებთან.
2. ლინტერები და ჩეკები CI/CD- ში: OpenAPI-diff, Buf-breaking, Avro/JSON Schema თავსებადობის შემოწმება.
3. CDC/Consumer-Driven Contracts: პროვაიდერი შემოწმებულია მომხმარებელთა რეალური კონტრაქტებისთვის.
4. Golden samples: საცნობარო მოთხოვნები/პასუხები/მოვლენები რეგრესისთვის.
5. Change მენეჯმენტი: RFC/ADR breaking, sunset გეგმები, კომუნიკაცია.

დეპრესია და ძველი ვერსიების ამოღება

გაითვალისწინეთ მოძველებული ('@ deprecated', აღწერილობები, სათაურები 'Deprecation', 'Sunset').
მიგრაციის ფანჯარა: წინასწარ გამოცხადებული თარიღი, ტესტის სტენდი, კოდის მაგალითები.
გამოყენების ტელემეტრია: ვინ არის კიდევ 'v1'? სეგმენტი მეტრიკა/ლოგები ვერსიის მიხედვით.
ორმაგი რუნი ნულამდე ტრაფიკამდე, შემდეგ - მოცილება.

დაკვირვება და ოპერაციული მეტრიკა

მოთხოვნის/შეტყობინებების პროცენტი ვერსიით.
შეცდომების/ტაიმაუტების წილი ძველ კლიენტებში გამოშვების შემდეგ.
შეუთავსებელი payload- ის წილი (სქემის შესაბამისობა კარიბჭეზე/ნაკადის ფილტრებში).
მომხმარებელთა მიგრაციის ლაგი (რამდენს უსმენს 'v1').

საპირისპირო თავსებადობის ტესტირება

Schema-diff: fail при remove/rename/type-change.
კონტრაქტის ტესტები: ძველი SDK/მომხმარებლები ახალი განხორციელების წინააღმდეგ მიდიან.
E2E canarey: ძველი ტრაფიკის ნაწილი ახალ ვერსიაზე, შედარება p95/p99, კოდები, retray.
მოვლენების რეპლიკები: პროგნოზები იკრიბება ძველი ლოგიკის ახალი ლოგიკით, შეუსაბამობის გარეშე.
Fault-injection: შეფერხებები/ნაწილობრივი პასუხები - ძველი მომხმარებლები არ ეცემა.

მაგალითები

REST (დანამატი)

json
{ "id": "p1", "status": "authorized" }

json
{ "id": "p1", "status": "authorized", "risk_score": 0. 12 }

ძველი მომხმარებლები, „risk _ score“ უგულებელყოფენ, აგრძელებენ მუშაობას.

Protobuf (ჭდეები)

proto message Payment {
string id = 1;
string status = 2;
optional double risk_score = 3 ;//new field, safe
}
//Tags 1 and 2 cannot be changed/deleted without v2

მოვლენები (ბირთვი + გამდიდრება)

`payment. authorized. v1 '- ბირთვი (მინიმალური ფაქტები).
`payment. enriched. v1 '- დეტალები; ბირთვის მომხმარებლები არ არიან დამოკიდებული გამდიდრებაზე.

ანტიპატერები

Swagger-wash: მათ განაახლეს სქემა, მაგრამ მომსახურება ძველებურად იქცევა (ან პირიქით).
ფარული დარღვევები: შეცვალეს ველის/სტატუსის მნიშვნელობა ვერსიის გარეშე.
Protobuf ტეგების ხელახალი გამოყენება: მონაცემთა „მშვიდი“ კორუფცია.
მკაცრი მომხმარებლები: დაეცემა უცნობ მინდვრებში/enum; არ არის tolerant reader.
მეგა-endpoint: ერთი და იგივე - ნებისმიერი ცვლილება ხდება პოტენციური დარღვევა.

ჩეკის სია გამოქვეყნებამდე

• ცვლილებები დანამატია; ბირთვი (MGC) არ შეეხო.
• Linters/checks გაიარა; არ არსებობს საბურღი დროშები.
• კლიენტის SDK განახლებულია (ან არ არის საჭირო დანამატის გაფართოებისთვის).
• tolerant reader შედის კლიენტებში; შემოწმებულია enum-fallback.
• მეტრიკა/ლოგები შეიცავს ვერსიას და კაპიტალურ დროშებს.
• პოტენციური დარღვევისთვის არის '/v2 ', ორმაგი რუნი და sunset გეგმა.
• დოკუმენტაცია/მაგალითები განახლებულია, არის ოქროს ნაკრები.

FAQ

Backward vs forward - რა განსხვავებაა?
Backward - ახალი სერვერები მუშაობენ ძველ კლიენტებთან. Forward - ახალი მომხმარებლები სწორად მუშაობენ ძველ სერვერებთან (tolerant reader- ის და სისუფთავე ნაგულისხმევის გამო). სრული წრე არის სრული კომპოზიცია.

ყოველთვის გჭირდებათ '/v2 'გაკეთება დიდი ცვლილებებისთვის?
დიახ, თუ ინვარიანტები/ტიპები/გასაღებები/სემანტიკა იშლება. წინააღმდეგ შემთხვევაში, შეინარჩუნეთ ხაზი და განავითარეთ დანამატი.

როგორ მოვიქცეთ enum- ით?
დაამატეთ ახალი მნიშვნელობები ძველი მნიშვნელობის შეცვლის გარეშე. მომხმარებლებს უნდა ჰქონდეთ fallback უცნობი მნიშვნელობით.

რა უნდა გავაკეთოთ, თუ ისინი უკვე „გატეხილია“?
გამოტოვება, ცხელი-ფიქსი ადაპტერი, 'v2' -ის გამოცემა ორმაგი-რუნიდან, კომუნიკაცია და მიგრაციის ჰაიდი.

შედეგი

საპირისპირო თავსებადობა არის ევოლუციის დისციპლინა: სტაბილიზირება ბირთვი, გაფართოება დანამატის საშუალებით, შემოიღეთ tolerant reader, ავტომატიზირებული შემოწმება და ჩაატარეთ ცნობიერი დეპრესია. ასე რომ, თქვენ შეგიძლიათ სწრაფად შეიმუშაოთ პლატფორმა, მომხმარებლების დატოვების გარეშე „უხილავი“ ცვლილებების ნაგვის ქვეშ.