Pemrograman Semantik Apa yang Dimaksud dengan Angka-angka di package.json Anda

Setiap proyek JavaScript memiliki package.json. Sebagian besar pengembang telah mengetikkan npm install some-library ratusan kali tanpa memperhatikan string versi secara kedua. Namun, jika Anda bertanya pada seseorang apa yang ^1.2.3 sebenarnya memungkinkan — artinya, versi mana yang npm akan dengan senang hati mengunduh — Anda sering kali mendapatkan jawaban yang mengangguk.

Ini bukan celah yang kecil. Rentang versi yang salah dipahami adalah penyebab sebuah npm install yang tiba-tiba berhenti bekerja pada mesin baru, padahal pipeline CI yang sama sebelumnya berjalan baik selama bertahun-tahun. Memahami kontrak di balik angka-angka tersebut adalah hal yang membutuhkan usaha kecil namun memberikan hasil besar yang membedakan pengembang yang bisa memperbaiki masalah versi dalam beberapa menit dari yang membutuhkan jam-jam untuk melakukannya.

Kontrak MAJOR.MINOR.PATCH

Versi semantik (semver) adalah format tiga angka: MAJOR.MINOR.PATCH. Setiap posisi membawa janji khusus tentang perubahan yang terjadi:

• MAJOR — perubahan yang mengganggu. Peningkatan ke versi utama mungkin membutuhkan Anda untuk memperbarui kode Anda.
• MINOR — fitur baru, kompatibel secara mundur. Kode yang sudah ada harus tetap berfungsi.
• TAMBAL — perbaikan bug saja. Aman untuk diperbarui; tidak ada perubahan API.

Itu adalah kontrak yang diikuti oleh paket-paket. Pergantian dari 2.3.1 ke 2.4.0 harus menambahkan fitur baru tanpa mengganggu perilaku yang sudah ada. Pergantian ke 3.0.0 adalah peringatan Anda: baca dokumentasi perubahan sebelum melakukan peningkatan.

Dalam praktiknya, pengelola sering kali keliru dan menyisipkan perubahan yang mengganggu dalam rilis minor. Semver tidak mengenakan dirinya sendiri — itu adalah konvensi. Namun, ini memberi Anda kerangka untuk mempertimbangkan risiko, dan ini adalah dasar dari semua operator rentang.

Apa yang Dianggap Perubahan yang Mengganggu?

Perubahan yang mengganggu adalah hal-hal yang memaksa pengguna untuk memperbarui kode mereka:

• Menghapus atau mengubah nama fungsi, kelas, atau konstanta yang diexport
• Mengubah tanda fungsi — menghapus parameter, menambahkan parameter wajib, atau mengubah tipe pengembalian
• Mengubah perilaku yang teramati secara cara yang membuat kode yang benar sekarang berperilaku salah
• Mengubah format file konfigurasi secara tidak kompatibel

Menambahkan parameter opsional baru? Itu adalah MINOR. Menambahkan ekspor baru? MINOR. Memperbaiki bug yang seseorang secara tidak sengaja menganggap sebagai fitur? Itu adalah keputusan, namun secara konvensi PATCH. Jika ragu, naikkan MINOR dan dokumentasikan dengan jelas.

Operator Rentang Versi di package.json

Buka apa saja package.json dan Anda akan melihat string versi seperti "^4.17.21" atau "~1.0.4". Ini bukan pin yang tepat — ini adalah rentang yang memberi tahu npm atau yarn versi mana yang diterima saat menyelesaikan pohon ketergantungan Anda.

Caret ^ — Kompatibel dengan Versi

Caret adalah operator default ketika Anda menjalankan npm install. Artinya: "terima versi mana pun yang tidak mengubah digit non-nol terkiri." Dalam praktiknya, untuk paket yang stabil, itu berarti sama pada versi utama, apapun versi minor atau patch:

^1.2.3  →  >=1.2.3 <2.0.0   (any 1.x.x at or above 1.2.3)
^0.2.3  →  >=0.2.3 <0.3.0   (zero-major: pins to minor)
^0.0.3  →  >=0.0.3 <0.0.4   (zero-zero: pins to exact patch)

Perilaku versi nol adalah sengaja. Paket pada 0.x.x mengindikasikan "API tidak stabil" — versi minor mana pun bisa mengganggu. Caret menghormati sinyal ini dan menjadi lebih konservatif.

Tilde ~ — Peningkatan pada Tingkat Patch Hanya

Tilde lebih konservatif. Ini menerima patch baru tetapi tidak mengubah versi minor:

~1.2.3  →  >=1.2.3 <1.3.0   (any 1.2.x at or above 1.2.3)
~1.2    →  >=1.2.0 <1.3.0
~1      →  >=1.0.0 <2.0.0   (when only major given — same as ^1)

Gunakan ~ ketika Anda ingin perbaikan bug tetapi tidak yakin bahwa library tersebut menghormati semver untuk peningkatan minor, atau ketika kode Anda sangat terikat pada permukaan API tertentu dan rilis fitur baru secara historis membawa perubahan perilaku halus.

Operator Perbandingan: >=, <=, >

Anda dapat menulis rentang sembarang menggunakan operator perbandingan. Spasi antara dua batasan berarti AND:

>=1.2.0           # at least 1.2.0, no upper bound
>=1.2.0 <2.0.0   # same as ^1.2.0 (explicit AND)
>1.2.0 <=1.5.0   # between these values, exclusive/inclusive

