Kirjanpito-rajapinnan esituotannon testaussuunnitelma

Rajapinnan palauttama 201 Created -vastaus kirjanpito-rajapinnasta ei kerro juuri mitään. Se vahvistaa vain sen, että palvelin vastasi. Se ei vahvista sitä, että järjestelmään syntyi tasan yksi lasku, että debet vastaa kredettiä, että dokumenttinumero varattiin vain kerran tai että yhteyskatkoksen jälkeinen uudelleenyritys ei kirjaakaan toista kopiota. Useimmat tuotannon kirjanpidon tuplat syntyvät juuri tästä kuilusta: palvelimella onnistuneesti tallentunut muutos, jonka lopputuloksesta asiakassovellus oli tietämätön, johti hiljaiseen uudelleenyritykseen uudella avaimella.

Tämä suunnitelma on tarkoitettu tiimeille, jotka arvioivat kirjanpito-rajapintaa ennen sen kytkemistä oikeaan kirjanpitoon. Suunnitelma keskittyy virhetilanteiden käyttäytymiseen, ei onnistumspolkuihin. Jokaisessa alla olevassa osiossa määritellään, mitä testataan, mitä väitteitä (assert) koodin tulee todentaa ja mikä lasketaan läpäisypisteksi. Tässä yhteydessä toteutusympäristönä on Nordlet, jonka rajapinta käyttää suojattuja bearer-avaimia, merkkijonoina esitettyjä desimaalimääriä, idempotenssiavaimia ja allekirjoitettuja webhookeja. Tarkat päätepisteiden syntaksit ja vastaussopimukset selviävät rajapintakäytännöt ja aloitusopas -sivuilta oletusten varaan laskemisen sijaan.

Mitä läpäiseminen oikeasti tarkoittaa

Testi todistaa kirjanpito-integraation turvalliseksi vain silloin, kun se varmentaa semantiikan eikä pelkkiä tilakoodeja. Testisarjan tulee varmistaa jokaisen skenarion osalta seuraavat seikat:

• Liiketoiminnan sivuvaikutus: tasan yksi asiakas, lasku, pääkirjavienti, numerovaraus tai maksun tilasiirtymä on olemassa.
• Kirjanpidon eheys: debet vastaa kredettiä ja rahamääräinen tarkkuus säilyy sarjallistuksessa.
• Uudelleentoistokäyttäryys (replay): uudelleenyritys palauttaa alkuperäisen tuloksen uuden tietueen luomisen sijaan.
• Kestävyys (durability): auditointitietueet ja webhook-tapahtumat ovat olemassa heti kun operaatio on tehty loppuun.
• Virhetilanteet ilman sivuvaikutuksia: hylätyt pyynnöt eivät kuluta dokumenttinumeroita eivätkä kirjoita vajaita tilirivejä.
• Palautuminen: väliaikainen virhe voidaan yrittää uudelleen ilman kahdentumista tai pysyvää tietojen menetystä.

Googlen ohjeistus rajapinnoille vetää rajan selvästi: vain sellaiset operaatiot, joiden toistettu suoritus jättää lopputilan ennaltaan, ovat turvallisia yrittää uudelleen, ja rajapinnan tulisi tunnistaa, mitkä operaatiot ovat idempotentteja sen sijaan, että jokaista virhettä yritettäisiin sokeasti uudelleen.

Pystytä erillinen ja tarkkailtava ympäristö

Käytä hiekkalaatikkoyritystä (sandbox), älä tuotantokirjanpitoa. Nordletin hiekkalaatikkoyritys käyttää samoja moduuleja ja rajapinnan toimintoja kuin oikea yritys, ja se on merkitty testidataksi, mikä tekee siitä turvallisen suurten volyymien kaksois- ja virhetesteille. Merkkaus on muuttumaton luonnin jälkeen, joten todellista kirjanpitoa ei voi myöhemmin luokitella uudelleen testidataksi. Huomaa, että hiekkalaatikon käyttö mitataan ja laskutetaan aivan kuten oikeankin yrityksen käyttö, joten mitoita volyymitestit sen hinnoittelun mukaan, jolla olet.

