JSON, TOML, YAML atau CSON: Memilih Format Konfigurasi

Kesimpulan utama: gunakan JSON untuk pertukaran mesin, dan pilih TOML atau YAML untuk konfigurasi yang diselenggara manusia mengikut ekosistem (YAML untuk Kubernetes dan CI, TOML untuk struktur rata atau tarikh asli); gunakan JSONC hanya apabila anda tidak pasti sama ada pembaca menyokong dialek itu.

JSON wujud untuk mesin yang bertukar data; fail konfigurasi ditulis oleh manusia untuk manusia. Campurkan kedua-duanya dan anda mendapat config.json yang tidak boleh mengandungi komen dan yang tiada siapa berani memangkasnya.

1. Mulakan dengan dua jenis fail berbeza

Pertukaran data dan konfigurasi tidak berkongsi matlamat yang sama, walaupun orang yang sama sering menulis kedua-duanya pada mesin yang sama.

JSON mendapat markah hampir sempurna dalam lajur kiri: tatabahasa minimum, penghurai dalam setiap bahasa, dan ketiadaan komen bermakna tiada masalah "komen terpesong daripada nilai". Dalam lajur kanan, keketatannya ialah geseran tulen: tiada komen, tiada koma di hujung, tiada tarikh, dan teks berbilang baris mesti diruntuhkan menjadi satu baris dengan \n.

2. Empat pesaing dan sintaks mereka

• JSON: ditakrifkan oleh RFC 8259 dan ECMA-404, dengan tepat enam jenis nilai: objek, tatasusunan, rentetan, nombor, boolean dan null. Ia ialah standard pertukaran de facto dan satu-satunya format yang tidak memerlukan keputusan pemilihan.
• TOML: dicipta oleh Tom Preston-Werner, dengan v1.0.0 diterbitkan pada Januari 2021. Matlamat yang dinyatakan ialah format konfigurasi minimum dengan semantik jelas yang memeta secara tidak kabur kepada jadual cincang. Cargo.toml dan pyproject.toml menggunakannya secara lalai.
• YAML: spesifikasi semasa ialah 1.2.2. Indentasi menyatakan hierarki, dan ia menyokong komen, sauh dan berbilang dokumen. Manifes Kubernetes, GitHub Actions dan Ansible semuanya bergantung padanya, dengan kos spesifikasi besar dan perbezaan pelaksanaan.
• CSON: CoffeeScript Object Notation, yang menulis konfigurasi menggunakan literal objek CoffeeScript. config.cson Atom menggunakannya. Ia menyokong komen, kunci tanpa petik dan koma di hujung, tetapi ekosistemnya tidak pernah meninggalkan dunia JavaScript.

2.1 Perbandingan keupayaan

Dua sel patut diberi nota. TOML tiada null, yang merupakan kegagalan paling biasa semasa menukar daripada JSON. Tingkah laku "tarikh asli" YAML bermakna penghurai 1.1 menukar 2026-10-31 menjadi objek tarikh secara automatik, jadi jenis itu hanyut merentas bahasa.

3. Komen: satu-satunya kelemahan JSON

Kesimpulan dahulu: jika manusia menyelenggara fail dan perlu menjelaskan mengapa sesuatu nilai menjadi seperti itu, jangan gunakan JSON standard.

Terdapat empat laluan praktikal, disusun mengikut betapa invasifnya:

1. Tukar kepada JSONC, iaitu JSON standard ditambah komen dan koma di hujung. settings.json dan tsconfig.json VS Code menggunakannya. Kosnya ialah pembaca mesti menggunakan penghurai peka komen seperti jsonc-parser; JSON.parse biasa gagal. Butiran ada dalam JSON5 dan JSONC: JSON dengan komen.
2. Kekalkan dokumen sampingan. config.json kekal boleh dibaca mesin, manakala config.md menerangkan maksud setiap medan dan mengapa ia memegang nilai itu. Kedua-duanya tinggal dalam direktori yang sama dan berubah dalam commit yang sama.
3. Letakkan penjelasan dalam skema. Kata kunci description dan $comment JSON Schema boleh mendokumenkan medan, tetapi skema jarang dihantar bersama konfigurasi masa jalan, jadi orang yang membaca konfigurasi mungkin tidak pernah melihatnya.
4. Berpindah ke TOML atau YAML, membiarkan format itu sendiri menyediakan komen yang difahami oleh setiap penghurai.

