A lecke végére meg tudod különböztetni a szerződés rétegeit, fel tudod ismerni a kompatibilis és a törő változtatást, és el tudod magyarázni az expand–migrate–contract módszert.
Miért kell?
A szolgáltatások akkor adhatók ki önállóan, ha a régi és az új változatok egy ideig együtt működnek. A szerződés ezért több a mezők listájánál: megadja a művelet jelentését, a bemenet korlátait, a kimenetet, a hibákat és a megengedett ismétlést.
A szerződés rétegei
Réteg
Mit ír le?
Példa
Szintaktikai
A formátumot: mezőtípusok, kötelező mezők, kódolás
A price szám
Szemantikai
Mit jelentenek az értékek
A price forintban, bruttóban értendő
Viselkedési
Az oldalsó hatásokat és a feltételeket
A reserve csak ellenőriz, vagy foglal is; meddig érvényes; mi történik ismétléskor
Működési
Időkeret, üzenetméret, terhelési korlát
Maximális kérésméret
A típusból nem következik az értelmezés: ugyanaz a szám jelenthet forintot, fillért vagy belső egységet.
Kompatibilis és törő változtatás
Egy új opcionális mező általában könnyebben bevezethető, mint egy régi kötelező átnevezése. A kompatibilitás azonban a fogyasztó viselkedésétől is függ: egy szigorú dekóder az ismeretlen mezőt is elutasíthatja, és egy új enumérték gondot okozhat, ha a kliens a lehetséges értékeket lezártnak tekinti. Fowler tolerant reader mintája szerint a fogyasztó csak azt olvassa, amire szüksége van, és a többit figyelmen kívül hagyja, így a szolgáltató kevesebb esetben törik meg a klienseket. A minta Postel törvényére épül: legyél konzervatív abban, amit küldesz, és liberális abban, amit elfogadsz.
A szemantikai változtatás a legveszélyesebb: ha az összeg korábban bruttót jelentett, később nettót, a séma változatlan maradhat, mégis törik az együttműködés. Ezért a szerződésellenőrzésnek a viselkedést is vizsgálnia kell.
Parallel change: expand, migrate, contract
Fowler leírása szerint a visszafelé nem kompatibilis változtatás biztonságosan három szakaszban végezhető:
Expand (bővítés): az új változat a régi mellé kerül; a meglévő kliensek tovább működnek.
Migrate (átállás): a klienseket fokozatosan át kell állítani az újra; külső fogyasztóknál ez általában a leghosszabb szakasz.
Contract (szűkítés): ha már semmi nem használja a régit, el kell távolítani.
flowchart LR
E["Expand:<br/>régi és új együtt"] --> M["Migrate:<br/>kliensek átállnak"] --> C["Contract:<br/>a régi törlése"]
A kockázat, hogy a szolgáltató két változatot tart fenn, és a szűkítés elmarad. Egy átnevezett mezőnél átmenetileg mindkét mező jelen lehet; meg kell adni, melyik az irányadó, és mi történik ellentmondó értékeknél.
Szerződésellenőrzés
A szolgáltató ellenőrizheti, hogy a válasza megfelel a publikált sémának és példáknak. A consumer-driven contract teszt (a fogyasztó által vezérelt szerződés) a fogyasztó tényleges elvárásait rögzíti: a Pact leírása szerint a fogyasztó tesztjei konkrét kérés–válasz példák formájában hozzák létre a szerződést, ezért csak azt ellenőrzik, amit a fogyasztó ténylegesen használ. A Pact oldala szerint ez nem helyettesíti a sémát (az statikus leírás a lehetséges állapotokról), és a szolgáltató önmagához mért ellenőrzése sem pótolja a fogyasztói tesztet. Egy séma szerint érvényes válasz lehet hibás üzleti eredmény, és a kompatibilis API is lehet elérhetetlen rossz útválasztás miatt.
Gyakori tévhitek
Állítás
Pontosítás
„Ha a séma nem változik, a szerződés sem.”
A jelentés változása is törő lehet.
„Új mező hozzáadása mindig biztonságos.”
Szigorú kliensnél törést okozhat.
„A verziószám megoldja a kompatibilitást.”
Csak elkülöníti a változatokat.
„A séma ellenőrzése elég.”
A viselkedést és az integrációt is vizsgálni kell.
Röviden
A szerződés szintaktikai, szemantikai, viselkedési és működési réteget tartalmaz.
A kompatibilitás a fogyasztó viselkedésétől is függ; a tolerant reader csökkenti a törést.
Kommunikációs szerződés és verziók együttélése
Célok
A lecke végére meg tudod különböztetni a szerződés rétegeit, fel tudod ismerni a kompatibilis és a törő változtatást, és el tudod magyarázni az expand–migrate–contract módszert.
Miért kell?
A szolgáltatások akkor adhatók ki önállóan, ha a régi és az új változatok egy ideig együtt működnek. A szerződés ezért több a mezők listájánál: megadja a művelet jelentését, a bemenet korlátait, a kimenetet, a hibákat és a megengedett ismétlést.
A szerződés rétegei
priceszámpriceforintban, bruttóban értendőreservecsak ellenőriz, vagy foglal is; meddig érvényes; mi történik ismétléskorA típusból nem következik az értelmezés: ugyanaz a szám jelenthet forintot, fillért vagy belső egységet.
Kompatibilis és törő változtatás
Egy új opcionális mező általában könnyebben bevezethető, mint egy régi kötelező átnevezése. A kompatibilitás azonban a fogyasztó viselkedésétől is függ: egy szigorú dekóder az ismeretlen mezőt is elutasíthatja, és egy új enumérték gondot okozhat, ha a kliens a lehetséges értékeket lezártnak tekinti. Fowler tolerant reader mintája szerint a fogyasztó csak azt olvassa, amire szüksége van, és a többit figyelmen kívül hagyja, így a szolgáltató kevesebb esetben törik meg a klienseket. A minta Postel törvényére épül: legyél konzervatív abban, amit küldesz, és liberális abban, amit elfogadsz.
A szemantikai változtatás a legveszélyesebb: ha az
összegkorábban bruttót jelentett, később nettót, a séma változatlan maradhat, mégis törik az együttműködés. Ezért a szerződésellenőrzésnek a viselkedést is vizsgálnia kell.Parallel change: expand, migrate, contract
Fowler leírása szerint a visszafelé nem kompatibilis változtatás biztonságosan három szakaszban végezhető:
A kockázat, hogy a szolgáltató két változatot tart fenn, és a szűkítés elmarad. Egy átnevezett mezőnél átmenetileg mindkét mező jelen lehet; meg kell adni, melyik az irányadó, és mi történik ellentmondó értékeknél.
Szerződésellenőrzés
A szolgáltató ellenőrizheti, hogy a válasza megfelel a publikált sémának és példáknak. A consumer-driven contract teszt (a fogyasztó által vezérelt szerződés) a fogyasztó tényleges elvárásait rögzíti: a Pact leírása szerint a fogyasztó tesztjei konkrét kérés–válasz példák formájában hozzák létre a szerződést, ezért csak azt ellenőrzik, amit a fogyasztó ténylegesen használ. A Pact oldala szerint ez nem helyettesíti a sémát (az statikus leírás a lehetséges állapotokról), és a szolgáltató önmagához mért ellenőrzése sem pótolja a fogyasztói tesztet. Egy séma szerint érvényes válasz lehet hibás üzleti eredmény, és a kompatibilis API is lehet elérhetetlen rossz útválasztás miatt.
Gyakori tévhitek
Röviden
Ellenőrző kérdések
Források