Ennen kuin kirjoitat yhtään testiä, valmistele seuraavat asiat:

• Erillinen hiekkalaatikkoyritys asetuksella isSandbox: true.
• Testeille tarkoitettu rajapinta-avain, jonka käyttöoikeudet on rajattu vain testattaviin moduuleihin.
• Webhook-päätepiste tai paikallinen tunneli, joka säilyttää alkuperäisen pyynnön rungon sellaisenaan.
• Alustetut asiakkaat, toimittajat ja tunnettu tilikartta.
• Vähintään kaksi tilikautta: yksi avoin, yksi lukittu.
• Testikello tai päivämääräfixture, jos toteutus tukee sellaista.
• Paikallinen tallennuspaikka, joka kirjaa jokaisen pyyntöyrityksen, idempotenssiavaimen, vastaustiivisteen, webhookin toimituksen ja täsmäytystuloksen.

Älä aja kaksoiskirjaustestejä jaettua staging-dataa vastaan. Edellisestä ajosta jäänyt harhainen asiakas tai lasku tekee myöhemmistä väitteistä epäselviä.

Jokaisen muutoksen testiapuvälineen tulisi tallentaa metodi, päätepiste, koko runko, idempotenssiavain, avaimen laajuus (scope), asiakkaan korrelaatiotunniste, aloitus- ja lopetusaikaleimat, vastauksen tila, otsikot, runko, pyyntötunniste sekä tieto siitä, katkesiko yhteys ennen vastauksen saapumista. Käytä rahasummille kiinteitä desimaalimerkkijonoja, kuten "75.0000". Nordlet esittää rahamääräiset arvot desimaalimerkkijonoina, joissa on enintään neljä desimaalia, ja sen esimerkkilasku käyttää tätä muotoa.

Toinen puolikas asetuksia on virheiden syöttö (fault injection). Testauskehyksesi tulisi pystyä viivästyttämään vastausta, katkaisemaan TCP-yhteys sen jälkeen kun palvelin on vastaanottanut pyynnön, palauttamaan synteettisiä 429-, 500-, 502-, 503- tai 504-vastauksia, palauttamaan muuta kuin 2xx-vastausta webhookin vastaanottajalta, toimittamaan saman webhookin kahdesti, muuttamaan tapahtumien järjestystä, korruptoimaan yhden tavun webhookin rungosta, muuttamaan idempotenssiavaimen runkoa pitäen avaimen samana, ajamaan kaksi identtistä pyyntöä samanaikaisesti sekä lukitsemaan tilikauden asetuksen ja kirjauksen välissä. Nämä skenaariot ovat arvokkaampia kuin sata onnistuneen polun esimerkkiä.

Lukitse sopimus ennen uudelleenyrityslogiikan kirjoittamista

Generoi tai hae OpenAPI-skeema ja vertaa sitä asiakassovellukseesi. Nordlet julkaisee OpenAPI-määrityksensä API-viitteessä ja generoi tyypitetyt SDK-kirjastonsa samasta määrityksestä, joten skeemalähtöiset testit päihittävät käsin kirjoitetut arvaukset.

Tarkista vaaditut kentät ja tyypit, desimaalimerkkijonokentät, päivämäärä- ja aikaleimamuodot, sallitut toiminnot ja käyttöoikeusalueet, virhekuoren muoto, webhook-tapahtumien skeemat, mitkä muutokset hyväksyvät idempotenssiavaimen sekä mitkä vastauksen kentät tunnistavat luodun objektin.