Ini muncul paling sering dalam peerDependencies, di mana sebuah library mengatakan sesuatu seperti "react": ">=16.8.0 <19.0.0" untuk menyatakan versi host yang kompatibel.

Wildcard: * dan x

Bentuk wildcard ini hampir selalu digunakan untuk kejelasan dokumentasi; npm menganggapnya setara dengan caret/tilde dengan dasar nol:

• * atau "" — versi apa saja. Jangan gunakan ini di produksi.
• 1.x atau 1.x.x — versi 1.x.x (sama dengan ^1.0.0)
• 1.2.x — versi 1.2.x (sama dengan ~1.2.0)

Versi Pra-rilis

Versi pra-rilis terlihat seperti 1.0.0-alpha.1, 2.0.0-beta.3, atau 3.1.0-rc.1. Mereka dianggap lebih rendah dibandingkan dengan rilis yang sama angkanya — 1.0.0-alpha.1 < 1.0.0.

Kritis, operator rentang tidak secara otomatis mencakup versi pra-rilis. Rentang ^1.0.0 tidak akan mengambil 1.1.0-beta.1meskipun secara teknis memenuhi >=1.0.0 <2.0.0. Anda harus secara eksplisit memilih:

npm install some-library@next
npm install some-library@2.0.0-beta.3

Ini adalah keamanan yang sengaja. Anda hampir tidak ingin CI secara diam-diam mengambil versi pra-rilis dari ketergantungan karena secara teknis memenuhi rentang versi. Jika Anda menguji versi pra-rilis, lakukan secara sengaja. -alpha File Lock Tidak Harus Dipilih

Ketika npm menyelesaikan rentang versi Anda, ia memilih versi teratas yang kompatibel yang tersedia

pada saat itu ^1.2.3 . Jalankan hari ini dan Anda mendapatkan. Jalankan itu enam bulan kemudian dan Anda mungkin mendapatkan npm install . Sama 1.5.0, pohon ketergantungan berbeda, perilaku yang berbeda. 1.9.2Itulah yang diselesaikan oleh file lock. package.json(npm) dan

(yarn) mencatat versi yang tepat yang diinstal untuk setiap ketergantungan — langsung dan transitive. Ketika seseorang lain menyalin repositori Anda dan menjalankan package-lock.json , mereka mendapatkan pohon yang sama. yarn.lock Sertakan file lock. Selalu. npm ciTidak menyertakannya berarti:

Pengembang berbeda mungkin menjalankan versi ketergantungan yang berbeda tanpa menyadarinya Lingkungan CI dapat secara diam-diam berbeda dari lingkungan lokal Anda

• Peningkatan ketergantungan transitive dapat mengubah perilaku produksi tanpa perubahan yang terlihat di
• Kecuali satu kasus: library yang dipublikasikan (bukan aplikasi) secara konvensi meninggalkan file lock tidak disertakan agar konsumen dapat menyelesaikan pohon ketergantungan mereka sendiri. Jika Anda membuat aplikasi, tidak ada alasan baik untuk meninggalkan file lock di luar kontrol sumber.
• "latest" di package.json Selalu Salah git diff

Sering kali Anda akan melihat ini di dalam

Jangan lakukan ini.

merujuk pada tag yang saat ini diberlakukan package.json:

"dependencies": {
  "some-package": "latest"
}

di npm — ini berubah setiap kali pengembang mempublikasikan rilis baru. Sebuah "latest" di mesin baru dapat mengunduh versi utama yang sangat berbeda dari versi yang Anda uji. latest Ini mungkin berfungsi baik selama beberapa minggu, lalu secara diam-diam rusak ketika paket mempublikasikan versi utama baru. Lebih buruk lagi, ini membuat npm install tidak berguna sebagai spesifikasi yang dapat direproduksi — Anda tidak bisa memahami versi apa yang sedang berjalan tanpa memeriksa npm secara manual. Tetapkan versi nyata dan biarkan caret mengelola peningkatan yang aman dalam rentang tersebut.

Periksa Apakah Versi Memenuhi Rentang package.json Jika Anda tidak yakin apakah versi memenuhi rentang tertentu — terutama dengan paket versi nol atau ekspresi yang tidak biasa —

di iotools.cloud memberi Anda jawaban langsung. Masukkan rentang (

) dan versi kandidat, dan ia akan memberi tahu Anda apakah kendala tersebut dipenuhi. Kalkulator Versi Semver & Pengujian Rentang Ini berguna saat meninjau PR peningkatan ketergantungan, memperbaiki mengapa^1.2.3, ~0.5.0, >=2.0.0 <3.0.0diresolusi ke versi yang tidak diharapkan, atau memverifikasi

rentang sebelum menerbitkan library. npm install Operator peerDependencies Menyelesaikan ke

Rincian Singkat

1.2.0 atau lebih tinggi, tanpa batas	Contoh	Versi apa saja (hindari)
^	^1.2.3	>=1.2.3 <2.0.0
~	~1.2.3	>=1.2.3 <1.3.0
>=	>=1.2.0	Versi 1.2.x patch apa saja
*	*	tepat
x	1.2.x	Tepat 1.2.3
Versi Semantik: Apa yang Dimaksud dengan Angka-angka di package.json Anda 2	1.2.3	Versi Semantik: Apa yang Dimaksud dengan Angka-angka di package.json Anda 1

Anda mungkin juga menyukai