Pjan tat-Testijiet Pre-Produzzjoni għal API tal-Kontabilità

Rispons 201 Created minn API tal-kontabilità ma jgħidlek kważi xejn. Huwa jikkonferma biss li s-server wieġeb. Ma jikkonfermawx li teżisti fattura waħda eżatta, li d-debiti huma daqs il-krediti, li n-numru tad-dokument ġie allokat darba biss, jew li tentattiv ġdid wara konnessjoni li tinqata’ mhux se jibbukkja t-tieni kopja. Il-biċċa l-kbira tad-duplikati fil-kontabilità tal-produzzjoni jiġu minn dik il-lakuna: mutazzjoni li kkonfermat fuq is-server waqt li l-klijent baqa’ b’riżultat mhux magħruf u reġa’ pprova bil-kwiet b’ċavetta friska.

Dan il-pjan huwa għal timijiet li qed jevalwaw API tal-kontabilità qabel ma jintegrawha fil-kotba reali. Huwa jiffoka fuq l-imġiba meta jinqalgħu l-fallimenti, u mhux fuq il-każijiet ideali biss. Kull taqsima hawn taħt tiddikjara x’għandek tittestja, x’għandek tivverifika, u x’jammonta għal test li rnexxa. Il-kuntest ta' implimentazzjoni hawnhekk huwa Nordlet, li l-API tagħha tuża ċwievet bearer bl-scope, ammonti b'string deċimali, ċwievet tal-idempotenza, u webhooks iffirmati. Għas-sintassi eżatta tal-endpoint u l-kuntratti tar-rispons, aqra l-paġni Konvenzjonijiet tal-API u Bidu mgħaġġel minflok ma tiddependi fuq preżunzjonijiet.

Xi jfisser verament li "tgħaddi" mit-test

Test jipprova li integrazzjoni tal-kontabilità hija sigura biss meta jivverifika s-semantika, u mhux il-kodiċijiet tal-istatus. Għal kull xenarju, is-suite għandha tikkonferma:

• Effett sekondarju fuq in-negozju: jeżisti eżattament klijent wieħed, fattura waħda, dħul wieħed fil-ġurnal, allokazzjoni ta’ numru wieħed, jew tranżizzjoni ta’ pagament waħda.
• Integrità tal-kontabilità: id-debiti huma daqs il-krediti, u l-preċiżjoni monetarja tibqa' sħiħa wara s-serialisation.
• Imġiba ta’ rrepetizzjoni (replay): tentattiv ġdid jirritorna r-riżultat oriġinali minflok rekord ġdid.
• Durabilità: ir-rekords tal-awditjar u l-avvenimenti tal-webhooks jeżistu ladarba l-operazzjoni tikkonferma.
• Fallimenti mingħajr effetti sekondarji: talbiet miċħuda ma jikkunsmaw l-ebda numru tad-dokument u ma jiktbu l-ebda linja parzjali fil-ledger.
• Irkupru: żball transitorju jista’ jerġa’ jiġi pprovat mingħajr duplikazzjoni jew telf permanenti.

Il-gwida tal-API ta' Google tpinġi l-linja b'mod ċar: l-operazzjonijiet biss li l-e ejecución ripetuta tagħhom tħalli l-istess stat finali huma siguri biex jerġgħu jiġu pprovati, u API għandha tidentifika liema operazzjonijiet huma idempotenti minflok ma terġa' tipprova kull falliment bl-addoċċ.

Waqqaf ambjent li jista’ jintrema u jiġi osservat

Uża kumpanija sandbox, mhux il-kotba tal-produzzjoni. Kumpanija sandbox ta’ Nordlet tuża l-istess moduli u l-istess imġiba tal-API bħal kumpanija reali u hija mmarkata bħala data tat-test, li tagħmilha sigura għal testijiet ta' duplikazzjoni u fallimenti b'volum għoli. Din il-marka ma tistax tinbidel wara l-ħolqien, sabiex il-kotba reali ma jkunux jistgħu jerġgħu jiġu kklassifikati bħala data tat-test aktar tard. Innota li l-użu tas-sandbox jitkejjel u jiġi fatturat eżattament bħall-użu f'kumpanija reali, għalhekk qabbel il-volum tat-testijiet tiegħek mal-mudell tal--ipprezzar li tinsab fih.