Läpäisykriteerit. Asiakassovellus hylkää virheelliset sisällöt paikallisesti silloin, kun skeema niin sallii. Palvelimen vastaukset vastaavat dokumentoitua skeemaa. Virheelliset desimaalit, huonot päivämäärät ja puuttuvat vaaditut kentät tuottavat jäsennnettyjä validointivirheitä. Deterministisen validointivirheen vuoksi ei yritetä uutta lähetystä.

Kiinni otettava virhetilapaikka. Asiakassovellus jäsentää arvon "121.0000" binääriliukuluvuksi (float) ja sarjallistaa hieman poikkeavan summan myöhemmin. Kokonaisluvut menevät läpi, mutta ALV-rivit ja murtolukuluvut epäonnistuvat. Testaa raha merkkijonoina päästä päähän.

Valtuutus ja vuokralaisten eristys (tenant isolation)

Käytä erillisiä avaimia lukuun ja kirjoitukseen. Testaa sen jälkeen koko matriisi: puuttuva avain, virheellinen avain, kelvollinen avain riittämättömällä moduulialueella, kelvollinen avain oikealla alueella, toiseen yritykseen kuuluva avain ja yritys lukea kohde eri yrityksestä.

Väitteet:

• Puuttuvat tai virheelliset tunnukset palauttavat koodin 401.
• Kelvollinen avain ilman vaadittua oikeutta palauttaa koodin 403.
• Kummassakaan virhetilanteessa ei synny kirjanpidon sivuvaikutuksia.
• Onnistunut pyyntö ei voi lukea tai muuttaa toisen yrityksen tietueita.
• Tietoturvavirheitä ei koskaan yritetä automaattisesti uudelleen.

Läpäisykriteeri. Voit todistaa sekä valtuutuksen oikeellisuuden että vuokralaisten eristyksen testin jälkeisillä luvuilla, et pelkän tilakoodin perusteella.

Todista yksi puhdas tapahtuma

Aja pieni, deterministinen kulku: luo tai etsi testiasiakas, luo lasku desimaalimerkkijonomäärillä, julkaise se, lue lasku ja sen kirjanpitoaikavaikutus, lue auditointitietue ja vastaanota webhook. Nordletin aloitusoppaan esimerkki näyttää laskun julkaisun, joka varaa aukottoman numeron, tarkistaa kauden avoimuuden ja kirjaa tasapainoisen pääkirjaviennin samassa transaktiossa.

Varmista, että lasku saavuttaa odotetun tilan, dokumenttinumero varataan tasan kerran, debet vastaa kredettiä, ALV ja rivien summat vastaavat odotettua pyöristystä (half-up), auditointitietue nimeää tekijän ja muutoksen, webhook toimitetaan lopulta ja rajapinnan vastaus sekä sitä seuraava luku ovat samaa mieltä laskun tunnuksesta ja tilasta.

Yksi säilyttämisen arvoinen erottelu: webhookin saapuminen ei ole todiste siitä, että muutos on tehty loppuun. Rajapinnan vastaus sekä lukuoperaatio ovat ensisijaisia transaktioväitteitäsi. Webhook todistaa ilmoituksen siirtymisestä eteenpäin, ja se testataan erikseen.

Idempotenssi: sama avain, sama runko

Luo yksi avain per looginen liiketoimintaoperaatio, älä yhtä avainta per verkkoyritys. Lähetä muutos avaimella K ja rungolla B, tallenna luotu tunnus ja lähetä sitten tasan sama pyyntö uudelleen.

Varmista, että toinen vastaus edustaa samaa operaatiota, objektin tunnus on identtinen ja järjestelmässä on yksi liiketoimintaobjekti, yksi kirjaus, yksi dokumenttinumero ja yksi taloudellinen vaikutus. Toistetun vastauksen tulee kantaa dokumentoitua toistootsikkoa (Nordletin tapauksessa x-idempotent-replay: true), ja auditointiketjun tulee osoittaa, että toista muutosta ei tehty.

