Alat pembangun · JSON pemformat & pengesah
Mengapa JSON tidak mempunyai ulasan: keputusan reka bentuk dan penyelesaiannya
· Latar belakang
json piawaian pengesahan
Ulasan telah dialih keluar daripada JSON dengan sengaja. Siaran ini menerangkan alasan, mengapa setiap percubaan untuk menambahkannya kembali mencipta format baharu, dan apakah pilihan anda apabila fail konfigurasi benar-benar memerlukan nota.
Komen yang memecahkan binaan
Komen yang memecahkan binaan — nota berguna ditambahkan pada konfigurasi JSON dan penghurai yang berhenti pada garis miring pertama. Pengarang mungkin telah menyalin corak daripada JavaScript atau editor JSONC-sedar, manakala alat pengerahan menggunakan JSON yang ketat. Penyerlahan sintaks boleh menjadikan nota kelihatan sah walaupun pengguna menolak penanda ulasan pertama.
Komen ditolak kerana slash bukan token JSON di mana pengimbas menjangkakan nilai atau ahli. ToolAcre tidak melucutkan sintaks JSONC atau JSON5 secara senyap. Sifat berbentuk ulasan konvensional ialah data biasa dan mungkin melanggar skema aplikasi walaupun sintaks JSON yang ketat menerimanya. Dakwaan sejarah yang tidak disokong tentang reka bentuk JSON diketepikan atau diperbetulkan dan bukannya dibentangkan sebagai fakta yang telah ditetapkan tanpa bukti utama atau sumber piawaian yang boleh dikesan tersedia untuk pengesahan.
Alasan Crockford untuk mengalih keluar komen
Alasan Crockford untuk mengalih keluar ulasan — penjelasan kemudian mengatakan ulasan telah digunakan untuk membawa arahan penghuraian, menjejaskan kesalingoperasian antara pelaksanaan. Akibat reka bentuk yang berkaitan ialah standard JSON tidak mempunyai token ulasan. Tuntutan tentang motivasi peribadi, kronologi tepat atau tindak balas industri universal memerlukan sumber sejarah yang tidak dibekalkan oleh repositori ini.
Sehubungan itu, tuntutan sejarah yang tidak disokong akan ditinggalkan atau diperbetulkan di sini. Standard yang boleh diperhatikan dan tingkah laku penghurai adalah mencukupi: JSON yang ketat menukar data melalui enam jenis nilai dan dua bekas, tanpa saluran anotasi. Kekangan itu menghalang seorang penerima daripada memberikan makna operasi kepada teks yang diabaikan oleh penerima lain, tetapi ia juga menjadikan JSON kurang selesa untuk konfigurasi yang diselenggara dengan tangan.
Apa yang dilaporkan oleh pengesah tentang ulasan
Perkara yang dilaporkan oleh pengesah tentang ulasan — `//` dan `/* */` tiada dalam tatabahasa, jadi ralat itu tiba pada garis miring pertama dengan baris dan lajur. Pengimbas tidak membantah perkataan dalam nota. Ia tidak boleh memulakan sebarang nilai JSON, nama ahli atau pemisah yang sah dengan `/` pada kedudukan itu.
Untuk `{"port":8080, // local only "secure":false}`, koma itu sah dan token sah seterusnya sepatutnya nama sifat dalam tanda petik atau pendakap penutup. Garis miring melanggar jangkaan tersebut. Mengalih keluar catatan sahaja meninggalkan pemisah yang sah dan ahli seterusnya; memadam tanda baca berdekatan boleh menghasilkan ralat kedua. Sahkan semula output ketat yang tepat selepas setiap suntingan.
Format yang menambah ulasan kembali
Format yang menambahkan ulasan kembali — JSONC membenarkan ulasan di sekitar sintaks JSON yang biasa, manakala JSON5 menambahkan kemudahan seperti kunci pengecam tidak disebut dan koma di belakang. Hjson menekankan penyuntingan manusia dengan sintaks santai tambahan. YAML mempunyai tatabahasa sendiri, termasuk ulasan, dan bukan sekadar JSON dengan anotasi ditambahkan.
Penerimaan adalah khusus pengguna: tetapan editor dan konfigurasi TypeScript mungkin menggunakan penghurai tahan komen, manakala manifes pakej atau badan API boleh memerlukan JSON yang ketat. Kubernetes biasanya menggunakan YAML atau JSON mengikut perkakasannya. Namakan format sebenar dalam dokumentasi dan pengendalian fail; menanggalkan sambungan atau memanggil setiap notasi objek "JSON" menyembunyikan sempadan keserasian.
Penyelesaian dalam ketat JSON
Penyelesaian dalam JSON yang ketat — kunci `_comment` atau `//` konvensional menyimpan penjelasan sebagai ahli rentetan biasa. Ia bertahan dalam penghuraian yang ketat kerana kedua-dua kunci dan nilai menggunakan token standard. Berbilang nota memerlukan kunci unik atau tatasusunan, kerana nama ahli pendua tidak boleh dipercayai dan mungkin diruntuhkan oleh penghurai.
Penyelesaian mengubah model data. Skema dengan `additionalProperties: false` boleh menolak anotasi dan aplikasi mungkin berterusan atau menghantarnya sebagai konfigurasi sebenar. Dokumentasi luaran, README bersebelahan atau skema `description` selalunya menyediakan saluran penjelasan yang lebih selamat. Gunakan ahli berbentuk ulasan sahaja apabila setiap pengguna secara eksplisit membenarkan dan mengabaikan mereka.
Contoh yang berfungsi: fail tetapan beranotasi
Contoh yang berfungsi: fail tetapan beranotasi — bermula dengan sumber JSONC yang mengandungi `// seconds before retry` di atas `"timeout":30`. Jika destinasi sahaja menerima JSON, gunakan penghurai yang memahami JSONC untuk menghasilkan data dan kemudian sirikan data tersebut sebagai JSON yang ketat. Artifak yang digunakan menjadi `{"timeout":30}` manakala sumber yang dikekalkan mengekalkan penjelasannya.
Jangan alih keluar ulasan dengan ungkapan biasa. Urutan garis miring boleh muncul secara sah di dalam rentetan seperti URL, dan corak ulasan sekat boleh merentangi baris dengan cara yang salah pengendalian penggantian teks. Pastikan sumber dan artifak yang dijana berbeza, sahkan hasil yang ketat dan aturkan penjanaan semula dalam binaan. Ini mengekalkan nota pengarang tanpa berpura-pura penghurai penerima menyokongnya.
Perkara ini tidak meliputi
Perkara ini tidak meliputi — cara mengkonfigurasi penghurai individu untuk menerima ulasan, yang khusus alat dan sering berubah. Pilihan permisif dalam satu perpustakaan tidak mengubah tatabahasa JSON atau menjamin bahawa perkhidmatan lain akan menerima teks yang sama. Semak penghurai, versi dan destinasi dan bukannya bergantung pada paparan editor.
Artikel ini juga mengelakkan dakwaan yang tidak disokong tentang dengan tepat apabila ulasan telah dialih keluar, siapa yang menggunakan setiap penyelesaian terlebih dahulu atau sama ada satu keputusan reka bentuk sahaja menyebabkan populariti JSON. Penegasan sejarah sedemikian memerlukan sumber utama yang bebas. Di sini ia ditinggalkan atau diperbetulkan; kesimpulan yang disokong adalah terhad kepada sintaks ketat semasa, tingkah laku repositori dan perbezaan operasi antara format yang dinamakan.
Bawa pulang: JSON ialah format pertukaran data, bukan bahasa konfigurasi
Bawa pulang: JSON ialah format pertukaran data, bukan bahasa konfigurasi yang kaya dengan ulasan — dan pengesah menunjukkan dengan tepat tempat nota melanggar tatabahasa yang ketat. Apabila manusia memerlukan anotasi, pilih format yang disokong secara rasmi oleh alat pengguna atau kekalkan sumber beranotasi yang menghasilkan artifak ketat yang berasingan. Jangan anggap komen akan diabaikan tanpa bahaya.
Jika JSON yang ketat adalah wajib, alihkan penjelasan ke dokumentasi atau gunakan metadata yang diluluskan skema, kemudian sahkan dokumen akhir. ToolAcre sengaja melaporkan garis miring pertama dan bukannya memadamkan bahan secara senyap, kerana penukaran senyap boleh menukar rentetan atau menyembunyikan ketidakpadanan format. Konteks sejarah harus kekal berdisiplin sama: tuntutan yang tidak disokong ditinggalkan atau diperbetulkan, manakala sintaks yang boleh diperhatikan dan tingkah laku penghurai membawa kesimpulan.