Stripe recorda la teva sol·licitud quan la resposta desapareix

Què cobreix aquest vídeo

• La idempotència es refereix a l'efecte previst de repetir una operació. L'API v1 de Stripe afegeix un contracte documentat de reproducció de resposta guardada.
• Un reintent de la mateixa acció lògica utilitza la mateixa clau i paràmetres. Persisteix la clau de l'operació entre diferents trucades de l'SDK o reinicis de l'aplicació; una acció genuïnament nova necessita la seva pròpia clau.
• Un cop comença l'execució del punt final, l'API v1 de Stripe guarda l'estat i el cos de la primera sol·licitud, inclosos els errors 500, i retorna aquesta resposta guardada en els reintents.
• Els paràmetres modificats amb la mateixa clau produeixen una discordança. Les fallades de validació i els conflictes d'execució concurrents no guarden cap resultat idempotent per a aquest intent i es poden reintentar.
• Stripe conserva les claus de l'API v1 durant almenys 24 hores i les pot eliminar posteriorment. Limita els reintents de xarxa no resolts a les primeres 24 hores, després atura't i concilia abans de repetir l'operació.
• Un error 500 en memòria cau pot seguir reproduint-se després que es recuperi la connectivitat. L'operació original pot tenir efectes secundaris; utilitza l'objecte rellevant, la sol·licitud del Tauler de control i els webhooks per establir el seu resultat.
• L'API v2 utilitza una semàntica de reproducció diferent. Una clau no estableix un lliurament "exactament una vegada" universal per al correu electrònic, l'inventari i cada operació de la base de dades local.

Transcripció traduïda

Traduït de la narració original en anglès. L'àudio i els subtítols disponibles estan controlats per YouTube.

Un temps d'espera ha cancel·lat el teu pagament?

0:00 Creus que un temps d'espera significa que el teu pagament ha fallat. El servidor pot acabar mentre la resposta desapareix, deixant la teva compra mostrant absolutament res amb confiança. Per què un reintent pot cobrar de nou? Com recorda Stripe un intent? Quan hauries de deixar de reintentar? I tenir en compte un detall desagradable. Un error recordat pot sobreviure al problema de xarxa.

0:17 Tornarem a això. Això és The Daily Diff, sota el capó.

Què identifica una clau d'idempotència?

0:21 La idempotència significa que repetir una operació té el mateix efecte previst que fer-la una vegada. Una clau d'idempotència etiqueta una acció lògica. La versió u de l'API de Stripe reconeix aquesta etiqueta en els reintents i reprodueix una resposta guardada. Imagina comprar un cafè. Stripe completa la teva sol·licitud de pagament, i la resposta es perd en el camí de tornada a casa. El client veu un spinner. El seu banc pot tenir una interpretació més emocionant. Una sol·licitud de creació no protegida pot repetir l'efecte secundari.

Com fa que la mateixa clau un reintent sigui segur?

0:45 Adjunta una clau única abans del primer intent i guarda-la per als reintents. Si la teva aplicació es reinicia, conserva aquesta clau amb l'operació en els teus registres. Per a l'API de la versió u de Stripe, un cop comença l'execució del punt final, l'estat i el cos de la primera sol·licitud es guarden. Envia la mateixa clau i paràmetres de nou, i Stripe retorna la resposta guardada. El cafè es queda al seu lloc mentre el seu rebut viatja de nou.

Què guarda exactament Stripe?

1:07 Aquí teniu la redacció real de Stripe. Els reintents amb la mateixa clau retornen la resposta guardada, inclosos els errors cinc-cents. La documentació fa més feina que el teu ajudant de reintents amb un nom optimista. El client torna a tocar. La teva aplicació decideix si això reprèn la compra pendent o n'inicia una altra. Un cafè genuïnament nou obté una clau nova. Una clau nova per a cada reintent de xarxa desfà la protecció.

1:27 Paràmetres diferents amb la mateixa clau activen una discordança.

Què passa quan la sol·licitud canvia?

1:30 Si els paràmetres fallen la validació, o una altra sol·licitud amb aquesta clau encara s'està executant, Stripe no guarda cap resultat idempotent per a aquest intent. Aquestes sol·licituds es poden reintentar. Una sol·licitud en competència obté un conflicte. Aquestes són les regles de la versió u. La versió dos es comporta de manera diferent. Una capçalera no pot prometre un lliurament "exactament una vegada" a tot el teu sistema. El correu electrònic, l'inventari i la teva base de dades necessiten gestió de fallades.

1:52 La clau protegeix l'operació dins del seu àmbit documentat. Stripe conserva les claus de la versió u durant almenys vint-i-quatre hores i les pot eliminar

Quant de temps és segur reintentar el resultat recordat?

1:59 posteriorment. Una clau eliminada pot executar una nova sol·licitud. Manteniu els reintents no resolts dins del primer dia. Més enllà d'això, atura't i concilia el resultat original. Utilitza el retrocés exponencial i el jitter per donar al servidor un respir. Altrament, els reintents formen una cua fora d'una cafeteria en flames. Les biblioteques de Stripe gestionen els reintents, però comprova els valors predeterminats de la teva biblioteca. Aquest error persistent és la trampa.

Per què un error recordat pot seguir tornant?

2:20 Una resposta cinc-cents en memòria cau continua reproduint-se després que es recuperi la connectivitat. L'operació original pot haver produït efectes secundaris. Resoldre el seu resultat utilitzant objectes, el Tauler de control i els webhooks. Una clau nova pot repetir l'acció. Si preferiu llegir això que sentir-me dir-ho, el "diff" arriba a la vostra safata d'entrada cada matí, gratuït a the daily diff dot dev, enllaç a continuació.

Enviaria un botó de reintent amb aquest contracte?

2:39 Veredicte, sota el capó. SHIP IT. Jo enviaria claus estables amb reintents limitats i conciliació, perquè els clients obtinguin cafè sense finançar la vostra educació en sistemes distribuïts. I aquesta és la diferència d'avui. Sóc en Niko d'Axrisi. Fusió amb responsabilitat.

Fonts

1. Idempotent requestsStripe Docs
2. Designing robust and predictable APIs with idempotencyStripe Engineering — Brandur Leach
3. Advanced error handlingStripe Docs
4. HTTP Semantics — RFC 9110 §9.2.2 Idempotent MethodsIETF / RFC Editor