Kaksi tallennussääntöä muuttavat sen, mitä uudelleenyrityssilmukkasi tulisi odottaa, joten testaa niitä suoraan: tallennettu 4xx toistetaan kuten mikä tahansa muu vastaus, kun taas 5xx-koodia ei tallenneta lainkaan, joten palvelinvirheen jälkeinen uudelleenyritys suorittaa operaation uudelleen toistamisen sijaan. Avaimet myös vanhenevat (Nordletissa 24 tunnin kuluttua), mikä rajoittaa sitä, kuinka pitkään toisto on saatavilla.

Nordletin dokumentaatio lupaa, että Idempotency-Key -otsikon lisääminen estää uudelleen yritettyä pyyntöä luomasta kaksoiskappaletta, ja sen rajapintakäytännöt määrittelevät tarkan toistootsikon ja tavu-tavulta-vastausvaatimuksen. Periaate vastaa Stripen julkaistua mallia: avain tunnistaa loogisen operaation, toistot palauttavat tallennetun tuloksen, ja eri parametreilla uudelleenkäytetty avain hylätään sen sijaan, että sitä muutettaisiin hiljaisesti.

Läpäisykriteeri. Järjestelmään syntyy tasan yksi taloudellinen tilasiirtymä riippumatta siitä, kuinka monta kertaa asiakas lähettää saman pyynnön toistoikkunan sisällä.

Idempotenssi: sama avain, muuttunut runko

Lähetä alkuperäinen pyyntö avaimella K ja rungolla B1, ja sen jälkeen toinen pyyntö avaimella K ja rungolla B2, jossa vähintään yksi summa, asiakas, päivämäärä tai rivi poikkeaa.

Odotettu tulos: pyyntö hylätään dokumentoidulla avaimen uudelleenkäyttövirheellä (Nordlet palauttaa 422 idempotency_key_reuse), alkuperäinen tietue pysyy koskemattomana, uutta tietuetta, numeroa tai auditointimuutosta ei ilmene, eikä asiakas "korjaa" tilannetta luomalla uutta avainta. Arvon B2 hiljainen hyväksyminen tekisi uudelleenyrityksen avaimista turvattomia.

Samanaikaiset kaksoispyynnöt

Laukaise kaksi identtistä pyyntöä samalla avaimella samalla hetkellä. Dokumentoidun toiminnan mukaan joko toinen suoritetaan samalla kun toinen saa käynnissä olevan konfliktin (Nordlet palauttaa 409 idempotency_in_progress), tai molemmat havaitsevat lopulta saman tuloksen.

Varmista, että molemmat kutsut eivät voi luoda erillisiä taloudellisia vaikutuksia, korkeintaan yksi dokumenttinumero varataan, tilapäinen konflikti yritetään uudelleen samalla avaimella uuden sijaan, lopullinen resurssi on täydellinen ja luettavissa, eikä idempotenssitietue jää pysyvästi jumiin.

Virhetilapaikka. Uudelleenyrityskirjasto, joka luo uuden UUID:n yritystä kohti, muuttaa yhden loogisen operaation useiksi erillisiksi kirjoituksiksi ja tuhoaa idempotenssin kokonaan.

Epävarma lopputulos yhteyskatkoksen jälkeen

Tämä on kaikkein tärkein tuotannon simulaatio. Lähetä muutos avaimella K, anna palvelimen tallentaa se, katkaise yhteys ennen vastauksen saapumista, kirjaa lopputulos tuntemattomaksi, yritä sitten uudelleen samalla avaimella K ja täsmäytä lukemalla resurssi- ja auditointitiedot.

Varmista, että uudelleenyritys palauttaa alkuperäisen tai dokumentoidun toistovastauksen, tasan yksi taloudellinen sivuvaikutus on olemassa, asiakas merkitsee operaation valmiiksi vasta onnistuneen toiston tai täsmäytysluvun jälkeen, eikä uutta avainta luoda. Aikakatkaisu ei tarkoita sitä, että "mitään ei tapahtunut". Stripe kuvaa idempotenssin nimenomaan suojaksi yhteysvirheitä vastaan, joissa palvelin saattaa olla käsitellyt muutoksen ennen kuin asiakas ehti vastaanottaa vastauksen.