Qabel tikteb xi test, ipprepara:

• Kumpanija sandbox dedikata b’isSandbox: true.
• Ċavetta tal-API tat-test bl-scope limitat biss għall-moduli li qed jiġu ttestjati.
• Endpoint tal-webhook jew mina lokali (local tunnel) li tippreserva l-korp tat-talba (request body) oriġinali.
• Klijenti, fornituri, u chart of accounts magħruf li diġà ddaħħlu (seeded).
• Mill-inqas żewġ perjodi tal-kontabilità: waħda miftuħa, u waħda msakkra.
• Arloġġ tat-test jew fixture tad-data jekk l-implimentazzjoni tappoġġjah.
• Maħżen lokali li jirreġistra kull tentattiv ta’ talba, ċavetta tal-idempotenza, hash tar-rispons, konsenja ta’ webhook, u riżultat ta’ rikonċiljazzjoni.

Tmexxix testijiet ta’ duplikazzjoni fuq data ta' staging kondiviża. Klijent jew fattura mitlufa minn test preċedenti tagħmel l-affermazzjonijiet sussegwenti ambigwi.

Il-fixture tiegħek għal kull mutazzjoni għandha taqbad il-metodu, l-endpoint, il-korp sħiħ, iċ-ċavetta tal-idempotenza, l-scope taċ-ċavetta, ID tal-korrelazzjoni tal-klijent, il- timestamp tal-bidu u tat-tmiem, l-istatus tar-rispons, il-headers, il-korp, l-ID tat-talba, u jekk il-konnessjoni inqatgħetx qabel ma wasal ir-rispons. Uża strings deċimali fissi bħal "75.0000" għall-flus. Nordlet tirrappreżenta valuri monetarji bħala strings deċimali b’sa erba’ pożizzjonijiet deċimali, u l-fattura eżempju tagħha tuża dak il-format.

In-naħa l-oħra tas-setup hija l-injezzjoni tal-fallimenti. Is-sistema tat-test tiegħek għandha tkun kapaċi ttardja rispons, taqta’ konnessjoni TCP wara li s-server ikun irċieva t-talba, tirritorna rispons sintetiku 429/500/502/503/504, tirritorna rispons mhux 2xx mir-riċevitur tal-webhook, twassal l-istess webhook darbtejn, tibdel l-ordni tal-avvenimenti, tikkorrompi byte wieħed minn korp ta’ webhook, tibdel il-payload ta’ ċavetta tal-idempotenza filwaqt li żżomm l-istess ċavetta, tmexxi żewġ talbiet identiċi fl-istess ħin, u tissakkar perjodu bejn is-setup u l-istivar (posting). Dawn ix-xenarji jiswew aktar minn mitt eżempju ta’ każijiet ideali.

Illokkja l-kuntratt qabel tikteb il-loġika tal-irkupru

Iġġenera jew ġib l-OpenAPI schema u qabblaha mal-klijent tiegħek. Nordlet tippubblika l-OpenAPI spec tagħha fir-referenza tal-API u tiġġenera s-SDKs ittajpjati tagħha minn dik l-istess spec, għalhekk it-testijiet ibbażati fuq l-iskema huma aħjar minn suppożizzjonijiet magħmulin bl-idejn.

Ivvifika l-oqsma u t-tipi meħtieġa, l-oqsma tal-istring deċimali, il-format tad-data u t-timestamps, l-azzjonijiet u l-iskopijiet permessi, il-forma tal-envelope tal-iżball, l-iskemi tal-avvenimenti tal-webhooks, liema mutazzjonijiet jaċċettaw ċavetta tal-idempotenza, u liema oqsma tar-rispons jidentifikaw l-oġġett maħluq.

Kriterji ta’ suċċess. Il-klijent jirrifjuta payloads invalidi lokalment fejn l-iskema tippermettihom. Ir-rispons tas-server jaqbel mal-iskema dokumentata. Deċimali invalidi, dati ħżiena, u oqsma meħtieġa neqsin jipproduċu żbalji ta’ validazzjoni strutturati. L-ebda tentattiv ieħor ma jsir għal falliment ta’ validazzjoni deterministiku.