复制{
  // Ditetapkan pada 8080: skrip binaan bahagian hadapan membaca port ini untuk proksinya
  "port": 8080,
  // Lumpuhkan pemantauan untuk mengelakkan kehabisan inod dalam CI
  "watch": false
}

JSONC masih dialek: sambungan kekal .json, tetapi hanya sesetengah alat memahaminya. Apabila data meninggalkan pasukan atau melintasi sempadan perkhidmatan, garis antara JSONC dan JSON standard mesti didokumenkan.

4. Tarikh dan rentetan berbilang baris: kubu TOML

TOML menaik taraf tarikh-masa kepada jenis kelas pertama dengan empat varian: tarikh-masa offset, tarikh-masa setempat, tarikh setempat dan masa setempat. Rentetan berbilang baris mempunyai sintaks khusus yang mengekalkan pemisah baris:

复制title = "json-toolkit"
created = 2026-10-31T09:00:00+08:00
description = """
A JSON toolkit for developers.
Every operation runs locally in the browser.
"""

Maklumat yang sama dalam JSON mesti menurunkan tarikh kepada rentetan dan melepaskan pemisah baris:

复制{
  "title": "json-toolkit",
  "created": "2026-10-31T09:00:00+08:00",
  "description": "A JSON toolkit for developers.\nEvery operation runs locally in the browser."
}

Dalam JSON, "created" hanyalah rentetan yang kebetulan kelihatan seperti tarikh, jadi maklumat jenis mesti tinggal dalam kontrak medan: kedua-dua pihak mesti bersetuju bahawa medan itu sentiasa RFC 3339. TOML memberikan penghurai objek tarikh sebenar tanpa persetujuan lisan diperlukan.

YAML juga boleh mengandungi teks berbilang baris, tetapi dua gaya blok bermaksud perkara berbeza: | mengekalkan pemisah baris manakala > melipatnya menjadi ruang. Pilih yang salah dan alamat atau pernyataan SQL runtuh menjadi satu baris, kesilapan yang sangat sukar ditangkap semasa semakan.

5. Nombor: perbezaan yang paling terlepas pandang

Spesifikasi JSON tidak meletakkan had pada ketepatan nombor, tetapi RFC 8259 juga memberi amaran bahawa kesalingoperasian paling selamat apabila nombor dianggap sebagai berganda IEEE 754. Dalam JavaScript, integer di atas 2^53 - 1 kehilangan ketepatan secara senyap:

复制JSON.parse('{"id":9007199254740993}').id
// 9007199254740992: digit terakhir hilang

TOML mewajibkan integer 64-bit bertanda dikendalikan tanpa kehilangan dan menaikkan ralat dan bukannya memotong secara senyap; nombor terapung mengikuti binary64 dan juga boleh jadi inf atau nan. YAML 1.1 membawa beban lama: 1:30 dihuraikan sebagai 90 (seksagesimal), dan boolean menerima yes, no, on dan off. Oleh itu "masalah Norway" klasik, di mana kod negara NO menjadi false.

Untuk wang, jangan sekali-kali bergantung pada titik terapung dalam mana-mana format ini: gunakan unit kecil integer, rentetan, atau jenis perpuluhan pangkalan data. Pemformatan dan ketepatan dibincangkan lebih mendalam dalam sempadan penukaran JSON, YAML dan XML.

6. Jadual dan bersarang: sempadan keras TOML

TOML menyatakan bersarang dengan jadual dan tatasusunan jadual:

复制[server]
port = 8080

[[routes]]
path = "/parse"
method = "POST"

[[routes]]
path = "/minify"
method = "POST"

Ia mempunyai dua sempadan keras yang mesti anda ketahui sebelum menukar:

• Akar dokumen TOML ialah jadual, jadi dokumen JSON yang peringkat atasnya tatasusunan (seperti [1, 2, 3]) tiada perwakilan TOML yang sah; ia mesti dibalut sebagai {"items": [...]};
• TOML tiada null, jadi medan null JSON mesti sama ada digugurkan atau diganti dengan rentetan kosong atau nilai sentinel, dengan semantik diserahkan kepada pengguna.

YAML adalah sebaliknya: kedalaman bersarang tidak terhad, dan sauh serta kunci gabungan boleh menggunakan semula serpihan:

复制defaults: &defaults
  retries: 3
  timeoutMs: 5000

server:
  <<: *defaults
  port: 8080

Sauh ialah keupayaan YAML sahaja dan kehilangan yang dijamin semasa penukaran: JSON tiada sintaks rujukan, jadi fail yang dikembangkan bertambah besar dan tiada apa yang merekodkan bahawa kedua-dua bahagian itu dahulunya konfigurasi yang sama.

