Migrasi ke Go Modul

Tulisan ini adalah bagian ke 2 dari sebuah seri.

Proyek-proyek Go menggunakan beragam strategi manajemen dependensi. Perkakas vendor seperti dep dan glide cukup terkenal, namun mereka memiliki perbedaan yang luas dalam perilaku dan tidak saling bekerja satu sama lain. Beberapa proyek bahkan menyimpan semua sumber kode di GOPATH dalam sebuah repositori Git. Yang lainnya bergantung kepada "go get" dan menggunakan versi terbaru dari dependensi yang terpasang di GOPATH.

Sistem Go modul, yang diperkenalkan sejak Go 1.11, menyediakan solusi manajemen dependensi dalam perintah "go". Artikel ini menjelaskan perkakas dan teknik-teknik untuk mengonversi sebuah proyek menjadi Go modul.

Mohon diingat: jika proyek Anda telah di tag v2.0.0 atau lebih tinggi, Anda perlu mengubah path modul Anda saat menambahkan berkas "go.mod". Kita akan menjelaskan bagaimana melakukan hal tersebut tanpa mengganggu pengguna modul Anda di masa depan di artikel selanjutnya yang berfokus pada v2 dan seterusnya.

Sebuah proyek bisa berada dalam salah satu situasi berikut sebelum memulai transisi ke Go modul:

Kasus yang pertama telah diulas dalam Menggunakan Go Modul; kita akan menelaah kedua kasus terakhir dalam artikel ini.

Untuk mengonversi sebuah proyek yang sudah menggunakan sebuah perkakas manajemen dependensi, cukup jalankan perintah berikut:

"go mod init" membuat berkas "go.mod" yang baru dan secara otomatis mengimpor dependensi dari "Godeps.json", "Gopkg.lock", atau sejumlah format lain yang didukung. Argumen dari "go mod init" adalah path modul, lokasi di mana modul dapat ditemukan.

Setelah itu jalankan "go build ./…​" dan "go test ./…​" sebelum melanjutkan. Langkah-langkah selanjutnya bisa saja mengubah berkas "go.mod" Anda, jadi jika Anda lebih suka pendekatan yang bertahap, tahap ini menghasilkan berkas "go.mod" yang paling sesuai dengan spesifikasi dependensi pra-modul.

"go mod tidy" mencari semua paket-paket yang secara transitif diimpor oleh paket-paket dalam modul Anda. Ia akan menambahkan modul baru untuk paket-paket yang tidak disediakan oleh modul lain, dan ia juga menghapus dependensi modul dari paket-paket yang tidak diimpor. Jika sebuah modul menyediakan paket-paket yang hanya diimpor oleh proyek yang belum dimigrasi ke modul, maka dependensi modul tersebut akan ditandai dengan komentar "// indirect". Praktik yang disarankan yaitu menjalankan "go mod tidy" sebelum menambahkan "go.mod" ke dalam version control.

Mari kita selesaikan dengan memastikan bahwa kode dapat dibangun dan melewati pengujian:

Ingatlah bahwa manajemen dependensi lain bisa saja menspesifikasikan dependensi pada tingkat individu dari paket-paket atau secara keseluruhan repositori (bukan modul), dan pada umumnya mereka tidak mengenali dependensi yang dispesifikasikan dalam berkas "go.mod". Akibatnya, Anda bisa saja mendapatkan versi yang tidak sama dengan paket yang sebelumnya, dan ada risiko pembaruan yang bisa menimbulkan kerusakan. Oleh karena itu, sangat penting mengikuti perintah di atas bersamaan dengan audit dari hasil dependensi. Untuk melakukan hal tersebut, jalankan

dan bandingkan versi keluarannya dengan berkas manajemen dependensi yang lama untuk memastikan bahwa versi yang terpilih adalah sesuai. Jika Anda menemukan versi yang tidak diinginkan, Anda bisa mencari tahu penyebabnya menggunakan "go mod why -m" dan/atau "go mod graph", dan memperbarui atau downgrade ke versi yang sesuai menggunakan "go get". (Jika versi yang Anda minta lebih lama dari versi yang terpilih, "go get" juga akan men-downgrade dependensi lainnya bila diperlukan untuk menjaga kompatibilitas.) Sebagai contohnya,

Untuk sebuah proyek Go tanpa sistem manajemen dependensi, mulailah dengan membuat berkas "go.mod":

Tanpa adanya berkas konfigurasi dari manajemen dependensi lainnya, "go mod init" hanya akan membuat berkas "go.mod" yang berisi directive "module" dan "go". Dalam contoh ini, kita men-set path modul ke "golang.org/x/blog" karena itulah path impornya. Pengguna bisa mengimpor paket-paket dengan path tersebut, dan pemilik modul harus berhati-hati supaya tidak mengubahnya sewaktu-waktu.

Perintah directive "module" dalam "go.mod" mendeklarasikan path modul, dan directive "go" mendeklarasikan versi bahasa Go yang digunakan untuk mengompilasi kode dalam modul.

Selanjutnya, jalankan "go mod tidy" untuk menambahkan dependensi dari modul:

Perintah "go mod tidy" menambah dependensi modul untuk semua paket-paket yang secara transitif diimpor oleh paket dalam modul Anda dan membuat sebuah berkas "go.sum" yang berisi checksum dari setiap pustaka pada versi tertentu. Mari kita selesaikan dengan memastikan bahwa kode dapat dibangun dan tes berjalan dengan sukses:

