API տարբերակումը և պայմանագրային համատեղելիությունը

TL; DR

Համատեղելիությունը կարգապահությունն է, ոչ թե հաջողությունը։ Պահեք տարբերակների հստակ քաղաքականությունը (SemVer), փոփոխության մաթեմատիկան (որը «կոտրում է», որը ոչ), պայմանագրային թեստերը, սխեմաների գրանցումները և Sunset-ընթացակարգերը։ Փողի և կոմպլանսի համար խիստ REST/gRPC-ն vN-ի հետ, UI-ագրեգացիայի համար - էվոլյուցիոն GraphQL-ը '@ deprecated "։ Միշտ 'քարքարոտ խառնուրդ, հակադարձ համատեղելիություն, մեկ ստացիոնար ցիկլ, միգրացիոն կերամիկա, դաշտերի օգտագործման հեռաչափություն։

1) Հիմնական հասկացությունները և նպատակները

Backwards-compatible (BC). Նոր հաճախորդները հարմար են։

Forwards-compatible (FC): Հին հաճախորդները հարմար են (սահմանափակ)։

Wire-համատեղելիությունը '«մետաղալարի» ձևաչափը չի կոտրվում (հատկապես կարևոր է gRPC/Eurobuf) համար։

SemVer: `MAJOR. MINOR. PATCH '- կոտրում եք պայմանագիրը MAJOR-ի վրա։

Նպատակը 'նվազեցնել կոտրող փոփոխությունները և ապահովել կանխատեսելի պատուհանները։

2) Փոփոխության մատրիցա 'ինչ կարող եք, և ինչ հնարավոր չէ։

3) Քաղաքականություններ տարբեր API-ների համար

3. 1 REST

URI-ի տարբերակը («/v1/... ») կամ պրոֆիլում (« api-v1. »)։ Վերնագրի տարբերակը միայն ներքին դեպքերի համար է։

Ավելացրեք, մի հեռացրեք, նոր դաշտերը 'օք, հինը' տեղադրեք որպես «deprecated» սխեմայում և թողեք առնվազն մեկ ցիկլ։

Ստատուսներ/սխալներ 'մի փոխեք կոմպոզիցիան և կառուցվածքը' error։ code/error. message/error. details`.

Idempotenty-ը անփոփոխ է 'մի վերածեք ապահով «POST» -ի' Idempotency-Key-ի «վարքագծային այլ» մարտահրավեր։

3. 2 gRPC / Protobuf

Դաշտերի համարները սուրբ են, մի օգտագործեք հեռավոր համարները, տեղադրեք որպես «reserved»։

Միայն նոր optional/repite դաշտերի ավելացումը։ «Կոշտ պարտադիր» 'վալիդացիայի միջոցով, ոչ թե «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 (reason)' պատուհանի հայտարարությամբ։

Persisted 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 "," type "," ts ', "")։

Ստորագրություններ/NMAS պահեք անփոփոխ։ նոր ալգորիթմները նման են դրոշին։

Ընդարձակումը միայն նոր դաշտերի միջոցով է։ "և" headers "'առանց հին։

4) API Gateway-ը և տարբերակների երթուղայնացումը

Rules-based routing: նախածանցով '/v1 "," X-Appi-Version "վերնագրով, մոդուլով։

Shadow/Canary: Արտացոլեք վաճառական-2019 մասը «ստվերի» նոր տարբերակի վրա, համեմատեք պատասխանները։

Rate/Distas per-version-ը պաշտպանում է հին հաճախորդները մրցույթի ընթացքում։

Sunset headers REST-ի համար

"Sunset: - տարբերակի անջատման ամսաթիվը

«Deprecation: 07» - տարբերակը հնացած է