Mod ta’ falliment li għandu jinqabad. Klijent jikkonverti "121.0000" f'float binarju u aktar tard jis-serialise ammont kemxejn differenti. In-numri sħaħ jgħaddu; il-linji tal-VAT u l-kwantitajiet frazzjonali jfallu. Ittestja l-flus bħala strings mill-bidu sal-aħħar.

Awtorizzazzjoni u iżolament tal-inkwilini (tenants)

Uża ċwievet separati għall-qari u l-kitba. Imbagħad ittestja l-grilja sħiħa: ċavetta nieqsa, ċavetta invalida, ċavetta valida b’scope tal-modulu insuffiċjenti, ċavetta valida bis-scope tajjeb, ċavetta li tappartjeni lil kumpanija oħra, u tentattiv biex taqra oġġett minn kumpanija differenti.

Asserzzjonijiet:

• Kredenzjali neqsin jew invalidi jirritornaw 401.
• Ċavetta valida mingħajr il-permess meħtieġ tirritorna 403.
• L-ebda effett sekondarju fil-kontabilità ma jinħoloq għal ebda wieħed mill-fallimenti.
• Talba ta’ suċċess ma tistax taqra jew timmuta r-rekords ta’ kumpanija oħra.
• Il-fallimenti tas-sigurtà qatt ma jerġgħu jiġu pprovati awtomatikament.

Kriterju ta’ suċċess. Tista’ tipprova kemm il-korrettezza tal-awtorizzazzjoni kif ukoll l-iżolament tal-inkwilini permezz ta’ qari wara t-test, mhux biss permezz tal-kodiċijiet tal-istatus.

Ipprova tranżizzjoni nadifa waħda

Mexxi fluss żgħir u deterministiku: oħloq jew sib klijent tat-test, oħloq fattura b’ammonti ta’ string deċimali, emettiha, aqra l-fattura u l-effett tal-kontabilità tagħha, aqra r-rekord tal-awditjar, u rċievi l-webhook. L-eżempju Bidu Mgħaġġel ta’ Nordlet juri l-emissjoni ta’ fattura li talloka numru konsekuttiv mingħajr vojt, tiċċekkja li l-perjodu huwa miftuħ, u tpoġġi dħul ibbilanċjat fil-ġurnal fl-istess tranżizzjoni.

Asserixxi li l-fattura tilħaq l-istat mistenni, in-numru tad-dokument jiġi allokat darba biss, id-debiti huma daqs il-krediti, il-VAT u t-total tal-linja jaqblu mal-kalkolu mistenni (half-up), ir-rekord tal-awditjar isemmi l-persuna u l-bidla, il-webhook eventwalment jitwassal, u r-rispons tal-API flimkien ma’ qari ta' segwitu jaqblu fuq l-ID tal-fattura u l-istat tagħha.

Distinzjoni waħda li ta’ min wieħed iżomm f'moħħu: il-wasla ta’ webhook mhijiex prova li l-mutazzjoni kkonfermat. Ir-rispons tal-API flimkien ma’ qari mill-ġdid huma l-affermazzjonijiet primarji tat-tranżizzjoni tiegħek. Il-webhook jipprova n-notifika downstream, u jiġi ttestjat separatament.

Idempotenza: l-istess ċavetta, l-istess korp

Iġġenera ċavetta waħda għal kull operazzjoni loġika tan-negozju, mhux ċavetta waħda għal kull tentattiv fuq in-network. Ibgħat il-mutazzjoni biċċ-ċavetta K u l-korp B, aħżen l-ID maħluqa, imbagħad erġa’ ibgħat eżattament l-istess talba.

Asserixxi li t-tieni rispons jirrappreżenta l-istess operazzjoni, l-ID tal-oġġett hija identika, u hemm oġġett wieħed tan-negozju, stivar wieħed, numru ta’ dokument wieħed, u effett finanzjarju wieħed. Ir-rispons ripetut għandu jkollu l-header dokumentat tar-replay – x-idempotent-replay: true fil-każ ta' Nordlet – u l-istorja tal-awditjar m'għandha turi l-ebda tieni mutazzjoni.