Konservatiivinen uudelleenyrityskäytäntö

Uudelleenyrityspäätökset riippuvat sekä virheestä että siitä, onko operaatio idempotentti, eikä pelkästään HTTP-metodista.

Yleensä uudelleenyritettävissä, sama avain säilytetään: yhteys katkennut tai aikakatkaisu idempotenttimuutoksen jälkeen, 408, 429 retry-after-otsikon noudattamisen jälkeen sekä 502/503/504. Dokumentoitu käynnissä olevan idempotenssin vastaus voidaan yrittää uudelleen lyhyen viiveen jälkeen.

Ei uudelleenyritettävissä ilman täsmäytystä: 400/422-validointivirheet, 401/403-todennusvirheet, puuttuvan resurssin 404, liiketoiminnan 409-konfliktit, jotka eivät liity kesken olevaan avaimeen, muuttunut runko olemassa olevalla avaimella sekä kauden lukituksen hylkäys.

Varmista rajoitettu eksponentiaalinen takaisinveto satunnaisuudella (jitter), määritellyt enimmäisyritykset ja kulunut aika, nopeusrajoitusten retry-after-huomiointi, saman avaimen säilyminen yhden operaation yritysten välillä, uusi avain jokaiselle uudelle operaatiolle sekä lokit, jotka erottavat alkuperäisen yrityksen uudelleenyrityksistä.

Testaa nopeusrajoitusta (rate limiting) erikseen. Ylitä dokumentoitu raja (Nordlet sallii oletusarvoisesti 300 pyyntöä minuutissa API-avainta kohti, ja joillakin todentamattomilla päätepisteillä on omat matalammat rajansa osoitetta kohden) ja varmista sitten, että palvelin palauttaa nopeusrajoitusvastauksen, asiakas jäsentää kentän retry-after viiveenä virheen sijaan, se pitää tauon pommittamisen sijaan ja rajoitetun muutoksen uudelleenyritys käyttää uudelleen alkuperäistä avainta. Otsikot x-ratelimit-* kertovat jäljellä olevan budjetin, mikä toimii hyvänä ennakkotarkistuksena. Pidä nopeusrajoitustestit erillään taloudellisista väitteistä, paitsi jos testiapuvälineesi osaa erottaa rajoitetun yrityksen toteutuneesta.

Webhook-allekirjoituksen varmennus

Rakenna vastaanottaja, joka säilyttää raakabytit. Tallenna jokaiselle tapahtumalle raakarunko, lue otsikko x-nordlet-signature, laske odotettu HMAC-SHA256 tilaussalaisuuden (secret) kanssa, vertaa vakioaikaisella funktiolle (constant-time function), jäsennä JSON vasta varmennuksen jälkeen, kirjaa toimitus ja palauta nopea 2xx kestävävän vastaanoton jälkeen. Nordlet allekirjoittaa HMAC:n raakarungosta, lähettää sen muodossa sha256=<hex> ja yrittää toimituksia uudelleen eksponentiaalisella takaisinvedolla. Stripen ohjeistus webhookeista vahvistaa muokkaamattoman raakarungon tarkistamisen vakioaikaisella vertailulla.

Aja negatiiviset testit: oikea runko ja salaisuus, oikea runko väärällä salaisuudella, yhden tavun muutos rungossa, uudelleensarjalistettu JSON muuttuneilla tyhjillä tiloilla, puuttuva otsikko, virheellinen allekirjoitus, toistettu vanha toimitus, jos skeema sisältää aikaleiman, sekä kelvollinen allekirjoitus toimitettuna väärään tilaukseen.

