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

რატომ გვჭირდება ხელშეკრულების თავსებადობა

ხელშეკრულების თავსებადობა არის API- ს განვითარების უნარი არსებული ინტეგრაციების დაშლის გარეშე. მზარდ სისტემებში, API უფრო ხშირად იცვლება, ვიდრე მომხმარებელთა კოდი; თავსებადობა საშუალებას გაძლევთ წარმოადგინოთ ფიჩები განმეორებით, „დიდი გადასასვლელების“ კმაყოფილების გარეშე.

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

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

კონტრაქტი არის ინტერფეისის ოფიციალური სპეციფიკაცია: რესურსები/მეთოდები/მოვლენები, მონაცემთა სქემები, შეცდომების კოდები, ლიმიტები, SLA, უსაფრთხოების მოთხოვნები.
მიმწოდებელი (provider) - API- ს მფლობელი. მომხმარებელი (მომხმარებელი) - კლიენტი/ინტეგრაცია.

• Backward: ახალი მიმწოდებელი მუშაობს ძველ მომხმარებლებთან.
• ფორვარდი: ძველი მიმწოდებელი მუშაობს ახალ მომხმარებლებთან (ჩვეულებრივ მიიღწევა „ტოლერანტული მკითხველი“).
• Full: დაცულია როგორც backward, ასევე forward (ყველაზე ძლიერი ვარიანტი).
• დანამატი - არჩევითი ელემენტების დამატება არსებული დარღვევის გარეშე.

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

• MAJOR არის დარღვევის ცვლილებები (მხოლოდ ახალი API ხაზის გამოშვებისას): '/v2 ',' სერვისი. v2`).
• MINOR - დანამატის ცვლილებები (ახალი არჩევითი ველები/მეთოდები).
• PATCH - კორექტირება ხელშეკრულების შეცვლის გარეშე.
• დეპრესიის პოლიტიკა: მოძველებული ელემენტების გამოცხადება, მხარდაჭერის ფანჯარა, სათაურების/მეტამონაცემების გაფრთხილებები, მოხსნის გეგმა.

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

უსაფრთხო (ჩვეულებრივ, ზურგჩანთა კომპოზიცია)

არჩევითი ველის დამატება JSON/Protobuf/Avro- ში.
ახალი ენდოინტის/მეთოდის/ღონისძიების დამატება.
Enum- ის გაფართოება ახალი მნიშვნელობებით, თუ მომხმარებლები ტოლერანტულები არიან უცნობი მნიშვნელობებისთვის.
ლიმიტების ზრდა (მაგალითად, 'maxItems') მინიმალური გამკაცრების გარეშე.
არასრული დამატება სწორი ნაგულისხმევებით.
აღწერილობის/მაგალითების ტექსტის შეცვლა.

საშიში (არღვევს თავსებადობას)

ველების შეცვლა/მოცილება, მათი ტიპის ან სავალდებულო ცვლილება.
სტატუს კოდების/შეცდომების სემანტიკის შეცვლა (მაგალითად, იყო '200', გახდა '204' ან '404').
იდენტიფიკატორის ფორმატის შეცვლა (UUID-int).
ვალიდაციის გამკაცრება (უფრო მკაცრი მინიმალური/ნიმუშები) ვერსიის გარეშე.
წესრიგისა და სტრუქტურის ცვლილება gRPC ნაკადებში/მოვლენებში.
ჭდეების ნომრების გადატანა Protobuf- ში ახალი მინდვრებისთვის.

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

REST/HTTP + JSON Schema