`Link: ; rel = «deprecation» - changelog/www.d-ում։

Օրինակ (Nginx-style, պարզեցված)

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 nook» PR-ում։

Consumer-Driven Corracom (CDC) 'սպառողների թեստեր (Pact/անալոգը) - պաշտպանություն աննկատ կոտրվածքներից։

Changelog: machine-readable (օրինակ ՝ «CHANGELOG»)։ md '+ ռելիզային նոտաները 1942-ին)։

6) Դաշտերի էվոլյուցիան 'գործնական կանոններ

ID/բանալին 'մի փոխեք ձևաչափը (UUID entint) առանց նոր դաշտի' _ v2 "և սկզբնական ժամանակահատվածի։

Ժամանակը/արժույթը 'պահեք UTC-8601/epoch և amount _ minor + currency; մի փոխեք մասշտաբը (կոպեկ/ցենտ)։

Enum 'ավելացրեք արժեքները' ok; մի փոխեք հին իմաստը։ REST-ի համար տվեք string-արժեքներ, ոչ թե ints։

Պագինացիա 'cursor-based ավելի կայուն; մի փոխեք կուրսորի իմաստը։

7) Deprikation և Sunset-ը։

1. Annnes (T-90/60): changelog, www.ru, «Deprecation/Sunset» վերնագրերը։

2. Կրկնվող ժամանակահատվածը 'V1 և V2 աշխատում են զուգահեռ; V1-ը նախազգուշացումներ է տալիս պատասխաններում/լոգարաններում։

3. Օգտագործման հեռուստաչափություն 'ո՞ վ է կոչում V1։ կետային շփումներ։

4. Սառեցում V1: Միայն ուղֆիքսներ/առանց ֆիչի։

5. Անջատումը (Sunset) ՝ 410 Gone կամ բլոկային էջ, որոնք ունեն կոդավորման հրահանգներ։

8) Սալվադորները առանց ցավի 'ռազմավարություններ

Blue/Green կամ Weighted routing: 1-5-25-50-100 տոկոսը։

Compatibility inum: առնվազն 1-2 մինորատիվ օրինակներ, ավելի հաճախ 6-12 ամիս արտաքին API-ի համար։

Feature Flags: նոր դաշտեր/տրամաբանության ճյուղեր միացնելու համար առանց տարբերակի փոփոխության։

Read/Write-բաժանումը, նախ ավելացրեք նոր դաշտի կարդալու աջակցությունը, ապա սկսեք գրել այն։

9) Պրոցեսորի փորձարկումը (պրակտիկայի փաթեթ)

Գոլդեն թեստերը հին տարբերակների պատասխանների վրա։

Diff-թեստերը 'breaking արգելքը CI-ում։

Replay-ը staging-ի վրա V2-ի համար (shadow)։

Back/Forward սցենարները 'նոր հաճախորդը հին սերվերի վրա և հակառակը (որտեղ FC-ն թույլ է տալիս)։

Ուեբհուկի պայմանագրային թեստերը 'ստորագրության, ձևաչափի, ժամանակի ստուգում։

10) Մետրիկի և SLO տարբերակման գործընթացը

հաճախորդների տոկոսը վերջին MINOR-ում (նպատակը 80 տոկոսն էր Sunset-ից)։

Ձախողումները (նպատակը 0)։

Հնացած տարբերակի զանգերի մասը (սպանում է Sunset)։

Հաճախորդի գնման ժամանակը (մեդիա/p95)։

Latency/regression corta տարբերակների միջև (ոչ ավելի վատ)։

11) Արտեֆակտների օրինակներ

OpenAPI (հատված, դաշտի ապակայունացում)

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 }

Eurobuf (reserved և v2 փաթեթ)

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

GraphQL (deprication)

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

12) Այլընտրանքային ալիքների տարբերակումը

SDK/CLI: SemVer + կախվածությունը API տարբերակից, համատեղելիությունը տեղադրված է READPS-ում։

Իրադարձությունները/սթրիմները (WS/Kafka) '«envelope» տարբերակը։ version`; նոր ատրիբուտները oporations են։ dedup-ը և ամփոփումը նույն կերպ են աշխատում տարբերակների միջև։

Հաշվետվություններ/CSV 'ֆայլի/գլխարկի անվանման տարբերակը։ ավելացրեք սյունները աջ կողմում. մի փոխեք կարգը/տեսակները։

13) Governational և դերերը

Պայմանագրի սեփականատերը (domain owner), API Steward (կանոններ և ոսպնյակներ), Releant Express (Sunset/հաղորդակցություն)։

RSA գործընթացը breaking-ի համար 'բիզնես հիմնավորում, ինտեգրման պլան, արտեֆակտներ, ամսաթվերը։

API-ի միասնական կատալոգը 'որտեղ տեսանելի են սխեմաները, տարբերակները, Sunset-օրացույցը, կապը։

14) Anti-patterna

«Հանգիստ» կոտրվածք 'փոխում ենք կարգավիճակը/սխալը/դաշտի տեսակը առանց տարբերակի։

Winobuf թվերի վերօգտագործումը ոչնչացնում է ռեփլեյը և հին հաճախորդները։

GraphQL-ը առանց դաշտերի օգտագործման հեռուստաչափության '«զգույշ» հեռացումը։

Համաշխարհային v2-ը ընդհանուր առմամբ մեգամիգացիա է 'կետային էվոլյուցիայի փոխարեն։

Հանրային API-ի համար query-Records տարբերակը աննկատ և խոցելի սխեմա է։

Ոչ մի միգրացիոն օրինակներ և օրինակներ չկան, գործընկերները փակում են, ժամկետները փչանում են։

15) Nokk-list-liste-ը նոր տարբերակով

• Նորարարված սխեման (OpenAPI/Drobuf/CPL), և breaking-winks։
• Ավելացված ինտեգրացիոն և պայմանագրային թեստերը (CDC)։
• Պատրաստ են SDK/օրինակ կոդի/միգրացիոն ֆոսֆիդ և Changelog։
• Ներառված է «Deprecation/Sunset» (հին տարբերակի համար) + «How to migrate» էջը։
• Canary/Shadow պլանը, alerts և dashbords համեմատության մետրը։
• Հակադարձ համատեղելիությունը պահպանված է համաձայնեցված ժամանակահատվածի համար։
• Արձագանքման պլանը (rollback) և ռիսկերի մատրիցը համաձայնեցված են։

Ռեզյումե

Կայուն API-ը գործընթաց է, ոչ թե «մեկ և ընդմիշտ»։ Ապրեք կանոններով 'SemVer + add-only էվոլյուցիա + սխեմաների գրանցում + պայմանագրային թեստեր + Sunset-ընթացակարգեր։ Բաժանեք ոճերը (REST/gRPC/GraphQL) և նրանց քաղաքական գործիչները, ուղարկեք տարբերակները API Gateway-ում, նետեք կանարեները, չափեք էֆեկտը։ Այսպիսով, դուք կհամարեք «կոտրող անակնկալներ», արագացրեք ռուսական գործընկերները և պահպանեք կանխատեսելիությունը դրամական և քննադատական օրինագծերի համար։