Żewġ regoli tal-ħażna jibdlu dak li l-linja tal-irkupru tiegħek għandha tistenna, għalhekk ittestjahom direttament: rispons 4xx maħżun jerġa’ jintbagħat bħal kull rispons ieħor, filwaqt li żball 5xx ma jinħażen xejn, għalhekk tentattiv ġdid wara żball tas-server jerġa’ jeżegwixxi l-operazzjoni minflok ma jerġa' jibgħat ir-rispons maħżun. Iċ-ċwievet ukoll jiskadu, f'Nordlet wara 24 siegħa, li jillimita kemm idum disponibbli r-replay.

Id-dokumentazzjoni ta’ Nordlet wegħdet li ż-żieda ta’ header Idempotency-Key tipprevjeni li talba li terġa’ tiġi pprovata toħloq duplikat, u l-konvenzjonijiet tal-API tagħha jiddefinixxu l-header eżatt tar-replay u r-rekwiżit ta' rispons identiku byte b'byte. Il-prinċipju jaqbel mal-mudell ippubblikat ta’ Stripe: ċavetta tidentifika l-operazzjoni loġika, ir-ripetizzjonijiet jirritornaw ir-riżultat maħżun, u ċavetta użata mill-ġdid b’parametri differenti tiġi miċħuda minflok ma tinbidel fis-skiet.

Kriterju ta’ suċċess. Eżattament tranżizzjoni waħda tal-istat finanzjarju teżisti irrispettivament minn kemm-il darba l-klijent jibgħat l-istess talba fil-perjodu tar-replay.

Idempotenza: l-istess ċavetta, korp mibdul

Ibgħat it-talba oriġinali biċċ-ċavetta K u l-korp B1, imbagħad it-tieni talba biċċ-ċavetta K u l-korp B2 fejn mill-inqas ammont wieħed, klijent, data, jew linja huma differenti.

Riżultat mistenni: it-talba tiġi miċħuda bl-iżball dokumentat tal-użu mill-ġdid taċ-ċavetta – Nordlet tirritorna 422 idempotency_key_reuse – ir-rekord oriġinali ma jintmessx, l-ebda tieni rekord jew numru jew mutazzjoni fl-awditjar ma jidher, u l-klijent ma "jsirihx" billi jiġġenera ċavetta ġdida. L-aċċettazzjoni fis-skiet ta’ B2 tagħmel iċ-ċwievet tat-tentattivi mhux siguri.

Talbiet doppji konkorrenti

Ibgħat żewġ talbiet identiċi bl-istess ċavetta fl-istess ħarsa ta’ żmien. Skont l-imġiba dokumentata, waħda tiġi eżegwita waqt li l-oħra tirċievi kunflitt ta’ tħaddim – Nordlet tirritorna 409 idempotency_in_progress – jew it-tnejn eventwalment josservaw l-istess riżultat.

Asserixxi li ż-żewġ sejħiet ma jistgħux joħolqu effetti finanzjarji indipendenti, l-aktar numru wieħed ta’ dokument jiġi allokat, kunflitt temporanju jerġa’ jiġi pprovat bl-istess ċavetta minflok b’waħda ġdida, ir-riżultat finali huwa sħiħ u jista’ jinqara, u r-rekord tal-idempotenza ma jibqgħux imwaħħal b’mod permanenti.

Mod ta’ falliment. Librerija ta’ tentattivi li tiġġenera UUID frisk għal kull tentattiv tibdel operazzjoni loġika f’diversi kitbiet indipendenti u tħassar l-idempotenza għal kollox.

Ir-riżultat inċert wara konnessjoni li tinqata’

Din hija l-aktar simulazzjoni tal-produzzjoni importanti. Ibgħat mutazzjoni biċċ-ċavetta K, ħalli s-server jikkonfermaha, aqta’ l-konnessjoni qabel ma jasal ir-rispons, irreġistra r-riżultat bħala mhux magħruf, imbagħad erġa’ pprova bl-istess ċavetta K u irrikonċilja billi taqra r-riżultat u d-data tal-awditjar.

Asserixxi li t-tentattiv il-ġdid jirritorna r-rispons oriġinali jew dak dokumentat tar-replay, jeżisti eżattament effett sekondarju finanzjarju wieħed, il-klijent jimmarka l-operazzjoni bħala kompluta biss wara replay b’suċċess jew qari ta’ rikonċiljazzjoni, u l-ebda ċavetta ġdida ma tiġi ġġenerata. Timeout ma jfissirx "ma ġara xejn". Stripe tiddeskrivi l-idempotenza preċiżament bħala protezzjoni kontra żbalji ta’ konnessjoni fejn is-server jista’ jkun ipproċessa mutazzjoni qabel ma l-klijent seta’ jirċievi r-rispons.

