Duplikasi pesanan saat bekerja dengan API: penyebab dan perlindungan

Mengapa duplikasi muncul setelah satu tindakan

Pemilik panel bisa menekan tombol satu kali dan melihat beberapa pesanan identik: untuk pengikut, penayangan, reaksi, atau layanan lain. Biasanya masalahnya bukan pada klik itu sendiri, melainkan pada rantai antara klien, API, basis data, dan penyedia.

Dari sudut pandang server, "satu permintaan" tidak selalu berarti satu. Klien mungkin tidak menerima respons, mengirim ulang, sementara operasi pertama sudah sempat tersimpan. Terkadang pesanan dibuat satu kali di basis data panel, tetapi terkirim dua kali ke penyedia. Ini skenario yang berbeda, dan cara memperbaikinya juga berbeda.

Timeout bukan berarti pesanan tidak dibuat

Penyebab paling umum — klien menunggu respons dalam waktu terbatas. Server menerima permintaan, membuat pesanan, tetapi merespons lebih lambat dari timeout yang ditetapkan. Klien menganggap operasi gagal dan mengirimnya ulang.

Akibatnya pesanan pertama sudah ada di basis data, dan permintaan kedua membuat satu lagi. Ini terutama sering terjadi saat respons API eksternal lambat, antrean kelebihan beban, atau koneksi antar layanan tidak stabil.

Timeout hanya menunjukkan tidak adanya respons, bukan tidak adanya pemrosesan permintaan.

Pengulangan otomatis di sisi klien

Pustaka untuk permintaan HTTP, tugas latar belakang, dan layanan integrasi sering mengulang permintaan secara otomatis. Pemicunya bisa berupa kesalahan koneksi, kode respons server, koneksi terputus, atau respons yang terlalu lama.

Pengulangan itu sendiri bermanfaat: mengurangi jumlah pesanan yang hilang saat gangguan sementara. Kekurangan pendekatan ini — tanpa perlindungan dari pemrosesan ulang, ia mengubah ketidakstabilan jaringan apa pun menjadi duplikasi.

• pengulangan bisa dipicu dalam kode situs atau bot;
• tugas bisa dimulai ulang oleh antrean;
• permintaan bisa diulang oleh proxy atau modul integrasi;
• operator bisa mengirim ulang pesanan secara manual setelah kesalahan.

Permintaan berulang datang sebelum respons pertama

Terkadang dua permintaan identik benar-benar mencapai API hampir bersamaan. Misalnya, pengguna mengirim formulir dua kali, frontend tidak memblokir tombol, atau tugas latar belakang dimulai ulang sebelum yang pertama selesai.

Jika handler terlebih dahulu memeriksa keberadaan pesanan, lalu membuatnya, dua operasi paralel bisa lolos pemeriksaan secara bersamaan. Masing-masing akan melihat bahwa pesanan belum ada, dan masing-masing menambahkan catatan baru.

Situasi ini disebut race condition. Pemeriksaan awal sederhana dalam kode tidak sepenuhnya melindungi dari ini. Kekurangan pemeriksaan tanpa batasan di tingkat basis data — ia rusak di bawah beban paralel.

Pesanan tercatat, tetapi respons API hilang

Permintaan melewati beberapa tahap: server menerima data, membuat catatan, menempatkan tugas dalam antrean, mengirim respons. Kegagalan bisa terjadi di antara tahap mana pun. Misalnya, basis data sudah mengonfirmasi pembuatan pesanan, tetapi koneksi terputus sebelum respons dikirim ke klien.

Klien tidak tahu apakah pesanan diterima, dan mengulang operasi. API tanpa mekanisme pemeriksaan terpisah menganggap permintaan sebagai yang baru. Dalam log, ini sering terlihat seolah-olah layanan membuat dua pesanan "sendiri", padahal ia menerima dua permintaan masuk.

Kunci idempotensi untuk membuat pesanan

Untuk operasi pembuatan, diperlukan kunci idempotensi unik. Klien menghasilkannya sebelum pengiriman pertama dan mengirimkannya bersama parameter pesanan. Saat pengulangan karena timeout atau kesalahan, kunci yang sama digunakan.

API menyimpan kunci bersama hasil pemrosesan. Jika datang permintaan dengan kunci yang sudah dikenal, server tidak membuat pesanan baru, melainkan mengembalikan hasil permintaan pertama: pengenal pesanan, statusnya, atau kesalahan yang terbentuk sebelumnya.

Satu kunci harus sesuai dengan satu operasi bisnis, bukan satu koneksi HTTP.

Kekurangan metode ini — kunci perlu disimpan, dibersihkan sesuai aturan, dan diperiksa di sisi API. Jika kunci baru dihasilkan pada setiap pengulangan, perlindungan tidak akan berfungsi. Jika satu kunci digunakan untuk pesanan berbeda, sebagian operasi baru akan keliru ditolak.

Keunikan harus dikendalikan oleh basis data

Idempotensi sebaiknya dilengkapi dengan batasan keunikan di basis data. Untuk ini dipilih kombinasi yang secara unik mendeskripsikan pesanan: pengenal internal klien, kunci idempotensi, jenis layanan, dan bidang lain yang diperlukan.

