Gesaan dan skop
Penyedia ingin membuang /v1/items selepas satu tempoh masa migrasi, tetapi klien dimiliki oleh pasukan yang berbeza dan sesetengahnya tidak aktif (dormant). Andaikan penyedia boleh memerhatikan permintaan berdasarkan identiti klien dan boleh menjalankan /v2/items secara selari. Pelan ini mesti membezakan pengumuman penurunan taraf daripada tarikh pembuangan, mengekalkan sandaran yang selamat, dan mengelak daripada menganggap bahawa pengepala sahaja mampu memindahkan klien.
Perkara yang diuji oleh penemu duga
- Memisahkan isyarat protokol, dokumentasi, inventori klien, dan penguatkuasaan.
- Mereka bentuk keserasian aditif dan pintu gerbang migrasi (migration gate) yang boleh diukur.
- Mengendalikan klien yang tidak diketahui, integrasi yang telah lama wujud, dan pengunduran kecemasan.
- Memilih kod status dan pengepala tanpa mereka cipta semantik di luar piawaian.
Soalan penjelasan untuk ditanya
Tanya sama ada klien menghantar identiti yang stabil, sama ada /v2 boleh bersifat aditif, tempoh sokongan minimum, keperluan notis kontrak, dan sama ada titik akhir lama boleh dijadikan baca sahaja sebelum dibuang. Sekiranya identiti tiada, bukti migrasi mesti diperoleh daripada kelayakan, metadata rangkaian, atau pendaftaran eksplisit dan bukannya daripada tekaan ejen pengguna.
Jawapan 30 saat
Saya akan menginventorikan pemanggil, menerbitkan panduan migrasi berversi, melancarkan /v2 secara aditif, dan mengukur trafik bagi setiap klien serta pariti ralat. Tandakan /v1 dengan isyarat Deprecation yang dipiawaikan dan tarikh Sunset, sambil menyediakan papan pemuka dan notis langsung untuk pemilik yang diketahui. Kekalkan laluan lama semasa tempoh masa yang dinyatakan, kuat kuasakan hanya selepas melepasi pintu gerbang bukti, dan kembalikan respons terminal yang didokumentasikan dengan pautan migrasi. Feature flag dan penghalaan boleh balik menyediakan pengunduran jika klien kritikal terjejas.
Huraian mendalam langkah demi langkah
1. Wujudkan keserasian dan bukti
Tentukan perbezaan pada peringkat medan, tingkah laku lalai, penomboran halaman (pagination), ralat, dan perubahan pengesahan. Jalankan ujian kontrak terhadap kedua-dua versi dan bandingkan respons yang representatif. Tag metrik mengikut klien, versi, titik akhir, status, dan keadaan migrasi; jangan gunakan trafik agregat semata-mata kerana klien bervolume rendah mungkin penting untuk perniagaan.
2. Isyaratkan penurunan taraf secara tepat
Pengepala respons Deprecation menyampaikan bahawa sesuatu sumber telah diturunkan taraf; pengepala Sunset menyampaikan tarikh yang dirancang selepas itu ia mungkin tidak lagi tersedia. Ini hanyalah isyarat, bukan jaminan bahawa setiap klien memahaminya. Ulangi tarikh tersebut dalam dokumentasi dan pemberitahuan pemilik, dan sertakan rujukan migrasi yang stabil dalam badan respons atau hubungan pautan yang ditakrifkan oleh kontrak API.
3. Migrasi dan kuat kuasa secara berperingkat
Mulakan dengan amaran dan papan pemuka, kemudian wajibkan pengecualian eksplisit untuk klien yang terlepas sasaran. Tawarkan perbandingan bayangan (shadow comparison) atau trafik pilihan serta (opt-in) sebelum menukar tetapan lalai. Di pintu gerbang penguatkuasaan, tolak hanya operasi lama yang selamat untuk dimansuhkan, kembalikan ralat yang boleh dibaca mesin, dan kekalkan saluran sokongan. Keserasian baca sahaja boleh dilanjutkan lebih lama daripada keserasian mutasi apabila risikonya berbeza.
4. Pastikan pengunduran dan tadbir urus kekal praktikal
Simpan tarikh sunset, pemilik, sebab pengecualian, dan kelulusan dalam rekod perubahan. Tetapkan amaran untuk perbezaan ralat pascamigrasi dan permintaan daripada klien yang tidak diketahui. Hantar laluan lama melalui feature flag supaya pengunduran merupakan perubahan konfigurasi, bukan triển khai (deploy) semula kod. Selepas pembuangan, kekalkan telemetri dan respons tombstone cukup lama untuk menerangkan kegagalan tanpa mendedahkan rahsia.
Contoh jawapan yang mantap
Saya akan menginventorikan 10,000 pemanggil dan menentukan perbezaan kontrak yang tepat antara /v1 dan /v2. Kedua-dua versi berjalan secara selari dengan metrik per klien dan ujian kontrak. Respons /v1 membawa isyarat Deprecation dan Sunset, manakala dokumentasi dan notis pemilik mengulangi tarikh serta langkah migrasi. Penyedia bergerak melalui peringkat amaran, opt-in, lalai kepada v2, dan penguatkuasaan, dengan pengecualian eksplisit dan ralat terminal yang boleh dibaca mesin. Feature flag mengekalkan keupayaan pengunduran; pintu gerbang sunset adalah berdasarkan bukti pada peringkat klien, bukan peratusan trafik agregat.
Kesilapan lazim
- Menganggap pengepala menjalankan migrasi → banyak klien mengabaikannya → padankan isyarat standard dengan penemuan pemilik dan panduan.
- Menetapkan tarikh tanpa inventori → klien yang tidak aktif tetapi kritikal gagal secara tidak dijangka → wajibkan identiti klien dan semakan pengecualian.
- Membandingkan kadar ralat agregat sahaja → gangguan pada satu penyewa hilang dalam purata → pantau pariti dan volum setiap klien.
- Membuang sejurus selepas
/v2dilancarkan → klien tidak mempunyai bukti keserasian → jalankan peringkat selari atau opt-in terlebih dahulu. - Menjadikan pengunduran sebagai triển khai (deploy) semula → pemulihan menjadi perlahan semasa gangguan perkhidmatan → halakan versi di sebalik flag yang boleh diterbalikkan.
- Mengembalikan 404 yang tidak didokumentasikan semasa sunset → automasi tidak dapat membezakan pembuangan daripada kesilapan menaip → terbitkan ralat terminal yang stabil dan rujukan migrasi.
Soalan susulan dan respons
Klien tidak pernah menghantar pengepala pengenalan. Apakah pintu gerbang migrasinya?
Gunakan kelayakan, akaun, rangkaian, atau identiti pendaftaran yang telah sedia ada pada penyedia. Jika tiada satu pun yang boleh dipercayai, pastikan titik akhir tersedia lebih lama dan wajibkan pendaftaran eksplisit sebelum penguatkuasaan.
Bolehkah tarikh Sunset diubah?
Boleh, jika rekod perubahan, dokumentasi, pengepala, dan notis pemilik dikemas kini bersama-sama. Anggap tarikh tersebut sebagai komitmen tadbir urus dan tetapkan amaran untuk klien yang masih bergantung pada laluan lama.
Bagaimana jika /v2 adalah betul tetapi lebih perlahan untuk satu klien?
Bandingkan kependaman (latency) dan belanjawan ralat klien secara berasingan, kemudian optimumkan atau berikan pengecualian terhad masa. Jangan lanjutkan tempoh masa sunset bagi keseluruhan populasi tanpa bukti bahawa isu tersebut adalah sistemik.
Bagaimanakah anda memansuhkan titik akhir mutasi secara selamat?
Hentikan penulisan baharu selepas melepasi pintu gerbang bukti, kekalkan akses baca jika boleh, dan pastikan percubaan semula mengembalikan ralat terminal yang deterministik. Sahkan bahawa baris gilir hiliran (downstream queues) dan rekod audit tidak lagi bergantung pada mutasi lama sebelum pembuangan.