Politika konservattiva ta’ tentattivi

Id-deċiżjonijiet ta’ tentattivi jiddependu kemm fuq l-iżball kif ukoll fuq jekk l-operazzjoni hijiex idempotenti, u mhux fuq il-metodu HTTP waħdu.

Normalment jistgħu jerġgħu jippruvaw, b’ċavetta miżmuma: konnessjoni li rrisettjat jew timeout wara mutazzjoni idempotenti, 408, 429 wara li jiġi segwit retry-after, u 502/503/504. Rispons dokumentat ta’ idempotenza f’nofs tħaddim jista’ jerġa’ jiġi pprovat wara dewmien qasir.

Ma jistgħux jerġgħu jippruvaw mingħajr rikonċiljazzjoni: żbalji ta’ validazzjoni 400/422, fallimenti tal-awtentikazzjoni 401/403, 404 għal riżorsa nieqsa, kunflitti tan-negozju 409 li ma jaqblux ma’ ċavetta li tinsab fil-proċess, payload mibdul fuq ċavetta eżistenti, u rifjut minħabba perjodu msakkar.

Asserixxi l-użu ta’ backoff esponenzjali marbut bi ftit każwalità (jitter), massimu espliċitu ta’ tentattivi u ħin mgħoddi, l-onorar ta’ retry-after għal-limiti tar-rata, l-istess ċavetta miżmuma ma’ tentattivi ta’ operazzjoni waħda, ċavetta ġdida għal kull operazzjoni ġdida, u logs li jisseparaw it-tentattiv oriġinali minn dawk li segwew.

Ittestja l-limitazzjoni tar-rata (rate limiting) weħidha. Aqbeż il-limitu dokumentat – Nordlet tippermetti 300 talba fil-minuta għal kull ċavetta tal-API b’mod awtomatiku, u xi endpoints mhux awtentikati għandhom il-limiti inferjuri tagħhom stess għal kull indirizz – imbagħad ikkonferma li s-server jirritorna rispons tal-limitazzjoni tar-rata, il-klijent janalizza retry-after bħala dewmien minflok bħala żball, jieqaf għal ftit minflok ma jkompli jattakka, u tentattiv ta’ mutazzjoni limitata jerġa’ juża ċ-ċavetta oriġinali. Il-headers x-ratelimit-* jirrapportaw il-baġit li fadal, li jagħmel pre-affermazzjoni tajba. Żomm it-testijiet tal-limitazzjoni tar-rata 'l bogħod mill-affermazzjonijiet finanzjarji sakemm il-fixture tiegħek ma jkunx jista’ jiddistingwi tentattiv limitat minn wieħed ikkonfermat.

Verifika tal-firma tal-webhook

Ibni riċevitur li jippreserva l-bytes oriġinali. Għal kull avveniment: aqbad il-korp oriġinali, aqra l-header x-nordlet-signature, ikkalkula l-HMAC-SHA256 mistenni bis-sigriet tas-sabskrizzjoni, qabbel bl-użu ta’ funzjoni b’ħin kostanti (constant-time), analizza l-JSON biss wara l-verifika, irreġistra l-kunsinna, u rritorna rispons veloċi 2xx wara aċċettazzjoni durabbli. Nordlet tiffirma HMAC fuq il-korp oriġinali, tibgħatu bħala sha256=<hex>, u terġa’ tipprova l-kunsinni b’backoff esponenzjali. Il-gwida tal-webhooks ta’ Stripe tenfasizza l-verifika tal-korp oriġinali mhux immodifikat b'paragun f'ħin kostanti.

Mexxi testijiet negattivi: korp u sigriet korretti, korp korrett b’sigriet ħażin, bidla ta’ byte wieħed fil-korp, JSON jerġa' jiġi serializzat b’ispazji bojod mibdula, header nieqes, firma malformata, kunsinna qadima rrepetuta jekk l-iskema tinkludi timestamp, u firma valida mwassal lis-sabskrizzjoni l-ħażina.

