Alat pembangun · UUID penjana
Kunci Idempotensi: Menggunakan UUID Dijana Pelanggan untuk Menjadikan Percubaan Semula Selamat
· Mengapa ia penting
uuid kriptografi pelayar-apis
Tamat masa pada permintaan pembayaran menyebabkan anda tidak pasti sama ada ia berjaya. Kekunci Idempotensi membolehkan anda mencuba semula dengan selamat, dan CSPRNG yang dihasilkan UUID ialah kunci semula jadi. Siaran ini menerangkan corak hujung ke hujung.
Tamat masa yang mungkin telah mengecaj pelanggan dua kali — kunci mati pucuk mod kegagalan wujud untuk diperbaiki
Tamat masa semasa permintaan pembayaran mewujudkan ketidakpastian yang tulen untuk pelanggan dan sistem. Pelanggan HTTP anda berputus asa menunggu jawapan, tetapi pelayan pembayaran mungkin telah memproses transaksi sebelum sambungan ditutup atau tamat masa. Jika anda mencuba semula permintaan yang sama, anda mungkin mengenakan bayaran dua kali kepada pelanggan. Jika anda tidak mencuba semula, pembayaran tidak akan selesai. Sistem pembayaran gagal menjadi jalan tengah yang tidak berpuas hati: wang pelanggan mungkin hilang, mungkin tiba esok, mungkin tersekat dalam baris gilir pemprosesan, atau mungkin tidak meninggalkan akaun sama sekali. Kekaburan ini tidak boleh diterima untuk sistem kewangan.
Cara kunci mati pucuk berfungsi — pelayan menyimpan respons pertama di bawah kunci dan memainkannya semula untuk ulangan
Kekunci Idempotensi menyelesaikan masalah ini secara elegan dengan menjadikan percubaan semula selamat dan deterministik. Pelanggan menjana kunci unik untuk setiap niat—pembayaran, pemindahan, caj—dan memasukkannya dalam setiap permintaan. Pelayan memproses pembayaran, menyimpan jawapan di bawah kunci itu dan menyimpan kedua-dua kunci dan hasil. Jika kunci yang sama tiba sekali lagi dalam tetingkap pengekalan, pelayan memainkan semula respons yang dicache tanpa memproses pembayaran sekali lagi. Pelanggan boleh mencuba semula dengan yakin mengetahui bahawa kunci yang sama akan sentiasa menghasilkan hasil yang sama, tidak kira berapa kali ia dihantar. Corak ini menghapuskan kekaburan dan menjadikan logik cuba semula selamat.
Hasilkan sebelum percubaan pertama — mengapa kunci mesti wujud sebelum permintaan keluar dan digunakan semula secara verbatim semasa mencuba semula
Coraknya lebih tua daripada moden HTTP spesifikasi tetapi mendapat keutamaan dalam pembayaran selepas kerugian kewangan yang meluas dan aduan pelanggan daripada caj pendua. Setiap pembayaran API dan banyak API perkhidmatan web kini menyokong kunci idempotensi. A CSPRNG-dijana UUID adalah pilihan semula jadi untuk kunci kerana ia tidak dapat dielakkan, unik tanpa sebarang penyelarasan antara pelanggan dan tidak memerlukan peruntukan bahagian pelayan atau pihak berkuasa pusat. Pelanggan menjananya sebelum percubaan pertama, menggunakannya semula secara verbatim pada setiap percubaan semula dan menerima respons yang sama setiap kali. Tiada keadaan sebelah pelayan diperlukan untuk menyelaraskan penjanaan kunci.
Mengapa UUID rawak dan bukan pembilang atau cincang muatan — keunikan tanpa penyelarasan dan tiada penggunaan semula secara tidak sengaja merentas niat
Kunci mesti wujud sebelum permintaan meninggalkan pelanggan kerana menjananya pada percubaan semula sudah terlambat untuk memastikan mati pucuk. Jika permintaan pertama berjaya dan mengecaj pelanggan, menjana kunci baharu semasa mencuba semula akan menutup masalah dan mengecas semula. Pelanggan mesti komited kepada kunci sebelum percubaan pertama, menyimpannya dalam memori atau storan berterusan, dan menggunakan semula kunci yang sama jika tamat masa atau cuba semula menjadi perlu. Untuk ujian API manual, penjana ToolAcre menghasilkan kekunci yang boleh anda tampalkan ke dalam curl atau klien REST, salin dan guna semula merentas berbilang permintaan untuk menguji tingkah laku idempotency.
Skop dan seumur hidup — kunci setiap operasi, setiap akaun, dan berapa lama pelayan harus mengingatinya
Mengapakah UUID dan bukannya cincang atau kaunter berjujukan untuk kunci mati pucuk? Cincang muatan permintaan nampaknya intuitif—muatan yang sama mendapat cincang yang sama dan oleh itu kunci yang sama. Tetapi cincang adalah lemah untuk kes penggunaan ini kerana dua permintaan yang hampir sama dengan jumlah yang berbeza, penerima yang berbeza atau parameter yang berbeza menghasilkan cincang yang berbeza sama sekali dan dengan itu menjana caj berasingan, yang betul tetapi tidak menyediakan semua perlindungan yang diperlukan. Kaunter berjujukan memerlukan penyelarasan dan keadaan teragih: jika dua pelanggan kedua-duanya menjana kunci berasaskan balas pada infrastruktur anda, kaunter mereka mungkin berlanggar. A UUID tidak memerlukan kuasa pusat, tidak boleh dielakkan dan sangat tidak mungkin bertembung secara kebetulan di seluruh Internet sepanjang masa.
Contoh yang berjaya — urutan cuba semula dengan kunci yang sama, menunjukkan perkara yang dihantar oleh pelanggan dan perkara yang dikembalikan oleh pelayan setiap kali
Pelaksanaan bahagian pelayan menyimpan respons di bawah kunci dan mengembalikan respons yang dicache pada ulangan. Kerumitannya adalah dalam menentukan soalan operasi praktikal: tempoh pengekalan berapa lama untuk mengingati kunci, saiz cache berapa banyak kunci yang perlu diingat, mengunci cara menghalang dua permintaan serentak dengan kunci yang sama daripada memproses pembayaran dua kali dan pembersihan apabila melupakan kunci. Ini adalah soalan storan dan kebolehpercayaan di luar skop penjana UUID. Tugas pelanggan adalah untuk menjana kunci yang baik dan menggunakannya semula apabila cuba semula; tugas pelayan adalah untuk melaksanakan cache dengan betul dan tahan lama.
Perkara ini tidak meliputi — storan dan penguncian sisi pelayan yang diperlukan untuk melaksanakan corak, yang merupakan reka bentuk yang berasingan
Contoh yang dikerjakan menunjukkan urutan biasa dalam amalan. Aplikasi mudah alih perlu memindahkan wang kepada rakan menggunakan API yang menyokong idempotensi. Sebelum menghantar permintaan, apl menjana a UUID menggunakan perpustakaan crypto tempatannya atau mengambil satu daripada ToolAcre penjana untuk tujuan ujian: 3fa85f64-5717-4562-b3fc-2c963f66afa6. Aplikasi menghantar a POST meminta kepada /transfers dengan a JSON badan dan an HTTP header Idepotency-Key: 3fa85f64-5717-4562-b3fc-2c963f66afa6. Pelayan memproses pemindahan, menyimpan 3fa85f64-5717-4562-b3fc-2c963f66afa6 → {status: "kejayaan", transferId: "xfer-12345"} dalam cachenya dan mengembalikan a 200 tindak balas dengan hasilnya.
Bawa pulang: satu niat, satu kunci — penjana ToolAcre memberi anda CSPRNG yang disokong UUID untuk digunakan sebagai kunci semasa menguji penyepaduan dengan tangan
Rangkaian tamat masa dan pelanggan tidak melihat respons daripada percubaan pertama. Apl mencuba semula permintaan yang sama dengan kunci idempotency yang sama tanpa menghasilkan UUID baharu. Pelayan mengecam kunci dalam cachenya, mencari respons yang dicache dan segera mengembalikan {status: "success", transferId: "xfer-12345"} tanpa memproses pemindahan baharu dan tanpa mengecaj pelanggan sekali lagi. Operasi adalah idempoten: mencuba semula menghasilkan hasil yang boleh diperhatikan yang sama setiap kali. Untuk ujian yang berjaya, penjana ToolAcre boleh memberikan kunci; jana UUID, masukkannya dalam pengepala, amati respons dan hantar semula dengan kunci yang sama untuk mengesahkan pelayan melaksanakan caching dengan betul.