Läpäisykriteerit. Vain oikea raakarunko ja salaisuus hyväksytään. Virheelliset allekirjoitukset saavat muun kuin 2xx-vastauksen. Virheelliset sisällöt eivät koskaan pääse kirjanpitojonoon. Salaisuudet pidetään poissa tavallisista lokeista. Käsittelijä kuittaa vastaanoton vasta sen jälkeen, kun tapahtuma on tallennettu kestävästi.

Kahdennetut ja väärässä järjestyksessä tulevat webhookit

Toimituksen luotettavuus on erillinen ongelma rajapinnan idempotenssista, ja vastaanottajan on oltava myös idempotentti. Toimita sama tapahtuma kahdesti, toimita sale_invoice.paid -tapahtuma ennen sale_invoice.issued -tapahtumaa, palauta 500 tallennuksen jälkeen mutta ennen vastaamista, ja toista tapahtuma, jonka kuluttaja on jo käsitellyt.

Varmista, että kaksoistoimitukset eivät kahdenna maksuja, tilamuutoksia tai kirjaustoimenpiteitä, että deduplikointiavain käyttää palveluntarjoajan toimitus- tai tapahtumatunnistetta silloin, kun sellainen on olemassa (tai dokumentoitua yhdistelmavainta, ei koskaan mielivaltaista aikaleimaa), että väärässä järjestyksessä tulevat tapahtumat eivät koskaan korvaa uudempaa tilaa vanhemmalla, että kuluttaja voi hakea nykyisen tilan rajapinnasta silloin, kun järjestys ei yksin riitä, ja että epäonnistuneet kuluttajayritykset ohjataan jonon tai virhekäsittelypolun (dead-letter) kautta. Stripe varoittaa nimenomaisesti, että toimitusjärjestys ei ole taattu, ja suosittelee käsiteltyjen tapahtumatunnisteiden tallentamista.

Pidä päätepiste kevyenä: validoi muoto, varmista allekirjoitus, tallenna tai laita jonoon, kuittaa ja palauta 2xx. Täsmäytys ja ilmoitukset kuuluvat asynkroniseen käsittelyyn. Testaa tätä saattamalla alavirran työ nukkumaan toimituksen aikakatkaisun ohi; oikein toteutettu vastaanottaja kuittaa silti vastaanoton kestävän jonotuksen jälkeen.

Avoimet ja lukitut tilikaudet

Nordlet valvoo tilikauden lukituksia kirjaushetkellä manuaalisissa päiväkirjoissa, dokumenttikuiluissa ja tuonneissa, joten testaa valvontaa useammassa kuin yhdessä paikassa. Luo vastaavia dokumentteja, joiden päiväys on avoimella kaudella, lukitulla kaudella, rajalla juuri ennen lukitusta, seuraavan avoimen kauden ensimmäisenä päivänä sekä kelvollisella dokumenttipäiväyksellä mutta virheellisellä kirjauspäiväyksellä, jos rajapinta erottaa nämä kaksi toisistaan.

Lukitun kauden tapauksessa varmista, että pyyntö hylätään dokumentoidulla kausilukkovirheellä (Nordletissa 409 conflict), ettei tilirivejä kirjoiteta, dokumenttinumeroa ei kuluteta, dokumentti ei siirry kirjatuksi eikä onnistumisen webhook laukea. Avoimen kauden version pitäisi onnistua samoilla taloudellisilla arvoilla.

Kilpailutilannetesti (race test). Aloita kirjaus avointa kautta vastaan, lukitse kausi kesken pyynnön ja vahvista, että tallennus ei voi ohittaa lukitusta. Kriittinen läpäisyehto: hyväksytty kirjaus ei saa koskaan päätyä kaudelle, joka lukittiin ennen transaktion valmistumista.

Auditointikelpoisuus ja täsmäytys

