Berkas go.mod adalah kartu identitas sebuah module: satu berkas teks ringkas di akar direktori yang mencatat nama module, versi bahasa, dan seluruh dependensinya. Formatnya line-oriented — setiap baris memuat satu directive yang terdiri dari keyword dan argumennya, mirip blok import yang dapat difaktorkan. Chapter ini merangkum arti setiap directive yang mungkin Anda temui, dari module hingga tool yang termuda, ditambah directive pendamping pada berkas go.work. Seluruh perilaku yang dikutip disarikan dari halaman resmi Go Modules Reference.
Contoh Isi go.mod #
Bentuk berikut memperlihatkan seluruh directive dalam satu berkas fiktif:
module contoh.com/layanan-pesanan
go 1.27
toolchain go1.27.2
require (
github.com/google/uuid v1.6.0
golang.org/x/sync v0.10.0 // indirect
)
tool golang.org/x/tools/cmd/goimports
exclude contoh.com/ekspresi-lama v1.1.0
replace contoh.com/pembayaran => ../pembayaran-lokal
retract [v1.0.0, v1.0.2]Baris require dapat difaktorkan menjadi blok berkurung seperti contoh di atas, atau ditulis satu baris per dependensi — keduanya setara. Komentar diawali tanda // dan bisa berdiri sendiri maupun menempel di akhir baris.
Directive Utama #
| Directive | Bentuk | Kegunaan |
|---|---|---|
module | module contoh.com/layanan | Menetapkan module path sebagai identitas dan awalan import path seluruh paket di dalamnya |
go | go 1.27 | Versi minimum bahasa Go yang dibutuhkan module; toolchain lebih baru boleh membangunnya |
toolchain | toolchain go1.27.2 | Menyarankan toolchain tertentu; berlaku saat toolchain bawaan lebih tua dari usulan (sejak Go 1.21) |
require | require jalur versi | Mendeklarasikan dependensi beserta versi minimumnya |
exclude | exclude jalur versi | Melarang satu versi dependensi dipilih oleh resolusi module |
replace | replace lama => baru | Mengganti dependensi dengan versi lain, path lokal, atau module pengganti |
retract | retract v1.0.1 atau retract [v1.0.0, v1.0.2] | Menarik kembali versi yang bermasalah agar pengguna diperingatkan saat upgrade (sejak Go 1.16) |
tool | tool golang.org/x/tools/cmd/goimports | Menandai dependensi berupa perkakas CLI yang dapat dijalankan dengan go tool (sejak Go 1.24) |
Directive tool memiliki dua syarat kerja: perkakas yang berada di module lain harus disertai baris require yang menyebut versinya, dan perkakas tersebut hanya bisa dijalankan lewat go tool saat direktori kerja berada di dalam module yang mendeklarasikannya. Hubungan go dan toolchain juga asimetris: versi toolchain tidak boleh lebih rendah daripada versi go pada berkas yang sama.
Penanda // indirect #
Suffix // indirect pada baris require bukan directive, melainkan komentar yang dikelola perkakas go sendiri. Penanda tersebut menyatakan dependensi tidak diimpor langsung oleh kode module — ia dibutuhkan karena dependensi lain yang memintanya. Perintah go mod tidy menambahkan dan menghapus penanda ini secara otomatis, sehingga kita tidak perlu menuliskannya manual.
Directive go.work #
Berkas go.work mendefinisikan workspace: kumpulan module yang dikembangkan bersamaan dalam satu mesin tanpa saling mempublikasikan. Formatnya satu tingkat lebih kecil dari go.mod:
| Directive | Bentuk | Kegunaan |
|---|---|---|
go | go 1.27 | Versi bahasa untuk keseluruhan workspace |
use | use ./layanan-a | Memasukkan direktori sebagai anggota workspace |
replace | replace jalur => ./lokal | Penggantian module yang berlaku dalam lingkup workspace |
Direktif replace pada go.work mengesampingkan replace di go.mod anggota selama workspace aktif, sehingga pengembangan lokal tidak mengubah berkas go.mod yang akan diterbitkan. Praktik lengkapnya dibahas pada chapter go work
.
Referensi #
- Go Modules Reference — go.mod files — definisi resmi setiap directive beserta sintaksnya.
- Go Modules Reference — go.work files — directive workspace yang dikutip di atas.
- Blog resmi: Using Go Modules — pengantar praktik alur kerja module.
Perilaku go.mod ini dikendalikan sejumlah environment variable — dari GOPROXY hingga GOTOOLCHAIN — yang dirangkum pada chapter Environment Variable
.