დანამატი: ჩვენ აღვნიშნავთ ახალ ველებს, როგორც 'optional '/' nullable'.
Tolerant Reader კლიენტში: უცნობი ველების უგულებელყოფა; ნუ დაეყრდნობით წესრიგს.
ვერსია: მაიორი - გზაზე ('/v2 ') ან მედია (' აპლიკაცია/vnd. example. v2+json`).
ETag/If-Match: უსაფრთხო რბოლებისთვის.
შეცდომები: ერთი ფორმატი ('ტიპი', 'code', 'title', 'detail', 'trace _ id'), არ შეცვალოთ 'კოდის "მნიშვნელობები მაჟორის გარეშე.
პაგინაცია: კურსორები სასურველია offset; დაამატეთ ველები 'შემდეგი _ cursor', არ შეცვალოთ არსებული მნიშვნელობა.

gRPC / Protobuf

ჭდეების ნუმერაცია უცვლელია. დისტანციური ჭდეების გამოყენება შეუძლებელია.
ახალი ველები - 'optional '/' repeated', გონივრული ნაგულისხმევი სერვერზე.
ნუ შეცვლით შეტყობინებების წესსა და სავალდებულო წესს Streaming-RPC- ში.
შეცდომების სტატუსი - სტაბილური ('INVALID _ ARGUMENT', 'FAILED _ PRECONDITION' და ა.შ.); ახალი სემანტიკა - მეთოდის/მომსახურების ახალი ვერსია.

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

მოვლენების სახელწოდება: 'domain. action. v{major}`.
ახალი ველები არჩევითია; განასხვავეთ ბირთვი და გამდიდრება ('.enriched').
სქემების რეგისტრატორები: თავსებადობის წესები (BACKWARD/FORWARD/FULL) თემაზე/ღონისძიებაზე.
enum- ის გაფართოება დასაშვებია მომხმარებელთა მხარეს tolerant reader- ით.
კონფიგურაციის/შეკვეთის გასაღების შეცვლა = დამანგრეველი ცვლილებები.

GraphQL

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

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

Additive-first: გაფართოება დაშლის გარეშე.
კაპიტალი: მომხმარებლები აცხადებენ, რომ ისინი მხარს უჭერენ (სათაურები/პარამეტრები/შეთანხმებები), სერვერი ადაპტირდება.
ხელშეკრულების საზღვრები: ჩაწერეთ MGC (მინიმალური საგარანტიო ხელშეკრულება) და გამოყავით გაფართოებები (უკანა პირამიდის მოდელი).
Tolerance by default: მომხმარებლები უგულებელყოფენ ზედმეტი და სწორად ამუშავებენ უცნობი მნიშვნელობებს.
Dual-write/Dual-emit: ძირითადი ცვლილებებით, ერთდროულად გამოუშვეთ 'v1' და 'v2'.
Sunset headers/Events: წინასწარ აცნობეთ ვერსიის მოხსნის შესახებ.

მთავრობა და ავტომატიზაცია

• OpenAPI/Spectral: სახელები, პაგინაცია, შეცდომის კოდი, ველების ფორმატები.
• Buf/Protobuf: ჭდეების ხელახალი გამოყენების აკრძალვა, პაკეტების ნოტაცია.
• AsyncAPI/Schema Registry: სქემების თავსებადობა CI დონეზე.
• კონტრაქტების კატალოგი (SSOT): სქემების/ვერსიების ცენტრალიზებული რეესტრი დიფების ისტორიასთან.
• API Guild: გილდია/კომიტეტი, რომელიც იღებს წესებს, შაბლონებს და ცვლილებებს.
• Change Management: RFC/ADR, release notes, მიგრაციის ჰაიდები.

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

CI Schema-diff: ჩვენ ბლოკავს სპეკის დარღვევის ცვლილებებს (OpenAPI-diff, Buf breaking, SR კომპოზიცია).
Consumer-Driven Contracts (CDC): Pact/მსგავსი არის მიმწოდებლის შემოწმება კონკრეტული მომხმარებლების კონტრაქტების წინააღმდეგ.
Golden samples: საცნობარო მოთხოვნები/პასუხები და რეგრესიის მოვლენები.
E2E Canary: ტრაფიკის განლაგება/ცალკეული საკონსულტაციო ჯგუფები.
Chaos/latence: Timauts/retray- ის შემოწმება - latency-SLO- ს ცვლილება ითვლება ხელშეკრულების ცვლილებად.

მიგრაცია და დეპრესია

1. გამოაცხადეთ დეპრესია: გაითვალისწინეთ ელემენტი, მიუთითეთ sunset ვადა და ალტერნატივა.
2. შეინარჩუნეთ თავსებადობის პერიოდი: ორმაგი თავისუფალი/ორმაგი ემიტი, ხიდები, გადამყვანები.
3. შეაგროვეთ ტელემეტრია: ვინ იყენებს ძველს?
4. კომუნიკაცია: ბიულეტენები, გამოშვება, სატესტო სტენდები.
5. ამოღება: ფანჯრის შემდეგ - მოცილება ფიქსირებული გამოშვებით.

ცვლილებების მაგალითები

REST

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

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

კლიენტები, რომლებიც უგულებელყოფენ უცნობ მინდვრებს, არ იშლება.

Protobuf

proto message Payment {
string id = 1;
string status = 2; // don't change tag numbers optional double risk_score = 3; // additive
}

Event

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

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

Swagger-wash: ოფიციალურად არის დაზუსტება, მაგრამ მომსახურების ქცევა განსხვავდება მისგან.
Breaking by stealth: შეიცვალა ტიპი/სტატუსი/ფორმატი ახალი ვერსიისა და მიგრაციის ფანჯრების გარეშე.
ნედლეული CDC მოვლენები, როგორც საჯარო კონტრაქტი: BD სქემების გაჟონვა, ევოლუციის შეუძლებლობა.
მკაცრი კლიენტი: ეცემა უცნობი მინდვრებით/მნიშვნელობებით; tolerant reader- ის არარსებობა.
Protobuf ტეგების ხელახალი გამოყენება: მონაცემების მშვიდი კორუფცია.
ლატენტობა, როგორც „არაკონტრაქტული“: მათ მოულოდნელად გაუგრძელეს p95 - მომხმარებლები იშლება ტაიმაუტებში.

თავსებადობის სია (მერჯამდე)

• დანამატის ცვლილებები (ან ძირითადი ვერსია მომზადებულია).
• ლინტერები/ჩეკები დასრულებულია, თავსებადობის წესები მწვანეა.
• შეცდომები/კოდები/სტატუსები არ შეცვლილა სემანტიკა.
• Enum გაფართოვდა ძველი მნიშვნელობების აკრძალვის გარეშე; მომხმარებლები - ტოლერანტი.

MGC საზღვრები უცვლელია.

• განახლდა მაგალითები/დოკუმენტაცია/SDK.
• მაჟორისთვის - გეგმა ორმაგი-write/dul-emit, sunset თარიღი, კომა გეგმა.
• ტესტები CDC/Golden/E2E დასრულებულია.

FAQ

როგორ განსხვავდება backward forward თავსებადობისგან?
Backward - ახალი სერვერები არ არღვევენ ძველ მომხმარებლებს. Forward - ახალი მომხმარებლები არ იშლება ძველ სერვერებზე (tolerant reader- ის და სისუფთავე ნაგულისხმევის საშუალებით).

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

შესაძლებელია თუ არა Schema Registry/linters- ის გარეშე ცხოვრება?
თეორიულად - დიახ, პრაქტიკულად - ეს არის ხშირი რეგრესები და „ფარული“ ხარვეზები. ავტომატიზაცია იხდის.

შეგიძლიათ გაფართოვდეთ Enum?
დიახ, თუ მომხმარებლები სწორად ამუშავებენ უცნობ მნიშვნელობებს (fallback/ignore). წინააღმდეგ შემთხვევაში - მაიორი.

შედეგი

კონტრაქტის თავსებადობა არის + დისციპლინის + ავტომატიზაციის წესები. დაპროექტეთ დანამატი, შეცვალეთ დარღვევის ცვლილებები, გამოიყენეთ tolerant reader, შეამოწმეთ დიფები და CDC ავტომატურად, დაგეგმეთ დეპრესია. ასე რომ, API შეძლებს სწრაფად განვითარდეს და ინტეგრაცია დარჩეს სტაბილური.