7. Memilih mengikut senario

Satu peraturan praktikal: biarkan ekosistem memilih format konfigurasi, bukan pilihan peribadi. Menulis Rust bermakna Cargo.toml, menggunakan Kubernetes bermakna YAML, dan membina sambungan VS Code bermakna JSONC. Hanya dalam projek baharu tanpa kekangan ekosistem "yang mana lebih sedap ditulis" menjadi soalan sebenar.

8. Sempadan penukaran

Alat penukaran menjamin nilai, tidak pernah komen. Jadi jangan reka saluran dua hala di mana "JSON ialah sumber dan YAML ialah artifak binaan". Sama ada jana dalam satu arah sahaja, atau selenggara satu fail sumber.

9. Senarai semak

• [ ] Dokumentasikan jenis fail mana menggunakan format mana, dan senaraikan dialek yang dibenarkan;
• [ ] Utamakan TOML atau YAML untuk konfigurasi yang diselenggara manusia, dan JSON untuk pertukaran mesin;
• [ ] Simpan tarikh dalam JSON sebagai rentetan RFC 3339 dan tandakan format dalam skema;
• [ ] Wakili wang dan integer di atas 2^53 sebagai rentetan atau unit kecil, tidak pernah sebagai nombor terapung;
• [ ] Sahkan setiap format dalam CI dengan penghurai sendiri, tidak pernah dengan JSON.parse untuk YAML;
• [ ] Hijrahkan format dalam satu arah sahaja, dan padam fail lama supaya keduanya tidak hanyut.

Soalan Lazim

Mengapa penukaran JSON ke TOML gagal pada sesetengah medan?

TOML tiada null, dan akar dokumen TOML ialah jadual, jadi medan null JSON mesti digugurkan atau diganti dengan rentetan kosong atau sentinel, dan tatasusunan peringkat atas mesti dibalut sebagai {"items": [...]}. Komen, jenis tarikh dan inf/nan juga hilang apabila bergerak ke arah bertentangan, sebab itulah penukaran harus sehala.

Patutkah saya menyimpan dua fail konfigurasi dalam format berbeza?

Tidak. Alat penukaran menjamin nilai tetapi tidak pernah komen, jadi saluran di mana "JSON ialah sumber dan YAML ialah artifak binaan" akan hanyut. Sama ada jana dalam satu arah sahaja, atau selenggara satu fail sumber dan padam fail lama selepas berhijrah.

Bagaimana saya menambah komen pada fail konfigurasi JSON?

JSON standard tiada komen. Anda boleh bertukar kepada JSONC (dialek VS Code, dibaca dengan jsonc-parser), mengekalkan dokumen sampingan yang menerangkan setiap medan, atau berpindah ke TOML atau YAML. Fail yang dihantar ke sistem lain patut kekal JSON standard, dengan penjelasan tinggal dalam dokumentasi atau skema.

Adakah TOML atau YAML lebih baik untuk konfigurasi aplikasi?

Pilih TOML apabila strukturnya rata, kebanyakannya pasangan nilai kunci, dan tarikh asli penting; semantiknya lebih boleh diramal dan perbezaan penghurai lebih kecil. Pilih YAML apabila anda memerlukan bersarang dalam, berbilang dokumen, penggunaan semula sauh, atau apabila ekosistem sasaran berorientasikan YAML, seperti Kubernetes atau CI. Kedua-duanya menyokong komen, jadi pembeza sebenar ialah kerumitan struktur dan penguncian ekosistem.

Mengapa NO menjadi false dalam YAML?

YAML 1.1 menganggap yes, no, on, off, y dan n sebagai boolean, jadi kod negara Norway NO dihuraikan sebagai false. Ini ialah "masalah Norway". Elakkannya dengan menggunakan pelaksanaan yang mengikuti YAML 1.2, atau dengan memetik setiap rentetan yang mungkin disalah tafsir.

Adakah CSON masih berbaloi digunakan?

Bukan untuk projek baharu. CSON bergantung pada ekosistem CoffeeScript, mempunyai sedikit alat yang diselenggara, dan sokongan editor serta CI terhad; selepas Atom berhenti diselenggara, kes penggunaannya menyusut lagi. Jika projek sudah mempunyai konfigurasi CSON, jadualkan penghijrahan sekali sahaja ke JSON, TOML atau YAML dan bukannya menambah lebih banyak.