Kriterji ta’ suċċess. Il-korp oriġinali u s-sigriet korretti biss huma aċċettati. Firmat invalidi jirċievu rispons mhux 2xx. Payloads invalidi qatt ma jidħlu fil-kju tal-kontabilità. Is-sigrieti jibqgħu barra mill-logs ordinarji. Il-handler jirrikonoxxi biss wara li l-avveniment jiġi rreġistrat b’mod durabbli.

Webhooks doppji u barra mill-ordni

L-affidabbiltà tal-kunsinna hija problema separata mill-idempotenza tal-API, u r-riċevitur irid ikun ukoll idempotent. Wasal l-istess avveniment darbtejn, wasal avveniment sale_invoice.paid qabel avveniment sale_invoice.issued, iriturna 500 wara li tiġi ppeġġjata iżda qabel ir-rispons, u rrepeti avveniment li l-konsumatur kien diġà pproċessa.

Asserixxi li kunsinni doppji ma jidduplikawx pagamenti, tibdil fl-istatus, jew azzjonijiet fil-ġurnal, li ċ-ċavetta tad-deduplikazzjoni tuża l-ID tal-kunsinna jew tal-avveniment tal-fornitur meta teżisti (jew ċavetta komposta dokumentata, qatt timestamp arbitrarju), li avvenimenti barra mill-ordni qatt ma jgħattu stat aktar ġdid b’wieħed eqdem, li l-konsumatur jista’ jġib l-istat kurrenti mill-API meta l-ordni ma tkunx biżżejjed, u li tentattivi falluti mill-konsumatur jgħaddu minn kju jew triq tad-dead-letter. Stripe twissi b’mod espliċitu li l-ordni tal-kunsinna mhijiex garantita u tirrakkomanda li jinħażnu l-IDs tal-avvenimenti pproċessati.

Żomm l-endpoint ħafif: ivvalida l-forma, ivverifika l-firma, aħżen jew poġġi fil-kju, irrikonoxxi, irritorna 2xx. Ir-rikonċiljazzjoni u n-notifikazzjonijiet jappartjenu għall-ipproċessar asinkroniku. Ittestjaha billi tagħmel ix-xogħol downstream jorqod wara t-timeout tal-kunsinna; riċevitur korrett xorta jirrikonoxxi wara li jitqiegħed fil-kju b’mod durabbli.

Perjodi tal-kontabilità miftuħa u msakkra

Nordlet timponi l-imblokk tal-perjodi fil-ħin tal-istivar f’ġurnali manwali, flussi ta’ dokumenti, u importazzjonijiet, għalhekk ittestja l-kontroll f’aktar minn post wieħed. Oħloq dokumenti ekwivalenti datati f’perjodu miftuħ, f’perjodu msakkar, fil-konfini eżabel qabel l-imblokk, fl-ewwel jum tal-perjodu miftuħ li jmiss, u b’data valida tad-dokument iżda data ta’ stivar invalida jekk l-API tissepara t-tnejn.

Għall-każ tal-perjodu msakkar, asserixxi li t-talba tiġi miċħuda bl-iżball dokumentat tal-imblokk tal-perjodu – żball 409 conflict f’Nordlet – u li l-ebda linja tal-ġurnal ma tinkiteb, l-ebda numru tad-dokument ma jiġi kkunsmat, l-ebda dokument ma jgħaddi għall-istat stivat, u l-ebda webhook ta’ suċċess ma jiġi attivat. Il-verżjoni tal-perjodu miftuħ għandha tirnexxi bl-istess valuri finanzjarji.

Test ta’ kompetizzjoni (race test). Ibda stivar kontra perjodu miftuħ, illokkja l-perjodu f’nofs it-talba, u kkonferma li l-konferma ma tistax taqbeż l-imblokk. Il-kundizzjoni kritika ta’ suċċess: stivar ikkonfermat qatt ma jispiċċa f’perjodu li kien imsakkar qabel ma t-tranżizzjoni kkonfermat.

Awditjabilità u rikonċiljazzjoni

Għal kull mutazzjoni ta’ suċċess, ikkonferma li l-oġġett tan-negozju eżisti, id-dħul fil-kontabilità jeżisti b’debiti ugwali għall-krediti, ir-rekord tal-awditjar jeżisti, l-avveniment tal-webhook jeżisti jew jista’ jinġieb, u r-rekord tal-operazzjoni tiegħek jindika l-ID tal-oġġett tal-fornitur b’tentattivi li jirreferu għall-istess operazzjoni loġika.