Ingatlah bahwa saat "go mod tidy" menambahkan dependensi, ia akan menggunakan versi terakhir dari dependensi tersebut. Jika GOPATH Anda berisi versi lama dari dependensi yang ternyata memiliki perubahan, Anda akan mendapatkan eror saat menjalankan "go mod tidy", "go build", atau "go test". Jika hal ini terjadi, cobalah men-downgrade ke versi yang lama dengan "go get" (misalnya, "go get github.com/broken/module@v1.1.0"), atau buat modul Anda kompatibel dengan versi terbaru dari setiap dependensi.

Beberapa pengujian bisa saja membutuhkan beberapa perubahan setelah migrasi ke Go modul.

Jika sebuah tes perlu menulis berkas dalam direktori paket, ia akan gagal bila direktori paket berada dalam modul cache, yang mana hanya read-only. Secara khusus, hal ini bisa menyebabkan "go test all" menjadi gagal. Pengujian seharusnya menyalin berkas yang ia butuhkan ke direktori khusus yang sementara.

Jika sebuah tes bergantung pada path relatif (misalnya, "../paket-dalam-modul-lain") untuk mencari dan membaca berkas di paket lain, maka ia akan gagal jika paket tersebut berada dalam modul yang berbeda, yang bisa saja berada dalam lokasi sub-direktori dengan versi dari modul cache atau dari sebuah path yang dispesifikasikan oleh directive "replace". Jika kasus ini terjadi, maka Anda perlu menyalin input pengujian ke dalam modul Anda, atau ubah tes input dari berkas mentah menjadi data yang ditanam ke dalam berkas sumber kode ".go".

Jika sebuah tes membutuhkan perintah "go" dijalankan dengan mode GOPATH, ia juga akan gagal. Jika hal ini terjadi, Anda perlu menambahkan berkas "go.mod" ke dalam sumber yang akan diuji, atau set "GO111MODULE=off" secara eksplisit.

Terakhir, Anda sebaiknya memberi tag dan merilis versi baru dari modul Anda. Hal ini adalah opsional bila Anda belum pernah merilis versi sebelumnya, namun tanpa adanya rilis resmi, pengguna lain akan bergantung pada commit tertentu menggunakan versi-pseudo, yang mungkin lebih sukar untuk didukung.

Berkas "go.mod" Anda yang baru mendefinisikan path impor yang kanonis bagi modul Anda dan menambahkan kebutuhan versi minimum yang baru. Jika pengguna modul Anda sudah menggunakan path impor yang benar, dan dependensi Anda belum banyak berubah, maka menambahkan berkas "go.mod" adalah sebuah backward-compatible (modul Anda masih bisa digunakan oleh pengguna lain tanpa adanya kerusakan di sisi mereka) — namun hal ini adalah perubahan yang signifikan, dan bisa saja menimbulkan permasalahan nantinya. Jika Anda sudah memiliki tag dengan versi, Anda harus meningkatkan versi minor. Lihat Menerbitkan Go Modul untuk belajar bagaimana meningkatkan dan menerbitkan versi.

Setiap modul mendeklarasikan path modul-nya dalam berkas "go.mod". Setiap perintah "import" yang mengacu ke sebuah paket dalam modul haruslah memiliki prefiks path modul. Namun, perintah "go" bisa menemukan sebuah repositori yang berisi modul lewat banyak path impor remote yang berbeda. Sebagai contohnya, "golang.org/x/lint" dan "github.com/golang/lint" mengacu pada repositori yang sama yang disimpan di go.googlesource.com/lint. Berkas go.mod di dalam repositori tersebut mendeklarasikan path-nya ke "golang.org/x/lint", jadi hanya path tersebut lah yang berkorespondensi ke modul yang valid.

Go 1.4 menyediakan mekanisme untuk mendeklarasikan path impor kanonis menggunakan komentar // import, namun pembuat paket tidak selalu menuliskannya. Akibatnya, kode yang ditulis sebelum adanya modul bisa saja menggunakan path impor yang tidak kanonis tanpa menimbulkan kesalahan penamaan. Bila menggunakan modul, path impor harus sama dengan path modul, jadi Anda perlu mengubah perintah "import": sebagai contohnya, Anda perlu mengubah import "github.com/golang/lint" menjadi import "golang.org/x/lint".

Skenario lain yang mana path kanonis dari modul bisa berbeda dengan path repositori terjadi pada Go modul dengan versi 2 atau lebih. Sebuah Go modul dengan versi mayor di atas 1 haruslah menambahkan sufiks versi-mayor pada path modul-nya: sebagai contoh, versi v2.0.0 haruslah diberikan sufiks "/v2". Namun, perintah "import" bisa mengacu ke paket-paket dalam modul tersebut tanpa sufiks tersebut. Sebagai contohnya, pengguna non-modul dari "github.com/russross/blackfriday/v2" pada versi v2.0.1 bisa saja mengimpornya sebagai "github.com/russross/blackfriday" saja, dan perlu mengubah path impor-nya untuk menambahkan sufiks "/v2".

Proses mengonversi Go modul seharusnya mudah bagi kebanyakan pengguna. Masalah-masalah khusus bisa muncul disebabkan path impor yang tidak kanonis atau breaking changes disebabkan karena dependensi. Artikel selanjutnya akan mengeksplorasi bagaimana menerbitkan versi baru, v2 dan seterusnya, dan cara-cara untuk men-debug situasi-situasi yang aneh.

Bila ada tanggapan dan bantuan untuk membantu manajemen dependensi di Go, silakan kirim laporan kesalahan atau laporan pengalaman.

Terima kasih untuk semua tanggapan dan bantuan yang telah menjadikan Go modul lebih baik.