Sistem berbeda dapat menyembunyikan pola kegagalan yang sama

Pembaruan pesanan tiba sebelum peristiwa pembuatan pesanan. Di tempat lain, peristiwa pembayaran tiba sebelum peristiwa langganan yang lebih awal. Ini dua tim ilustratif yang memakai produk dan isi pesan berbeda. Keduanya tergoda memperbaiki masalah dengan mengurutkan kiriman menurut waktu kedatangan.

Ini bukan laporan insiden salah satu tim. Pertanyaannya adalah apakah kedua kegagalan mempunyai pola yang sama walaupun rincian penyedianya berbeda.

Percakapan yang dipelajari tentang hubungan matematika mengamati bahwa masalah yang tampak berbeda dapat mempunyai bentuk berguna yang sama. Menerapkan gagasan itu pada integrasi perangkat lunak adalah sebuah penyimpulan. Gagasan itu berguna hanya jika bentuk bersama menghasilkan pengujian yang didukung perilaku terdokumentasi tiap sistem.

Hapus nama sistem, lalu kembalikan kontraknya

Jelaskan kasus pertama tanpa nama produk: suatu peristiwa tentang sumber daya dapat tiba setelah perubahan berikutnya pada sumber daya yang sama. Penerima yang menganggap urutan kedatangan sebagai urutan keadaan dapat menimpa informasi baru dengan informasi lama.

Sekarang periksa kontrak nyata. Dokumentasi webhook Shopify menyatakan urutan tidak dijamin, bahkan dalam satu topik, dan memberi contoh pembaruan produk yang dapat tiba sebelum kiriman pembuatan produk. Dokumentasi webhook Stripe juga menyatakan peristiwa tidak dijamin tiba menurut urutan pembuatannya dan menyarankan mengambil objek yang hilang ketika peristiwa awal yang diharapkan belum tiba.

Shopify kiriman tak berurutan header peristiwa Shopify

Pertanyaan bersama Keadaan akhir benar? Uji urutan terbalik

Stripe kiriman tak berurutan ID peristiwa Stripe

Shopify dan Stripe memperingatkan bahwa urutan kiriman peristiwa tidak dijamin. Pertanyaan bersama ialah apakah keadaan akhir benar; pengenal dan pemulihan tiap penyedia tetap perlu diuji sendiri.

Pertanyaan yang dapat dipindahkan adalah: “Jika peristiwa ini tiba sebelum peristiwa terkait, apakah kita masih dapat memperoleh keadaan terkini yang benar?” Jawaban penerapannya tidak otomatis dapat dipindahkan. Shopify mendokumentasikan header seperti X-Shopify-Webhook-Id dan penanda waktu. Stripe menggunakan ID peristiwanya sendiri dan aturan pengambilan objek. Pengenal yang berarti “kiriman” di satu sistem mungkin bermakna lain di sistem berikutnya.

Panduan konektor Brevo kami membahas rincian bidang dan pemetaan yang berbeda. Rincian itu penting bagi integrasi yang bekerja, tetapi bukan perilaku universal API.

Pola bersama adalah sifat yang harus tetap benar

Untuk sinkronisasi pelanggan, sifat itu mungkin: setelah pemrosesan, catatan pelanggan tujuan mencerminkan keadaan terkini dari sumber yang berwenang. Untuk penagihan, mungkin: tindakan yang bergantung pada pembayaran terjadi hanya ketika keadaan pembayaran resmi mengizinkannya. Sifat itu menyebut apa yang harus tetap benar walau peristiwa terlambat, berulang, atau tidak lengkap.

Catat empat hal sebelum memilih perbaikan:

Pertanyaan	Mengapa penting
Identitas apa yang menyebut objek bisnis?	ID peristiwa mungkin mengenali pesan, bukan pelanggan atau pesanan.
Sistem mana yang menguasai keadaan terkini?	Isi pesan mungkin berupa potret keadaan, perubahan, atau hanya penunjuk.
Urutan waktu apa yang dijamin sumber?	Urutan kiriman mungkin berbeda dari urutan perubahan keadaan.
Keadaan akhir apa yang membuktikan keberhasilan?	Menerima peristiwa tidak membuktikan tujuan sudah benar.

Tabel ini alat bantu berpikir, bukan protokol. Jawaban sumber kebenaran bergantung pada alur kerja. Pencarian keadaan terkini mungkin wajib dalam satu sistem tetapi tidak tepat dalam sistem lain. Beberapa peristiwa harus disimpan sebagai fakta historis, bukan diringkas menjadi potret terbaru.

Pakai ulang pengujian, sesuaikan perbaikannya

Pengujian kontrak sederhana dapat mengirim peristiwa terkait dalam urutan terbalik dan memeriksa apakah keadaan akhir di tujuan tetap benar. Pengujian lain dapat mengirim kiriman yang sama dua kali. Pengujian ini mengungkap bentuk risiko. Dokumentasi penyedia lalu menentukan cara mengidentifikasi, memverifikasi, dan memulihkan tiap peristiwa.

Perbedaan itu melindungi tim dari arsitektur salin-tempel. Kunci pencegah duplikasi dari satu API dapat gagal di API lain. Penanda waktu yang kurang presisi mungkin tidak menentukan urutan. Mengambil objek terkini mungkin perlu untuk sinkronisasi keadaan tetapi tidak dapat merekonstruksi setiap peristiwa historis di antaranya. Panduan mengintegrasikan beberapa alat bisnis dimulai dengan memutuskan sistem yang menguasai tiap bidang; tanpa itu, kata “terbaru” tidak mempunyai arti jelas.

Pemindahan pola mempunyai batas. Gejala serupa dapat berasal dari penyebab berbeda: catatan yang hilang mungkin disebabkan kueri tanpa izin, webhook terlambat, pemetaan tidak valid, atau penulisan ditolak. Sebelum menyatakan dua kasus setara, bandingkan kontrak sumber, kontrak tujuan, dan keadaan akhir yang diamati. Jika salah satunya berbeda, pertahankan pertanyaan bersama tetapi ubah pengujiannya.

Metode ini berguna di luar pengiriman peristiwa. Bidang yang diterima API tetapi tidak muncul dalam catatan yang dilihat pengguna menimbulkan pertanyaan umum yang sama pada konektor mana pun: apa yang dibuktikan tanda terima, dan bukti apa menunjukkan keadaan yang dimaksud? Jawabannya mungkin memerlukan pembacaan tujuan, pencarian skema, atau pemeriksaan izin. Pola mengajarkan tim memisahkan transportasi dari makna. Pola itu tidak memberi tahu bidang atau titik akses mana yang harus dipanggil. Pelajarannya lebih sempit daripada resep integrasi universal, tetapi lebih mudah dibawa ke sistem lain karena fakta setempat tetap terlihat.

Pelajaran paling kuat yang dapat dipakai ulang bukan potongan kode penanganan. Pelajarannya adalah pertanyaan yang tetap berlaku di sistem lain dan memudahkan pemeriksaan kontrak setempat.