Għal kull mutazzjoni miċħuda, ikkonferma li l-ebda dokument parzjali ma jeżisti, l-ebda numru ma ġie kkunsmat sakemm il-kuntratt ma jippermettix riżerva, l-ebda dħul fil-ledger ma jeżisti, l-ebda webhook ta’ suċċess ma jeżisti, u l-iżball iġorr ID tat-talba għad-dijanjosi. Il-konvenzjonijiet ta’ Nordlet jiddeskrivu l-awditjabilità tal-mutazzjonijiet u l-istivar ibbilanċjat bħala garanziji tal-pjattaforma, bil-bilanċ impost minn trigger deferit fid-database fil-ħin tal-konferma minflok permezz tal-kodiċi tal-applikazzjoni waħdu. Iddawwar dawk il-garanziji f’mistoqsijiet ta’ rikonċiljazzjoni wara t-test minflok ma tiddependi fuq ir-rispons HTTP.

Matriċi ewlenija tat-testijiet

Żona	Azzjoni tat-test	Asserzzjoni mistennija	Kriterju ta’ suċċess
Awtentikazzjoni	Ebda ċavetta, ċavetta invalida, scope insuffiċjenti	401/403 strutturat; ebda effett sekondarju	It-tentattivi miċħuda kollha ma joħolqu l-ebda rekord tal-kontabilità
Skema u flus	Deċimali invalidu, data, qasam meħtieġ	Żball ta’ validazzjoni fil-livell tal-qasam	L-ebda tentattiv ġdid jew kitba parzjali ma sseħħ
Stivar normali	Oħloq u emetti fattura f’perjodu miftuħ	Dokument wieħed, ġurnal ibbilanċjat wieħed, rekord ta’ awditjar wieħed	L-istat tal-qari mill-ġdid u l-ledger jaqblu
Ripetizzjoni bl-istess ċavetta	Irrepeti mutazzjoni identika, l-istess ċavetta u korp	Riżultat oriġinali ripetut; l-ebda duplikat	ID tal-oġġett, numru, effett fil-ġurnal, awditjar jibqgħu uniċi
Korp mibdul, l-istess ċavetta	Uża ċ-ċavetta mill-ġdid b’ammont differenti	Rifjut dokumentat tal-użu mill-ġdid taċ-ċavetta	Rekord oriġinali mhux mibdul; xejn ġdid miktub
Konnessjoni li nqatgħet	Ikkonferma, aqta’, erġa’ pprova bl-istess ċavetta	Riżultat ripetut	Eżattament effett sekondarju finanzjarju wieħed
Perjodu msakkar	Stiva dokument datat f’perjodu msakkar	Rifjut minħabba perjodu msakkar	L-ebda ġurnal, l-ebda numru, l-ebda webhook ta’ suċċess
Firma tal-webhook	Sigriet ħażin, korp mibdul	Mhux 2xx mir-riċevitur	Korp oriġinali u sigriet korretti biss huma aċċettati

X’kont nagħmel l-ewwel

Jekk iż-żmien huwa qasir, mexxi t-testijiet fl-ordni li taqbad l-aktar bugs għaljin. Ibda bit-tentattiv wara li tinqata’ l-konnessjoni, għax dak ix-xenarju uniku jipproduċi l-biċċa l-kbira tad-duplikati reali. Imbagħad il-par tal-idempotenza tal-istess ċavetta u korp mibdul. Imbagħad il-perjodi msakkra, peress li stivar f’xahar magħluq huwa problema ta’ awditjar li tidher tard. Il-verifika tal-firma u l-webhooks barra mill-ordni jiġu wara, u l-iskema sħiħa flimkien mal-grilja tal-awtorizzazzjoni jistgħu jitmexxew kontinwament fis-CI ladarba l-klijent jistabbilizza.

