null atau hilangkan field

Intinya: kirim null saat konsumen harus membedakan "dikosongkan" dari "tidak disentuh" — dalam body PATCH, ketidakhadiran membiarkan field apa adanya dan null eksplisit mengosongkannya — dan pertahankan satu konvensi per field agar response dan penggabungan config tetap stabil.

Perbedaannya

复制{ "nickname": null }

Ada, kosong. Konsumen tahu field itu secara eksplisit dikosongkan.

复制{ }

Tidak ada. Konsumen tidak bisa membedakan "belum pernah diisi" dari "tidak didukung".

Di JavaScript perbedaannya konkret:

复制'nickname' in obj          // false — absent
obj.nickname === null      // true  — present and null
obj.nickname === undefined // true  — both cases

Di mana ini penting

Body PATCH. {"nickname": null} mengosongkan nickname. {} tidak mengubah apa pun. Jika handler memperlakukan "null" dan "hilang" sebagai hal yang sama, pengguna tidak akan pernah bisa mengosongkan field — mereka hanya bisa mengisinya dengan string kosong, yang merupakan hal berbeda.

Implementasikan dengan keberadaan key, bukan nilai:

复制if (Object.hasOwn(patch, 'nickname')) {
  target.nickname = patch.nickname;   // null allowed
}

Penggabungan config. Ketidakhadiran mewarisi default; null menonaktifkannya secara eksplisit. Inilah persis cara nilai Helm dan Kubernetes berperilaku.

Prefill form. null dirender sebagai kosong dan field yang hilang juga begitu, tetapi pengiriman berbeda: tadinya punya nilai, kini dikosongkan → kirim null; tidak pernah diisi → hilangkan. Tanpa perbedaan itu, mengosongkan tampak identik dengan tidak menyentuhnya.

Konvensi

Jaga bentuk response tetap stabil. Daftar yang sebagian itemnya membawa avatar dan sebagian tidak memaksa pemeriksaan 'avatar' in item di setiap call site. avatar: null lebih mudah dikonsumsi.

Tiga hal yang jangan dilakukan

Jangan memakai "" untuk null. Nickname kosong dan nickname yang belum diisi adalah state berbeda di sebagian besar domain.

Jangan memakai 0 atau -1 sebagai sentinel. Nol adalah angka yang sah, dan sentinel itu merusak setiap rata-rata yang Anda hitung.

Jangan mencampur konvensi per endpoint. Dua konvensi berarti dua jalur kode di setiap klien.

FAQ

Apa yang menentukan antara null dan field yang dihilangkan?

Tanyakan apakah konsumen perlu membedakan "secara eksplisit dikosongkan" dari "belum pernah diisi". Dalam body PATCH harus, jadi null mengosongkan dan ketidakhadiran mempertahankan; dalam response, mempertahankan null membuat bentuknya stabil dan tipe klien lebih sederhana.

Bagaimana endpoint PATCH membedakan pengosongan dari pembiaran?

Periksa keberadaan key, bukan nilainya: Object.hasOwn(patch, 'nickname') memberi tahu bahwa field dikirim, dan hanya setelah itu tetapkan nilainya, termasuk null. Jika handler memperlakukan null dan hilang sebagai hal yang sama, pengguna tidak akan pernah bisa mengosongkan field dan hanya bisa jatuh ke string kosong.

Mengapa body response sebaiknya mempertahankan null?

Bentuk yang stabil berarti klien tidak perlu pemeriksaan 'avatar' in item untuk setiap key opsional. Ketika sebagian item daftar membawa avatar dan sebagian menghilangkannya, pemeriksaan itu terduplikasi di setiap call site dan mudah salah.

Bacaan lanjutan

• Struktur apa yang sebaiknya dipakai response API
• JSON Pointer, Patch dan Merge Patch