Varmista jokaisen onnistuneen muutoksen osalta, että liiketoimintaobjekti on olemassa, kirjanpitovienti on olemassa ja debet vastaa kredettiä, auditointitietue on olemassa, webhook-tapahtuma on olemassa tai haettavissa, ja operaatiotietueesi osoittaa palveluntarjoajan objektitunnisteeseen siten, että uudelleenyritykset viittaavat samaan loogiseen operaatioon.

Varmista jokaisen hylätyn muutoksen osalta, että mitään osittaista dokumenttia ei ole olemassa, mitään numeroa ei ole kulutettu, ellei sopimus salli varausta, kirjatiliä ei ole olemassa, onnistumisen webhookkia ei ole olemassa ja virhe kantaa pyyntötunnistetta vianmääritystä varten. Nordletin käytännöt kuvaavat muutosten auditointikelpoisuutta ja tasapainotettuja kirjauksia alustalupauksina, joiden tasapainoa valvoo sovelluskoodin lisäksi viivästetty tietokantaliipaisin (trigger) commit-hetkellä. Muunna nämä lupaukset testin jälkeisiksi täsmäytyskyselyiksi sen sijaan, että luottaisit HTTP-vastauskoodeihin.

Keskeinen testausmatriisi

Alue	Testitoiminto	Odotettu väite	Läpäisykriteeri
Todennus	Ei avainta, virheellinen avain, riittämätön laajuus	Jäsennnetty 401/403; ei sivuvaikutuksia	Kaikki hylätyt yritykset eivät luo kirjanpitotietuetta
Skeema ja raha	Virheellinen desimaali, päivämäärä, puuttuva kenttä	Kenttätason validointivirhe	Uudelleenyritystä tai osittaista kirjoitusta ei tapahdu
Normaali kirjaus	Luo ja julkaise lasku avoimella kaudella	Yksi dokumentti, yksi tasapainotettu kirjaus, yksi auditointitietue	Luku- ja kirjanpitotilat vastaavat toisiaan
Saman avaimen toisto	Toista identtinen muutos, sama avain ja runko	Alkuperäinen tulos toistetaan; ei kaksoiskappaletta	Objektitunniste, numero, kirjausvaikutus ja auditointi pysyvät yksittäisinä
Muuttunut runko, sama avain	Käytä avainta uudelleen eri summalla	Dokumentoitu avaimen uudelleenkäytön hylkäys	Alkuperäinen tietue ennallaan; mitään uutta ei kirjoitettu
Katkennut yhteys	Tallenna, katkaise, yritä uudelleen samalla avaimella	Toistettu tulos	Tasan yksi taloudellinen sivuvaikutus
Lukittu kausi	Kirjaa dokumentti, jonka päiväys on lukitulla kaudella	Kausilukon hylkäys	Ei kirjausta, ei numeroa, ei onnistumisen webhookkia
Webhookin allekirjoitus	Väärä salaisuus, muutettu runko	Muu kuin 2xx vastaanottajalta	Vain oikea raakarunko ja salaisuus hyväksytään

Mitä tekisin ensin

Jos aikaa on vähän, aja testit siinä järjestyksessä, joka nappaa kalleimmat virheet. Aloita yhteyskatkoksen aikaisella uudelleenyrityksellä, koska tämä yksi skenaario tuottaa suurimman osan todellisista tuotannon tuplista. Siirry sitten saman avaimen ja muuttuneen rungon idempotenssipariin. Sen jälkeen lukitut kaudet, sillä kirjaus suljetussa kuussa on auditointiongelma, joka paljastuu myöhään. Allekirjoituksen varmennus ja väärässä järjestyksessä saapuvat webhookit tulevat seuraavana, ja täysi skeema- ja valtuutusmatriisi voi pyöriä jatkuvasti CI-ympäristössä heti, kun asiakassovellus vakiintuu.