Kulħadd f’dan il-pjan jappoġġja dawk il-ħamsa. Agħmilhom tajbin kontra kumpanija sandbox, bil-qari tar-rikonċiljazzjoni jikkonferma l-effetti sekondarji, u tkun taf li l-integrazzjoni hija sigura qabel ma tmiss ledger wieħed reali. Tista’ toħloq kumpanija sandbox u ċavetta tat-test b’scope f’ftit minuti minn Bidu mgħaġġel, u tiċċekkja liema moduli għandek bżonn kontra l-lista tal-karatteristiċi.

FAQ

Ir-rispons 2xx huwa biżżejjed biex tikkonferma li kitba fil-kontabilità rnexxiet?

Le. Kodiċi tal-istatus jikkonferma biss li s-server wieġeb, u mhux li teżisti eżattament fattura waħda, allokazzjoni ta’ numru wieħed, u dħul ibbilanċjat wieħed fil-ġurnal. Kull test ta’ mutazzjoni għandu jsegwi r-rispons b’qari mill-ġdid tal-oġġett, l-effett tal-kontabilità tiegħu, u r-rekord tal-awditjar tiegħu. Il-każ perikoluż huwa fid-direzzjoni opposta: operazzjoni li kkonfermat waqt li l-klijent qatt ma irċieva r-rispons xejn.

Għandi niġġenera ċavetta ġdida tal-idempotenza meta talba tiskadi (timeout)?

Le, u dan huwa l-iżball li jikkawża l-biċċa l-kbira tad-duplikati fil-produzzjoni. Iċ-ċavetta tidentifika l-operazzjoni loġika tan-negozju, u mhux it-tentattiv fuq in-network. Erġa’ pprova bl-istess ċavetta, imbagħad irrikonċilja billi taqra r-riżorsa. Librerija ta’ tentattivi li tiġġenera UUID frisk għal kull tentattiv tibdel fattura maħsuba f’diversi kitbiet indipendenti.

X’jiġri jekk nuża mill-ġdid ċavetta tal-idempotenza b’payload differenti?

API korretta tirrifjutaha minflok ma tapplika l-korp il-ġdid fis-skiet. Nordlet tirritorna 422 idempotency_key_reuse u tħalli r-rekord oriġinali mhux mibdul. Il-klijent tiegħek għandu jittratta dan b’żball ta’ programmazzjoni li jrid jiġi ffissat, u mhux bħala kundizzjoni li trid tiġi evitat billi tiġi ġġenerata ċavetta ġdida.

Il-webhooks huma sostitut għall-qari mill-ġdid tal-oġġett maħluq?

Le. Il-kunsinna ta’ webhook tipprova n-notifika downstream, u mhux li t-tranżizzjoni kkonfermat bil-mod li tistenna, u l-ordni tal-kunsinna mhijiex garantita. Ivverifika l-firma fuq il-korp oriġinali, agħmel id-deduplikazzjoni fuq l-ID tal-kunsinna jew tal-avveniment, u iġib l-istat kurrenti mill-API kull meta l-ordni tal-avvenimenti waħedha ma tkunx biżżejjed biex tiddeċiedi x’inbidel.

Kif nittestja l-istivar f’perjodu tal-kontabilità imsakkar?

Oħloq dokumenti ekwivalenti f’perjodu miftuħ u f’wieħed imsakkar, u asserixxi li l-każ imsakkar jiġi miċħud mingħajr l-ebda linja tal-ġurnal, l-ebda numru tad-dokument ikkunsmat, l-ebda tranżizzjoni tal-istat, u l-ebda webhook ta’ suċċess. Imbagħad mexxi l-verżjoni tal-kompetizzjoni: ibda stivar kontra perjodu miftuħ u illokkja l-perjodu f’nofs it-talba. Stivar ikkonfermat qatt m'għandu jispiċċa f'perjodu li kien imsakkar qabel ma t-tranżizzjoni kkonfermat.

Nista’ nmexxi testijiet ta’ duplikazzjoni b’volum għoli f’kumpanija sandbox?

Iva. Kumpanija sandbox tġib ruħha bħala waħda reali, hija mmarkata bħala data tat-test, u titħassar immedjatament minflok wara l-perjodu ta’ żamma, u għalhekk hija l-post it-tajjeb għal testijiet distruttivi u ta’ duplikazzjoni. L-użu tas-sandbox xorta jitkejjel u jiġi fatturat bħall-użu reali, għalhekk ippjana l-volum minflok ma tagħmel loops b’mod indefinit.