𝟵 𝗔𝗣𝗜 𝗖𝗵𝗮𝗻𝗴𝗲𝘀 𝗧𝗵𝗮𝘁 𝗕𝗿𝗲𝗮𝗸 𝗬𝗼𝘂𝗿 𝗔𝗽𝗽

𝟵 𝗣𝗲𝗿𝘂𝗯𝗮𝗵𝗮𝗻 𝗔𝗣𝗜 𝗬𝗮𝗻𝗴 𝗠𝗲𝗿𝗼𝘀𝗮𝗸𝗸𝗮𝗻 𝗔𝗽𝗹𝗶𝗸𝗮𝘀𝗶 𝗔𝗻𝗱𝗮

"Kami tidak merosakkan apa-apa. Kami cuma mengemas kini respons tersebut."

Kata-kata itu sering menyebabkan kegagalan sistem. Aplikasi mudah alih gagal berfungsi. Integrasi rakan kongsi memulangkan data yang tidak bermakna. Anda telah mengubah struktur data yang bergantung kepada pihak lain.

Perubahan berbahaya selalunya kelihatan seperti proses mengemas. Ia melepasi semakan kod dan ujian. Kerosakan berlaku dalam kod yang anda tidak dapat lihat.

Berikut adalah sembilan perubahan yang terasa selamat tetapi sebenarnya tidak.

• Menamakan semula medan (fields) Menukar userId kepada user_id demi konsistensi akan merosakkan klien. Penamaan semula adalah satu proses pemadaman dan penambahan. Bahagian pemadaman itulah yang merosakkan sistem pengguna. Langkah selamat: Tambah medan baharu. Kekalkan medan lama. Tandakan ia sebagai usang (deprecate). Padamkan ia jauh lebih lewat.

• Menjadikan medan sebagai pilihan (optional) Sesuatu medan dahulunya sentiasa ada. Sekarang, ia kadangkala bernilai null. Kod klien akan mengalami kegagalan (crash) apabila cuba memprosesnya. Langkah selamat: Anggap "sentiasa ada" sebagai satu janji. Jika sesuatu medan menjadi pilihan, gunakan versi baharu.

• Membuang medan yang tidak digunakan Anda tidak dapat melihat bagaimana pengguna data anda menggunakannya. "Tidak digunakan" hanya bermaksud tidak digunakan oleh anda. Langkah selamat: Ukur penggunaan medan dalam persekitaran produksi sebelum anda membuang apa-apa.

• Mengecilkan jenis input Menukar string kepada enum atau nombor kepada integer akan merosakkan permintaan (requests). Meluaskan input adalah selamat. Mengecilkannya adalah perubahan yang merosakkan. Langkah selamat: Hanya longgarkan input yang anda terima. Mengetatkan input memerlukan versi baharu.

• Menukar nilai lalai (default) Menukar nilai lalai daripada false kepada true mengubah tingkah laku tanpa sebarang ralat. Ini merosakkan logik secara senyap. Langkah selamat: Anggap perubahan nilai lalai sebagai perubahan yang merosakkan.

• Menambah medan wajib (required) Menambah tenantId dan menjadikannya wajib akan merosakkan setiap klien sedia ada. Mereka akan menerima ralat 400. Langkah selamat: Medan baharu mestilah bersifat pilihan atau gunakan versi baharu.

• Menukar format ralat Menukar 400 kepada 422 atau menukar kandungan (body) ralat akan merosakkan kod pengendalian ralat. Langkah selamat: Format ralat adalah kontrak. Gunakan versi untuknya seperti perkara lain.

• Mengubah suai nilai enum Menamakan semula "active" kepada "ACTIVE" akan merosakkan klien. Membuang sesuatu nilai akan merosakkan klien yang mempunyai logik yang ketat. Langkah selamat: Nilai enum adalah kekal. Tambah ia dengan berhati-hati. Jangan sesekali menamakan semula atau membuangnya tanpa versi utama (major version).

• Mengubah maksud data Menukar tarikh daripada saat Unix kepada ISO-8601 atau menukar paginasi daripada offset kepada cursor akan merosakkan segalanya. Perbezaan skema (schema diff) mungkin tidak dapat mengesan perkara ini. Langkah selamat: Tetapkan format secara eksplisit. Bandingkan payload sebenar, bukan sekadar spesifikasi.

Jangan bergantung pada gerak hati. Bandingkan setiap perubahan dengan kontrak pengeluaran dalam CI anda. Manusia mungkin terlepas pandang medan yang telah ditukar namanya. Alat 'diff' tidak akan terlepas.

Sumber: https://dev.to/deepaksatyam/9-api-changes-that-look-backwards-compatible-but-arent-1bk0