Kaikki muu tässä suunnitelmassa tukee näitä viittä. Kun saat ne vihreiksi hiekkalaatikkoyritystä vastaan siten, että täsmäytysluvut vahvistavat sivuvaikutukset, tiedät integraation olevan turvallinen ennen kuin se koskettaa yhtäkään todellista pääkirjaa. Voit luoda hiekkalaatikkoyrityksen ja rajatun testiavaimen muutamassa minuutissa sivulta Aloita ja tarkistaa tarvitsemasi moduulit ominaisuudet -luettelosta.

FAQ

Riittääkö 2xx-vastaus vahvistamaan, että kirjanpitoon kirjoitus onnistui?

Ei. Tilakoodi vahvistaa sen, että palvelin vastasi, ei sitä, että järjestelmässä on tasan yksi dokumentti, yksi numerovaraus ja yksi tasapainotettu pääkirjavienti. Jokaisen muutostestin tulisi seurata vastausta objektin luvulla, sen kirjanpitoaikavaikutuksella ja auditointitietueella. Vaarallisin tilapala on vastakkainen suunta: operaatio, joka tallentui palvelimelle samalla kun asiakas ei koskaan saanut vastausta laisinkaan.

Pitäisikö minun luoda uusi idempotenssiavain, kun pyyntö aikakatkaistaan?

Ei, ja tämä on virhe, joka aiheuttaa eniten tuotannon kaksoiskappaleita. Avain tunnistaa loogisen liiketoimintaoperaation, ei verkkoyritystä. Yritä uudelleen samalla avaimella, ja täsmäytä sitten lukemalla resurssi. Uudelleenyrityskirjasto, joka luo uuden UUID:n yritystä kohti, muuttaa yhden aiotun laskun useiksi erillisiksi kirjoituksiksi.

Mitä tapahtuu, jos käytän idempotenssiavainta uudelleen eri sisällöllä?

Oikein toteutettu rajapinta hylää sen sen sijaan, että se soveltaisi hiljaisesti uutta runkoa. Nordlet palauttaa koodin 422 idempotency_key_reuse ja jättää alkuperäisen tietueen koskemattomaksi. Asiakassovelluksesi tulisi käsitellä tätä ohjelmointivirheenä, joka on korjattava, eikä tilana, joka kiertämiseksi luodaan uusi avain.

Ovatko webhookit korvike luodulle objektille tehtävälle luvulle?

Ei. Webhookin toimitus todistaa alavirran ilmoituksen, ei sitä, että transaktio tallentui odotetulla tavalla, eikä toimitusjärjestys ole taattu. Varmista allekirjoitus raakarungosta, deduplikoi toimitus- tai tapahtumatunnisteen perusteella ja hae nykyinen tila rajapinnasta aina, kun tapahtumajärjestys yksin ei riitä päättämään, mikä muuttui.

Miten testaan kirjaamista lukittuun tilikauteen?

Luo vastaavat dokumentit avoimelle kaudelle ja lukitulle kaudelle, ja varmista, että lukittu tapaus hylätään ilman tilirivejä, kulutettua dokumenttinumeroa, tilasiirtymää ja onnistumisen webhookkia. Aja sitten kilpailutilanneversio: aloita kirjaus avointa kautta vastaan ja lukitse kausi kesken pyynnön. Hyväksytty kirjaus ei saa koskaan päätyä kaudelle, joka lukittiin ennen transaktion valmistumista.

Voinko ajaa suuren volyymin kaksoiskirjaustestejä hiekkalaatikkoyrityksessä?

Kyllä. Hiekkalaatikkoyritys käyttäytyy kuin todellinen yritys, se on merkitty testidataksi ja poistetaan välittömästi säilytysajan umpeuduttua, joten se on oikea paikka tuhoaville ja kahdennustesteille. Hiekkalaatikon käyttö mitataan ja laskutetaan silti todellisen käytön tavoin, joten suunnittele volyymi sen sijaan, että pyörittäisit luuppia loputtomasti.