Basis data harus menolak catatan kedua, bahkan jika dua handler mencapai pembuatan secara bersamaan. Setelah konflik, API mengembalikan pesanan yang sudah ada, bukan kesalahan tanpa penjelasan.

Kekurangan batasan unik yang ketat — tidak bisa dibangun hanya berdasarkan tautan atau username. Klien bisa dengan sengaja memesan satu layanan pada kanal yang sama beberapa kali. Batasan yang terlalu luas akan memblokir pembelian ulang yang normal.

Antrean bisa mengirimkan tugas lebih dari satu kali

Antrean tugas sering bekerja dengan prinsip "pengiriman setidaknya satu kali". Jika worker memproses tugas tetapi tidak sempat mengonfirmasi penyelesaiannya, antrean bisa mengirimkan tugas yang sama lagi ke worker lain.

Bagi antrean ini adalah cara normal untuk tidak kehilangan tugas. Bagi pembuatan pesanan tanpa idempotensi — sumber duplikasi. Pengenal tugas atau kunci operasi terpisah harus diteruskan hingga ke handler akhir, termasuk modul pengiriman pesanan ke penyedia.

Kekurangan menonaktifkan pengiriman ulang — jika worker gagal, sebagian pesanan bisa hilang. Lebih aman menerima kemungkinan pengulangan dan membuat handler tahan terhadapnya.

Duplikasi muncul antara panel dan penyedia

Pesanan internal bisa dibuat satu kali, tetapi permintaan ke API eksternal dikirim dua kali. Penyebabnya sama: panel tidak menerima respons dari penyedia dan memutuskan untuk mengirim ulang. Jika penyedia sempat menerima permintaan pertama, di sisinya akan muncul dua permintaan identik.

Diperlukan keterkaitan terpisah antara pesanan internal dan eksternal: pengenal pengiriman, kunci idempotensi, atau respons penyedia yang tersimpan. Tidak bisa dianggap bahwa perlindungan di pintu masuk panel sendiri secara otomatis akan melindungi panggilan keluar.

Kekurangan pencocokan dengan API pihak ketiga — tidak setiap penyedia mendukung pencarian berdasarkan kunci eksternal. Maka dari itu, percobaan pengiriman harus dicatat dan status yang tidak pasti dianalisis secara terpisah.

Webhook tidak boleh membuat pesanan baru

Webhook memberi tahu tentang perubahan: pesanan diterima, dimulai, selesai, dibatalkan, atau memerlukan pemeriksaan. Kesalahan terjadi ketika handler webhook menganggap notifikasi sebagai perintah untuk membuat pesanan baru.

Webhook yang sama bisa datang berulang kali. Pengirim mengulang pengiriman jika tidak menerima konfirmasi, dan notifikasi terkadang datang tidak berurutan. Handler harus menemukan pesanan yang ada berdasarkan pengenal eksternal dan memperbarui status.

Kekurangan pemrosesan webhook hanya berdasarkan waktu penerimaan — notifikasi yang terlambat bisa menimpa status terkini dengan yang usang. Diperlukan pengenal peristiwa, versi status, atau aturan transisi yang jelas.

Catatan apa yang membantu menemukan sumber duplikasi

Untuk investigasi, tidak cukup hanya melihat dua nomor pesanan. Diperlukan data tentang setiap tahap pemrosesan: waktu permintaan, kunci idempotensi, pengenal klien, parameter pesanan, nomor tugas latar belakang, respons API eksternal, dan percobaan pengiriman ulang.

• cocokkan duplikasi berdasarkan kunci operasi, bukan hanya berdasarkan tautan;
• periksa apakah ada permintaan identik dalam log API masuk;
• lihat apakah tugas diulang dalam antrean;
• pisahkan pembuatan pesanan internal dari pengiriman ke penyedia;
• simpan pengenal eksternal permintaan segera setelah menerima respons.

Kekurangan log yang terlalu singkat — sumber masalah hilang sebelum sempat dianalisis. Kekurangan logging berlebihan — catatan bisa memuat token, data pribadi, dan bidang sensitif lainnya, sehingga perlu disamarkan.

Cara menangani hasil permintaan yang tidak pasti

Setelah timeout, tidak boleh langsung membuat pesanan ulang dengan data baru. Pertama, API harus memeriksa operasi berdasarkan kunci idempotensi atau pengenal klien. Jika pesanan ditemukan, statusnya saat ini dikembalikan. Jika pemrosesan masih berlangsung, klien menerima status menunggu.

1. Buat kunci operasi sebelum permintaan pertama.
2. Kirim kunci yang sama pada setiap pengulangan.
3. Simpan kunci dan pesanan dalam satu operasi basis data yang terlindungi.
4. Teruskan pengenal operasi ke antrean dan API eksternal.
5. Kembalikan pesanan yang dibuat sebelumnya saat ada permintaan berulang.

Skenario seperti ini memerlukan penyesuaian API dan integrasi klien. Kekurangannya — debugging lebih sulit dan lebih banyak status pesanan, tetapi pengiriman ulang permintaan tidak lagi otomatis berarti pembelian ulang.