go mod init và Go Modules: go.mod, go get, go mod tidy

Một module là một cây thư mục chứa các package Go, với một tệp go.mod ở gốc. go.mod đặt tên cho module và liệt kê phiên bản của mọi module khác mà nó phụ thuộc. Bạn tạo module bằng go mod init:

mkdir myapp
cd myapp
go mod init example.com/myapp

go: creating new go.mod: module example.com/myapp

Tệp go.mod được tạo ra:

module example.com/myapp

go 1.24.5

Vậy là đủ để build. Từ Go 1.16, mọi dự án Go đều là một module, và go build, go run . cùng go test sẽ từ chối hoạt động nếu không có module:

go: go.mod file not found in current directory or any parent directory; see 'go help modules'

Chọn module path

Module path là tiền tố của mọi đường dẫn import bên trong module. Với module example.com/myapp, một package trong thư mục internal/store được import là example.com/myapp/internal/store.

Với một thư viện, đường dẫn phải khớp với nơi code được lưu trữ, vì go get dùng nó để tìm repository. Với một chương trình chỉ mình bạn chạy, đường dẫn chỉ là một cái tên. Tránh dùng một từ đơn trùng với package trong thư viện chuẩn, như go mod init fmt hay go mod init strings: khi đó bản build sẽ thất bại với ambiguous import: found package fmt in multiple modules.

Chạy go mod init không kèm đối số sẽ thất bại bên ngoài cấu trúc GOPATH cũ:

go: cannot determine module path for source directory /home/ana/myapp (outside GOPATH, module path must be specified)

Hãy truyền cho nó một đường dẫn.

Thêm dependency

Viết import trước, rồi để Go tải về. Giả sử main.go import github.com/google/uuid. Build khi module chưa biết đến package này sẽ cho ra một chỉ dẫn rõ ràng:

main.go:6:2: no required module provides package github.com/google/uuid; to add it:
	go get github.com/google/uuid

Lệnh nào dưới đây cũng khắc phục được:

go get github.com/google/uuid
# or, to sync go.mod with every import in the module:
go mod tidy

go get báo lại những gì nó đã thay đổi:

go: downloading github.com/google/uuid v1.6.0
go: added github.com/google/uuid v1.6.0

go mod tidy báo lại cách nó giải quyết import:

go: finding module for package github.com/google/uuid
go: downloading github.com/google/uuid v1.6.0
go: found github.com/google/uuid in github.com/google/uuid v1.6.0

Giờ go.mod đã có một dòng require:

module example.com/myapp

go 1.24.5

require github.com/google/uuid v1.6.0

go get với phiên bản

go get thay đổi go.mod. Lệnh này không còn build hay cài đặt chương trình nữa; từ Go 1.18, đó là việc của go install pkg@version.

Dependency gián tiếp

Những requirement được đánh dấu // indirect là các module mà code của bạn không import trực tiếp nhưng bản build lại cần. Từ Go 1.17, go.mod liệt kê mọi module cung cấp package cho bản build, nên dependency của các dependency cũng xuất hiện ở đây với dấu đánh dấu đó. go mod tidy quản lý các dấu này; bạn không tự thêm chúng.

go mod tidy

Hãy chạy go mod tidy mỗi khi bạn thêm hoặc xóa import. Lệnh này:

• thêm requirement cho những package được import mà còn thiếu,
• xóa những requirement không còn được import,
• thêm các mục go.sum mà bản build cần và bỏ những mục đã cũ.

Nó xem xét mọi package trong module, bao gồm cả test và mọi tổ hợp build tag, nên đôi khi nó giữ lại một dependency mà bạn không thấy được dùng trên nền tảng của mình. Chạy go mod tidy trước mỗi lần commit, và kiểm tra trong CI rằng nó không tạo ra khác biệt nào, sẽ giúp go.mod luôn chính xác.

go.sum

go.sum ghi lại một mã băm cho mỗi phiên bản module mà bản build dùng:

github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=

Dòng đầu băm các tệp của module, dòng thứ hai chỉ băm go.mod của nó. Khi lệnh go tải một module, nó đối chiếu mã băm với go.sum và với cơ sở dữ liệu checksum công khai (sum.golang.org), nên một bản phát hành bị can thiệp hoặc âm thầm thay đổi sẽ làm bản build thất bại. Hãy commit go.sum cùng với go.mod, và đừng bao giờ sửa tay.

Cách Go chọn phiên bản

Go dùng minimal version selection (chọn phiên bản tối thiểu). Mỗi module liệt kê phiên bản tối thiểu của từng dependency mà nó cần, và bản build dùng phiên bản cao nhất trong số các mức tối thiểu đó, không bao giờ dùng bản mới hơn. Nếu module của bạn yêu cầu uuid v1.5.0 và một dependency yêu cầu uuid v1.6.0, bản build sẽ dùng v1.6.0, kể cả khi v1.7.0 đã có. Không có gì được nâng cấp trừ khi ai đó yêu cầu bằng go get.

Kết quả là các bản build có thể tái lập mà không cần tệp lock: go.mod cùng với đồ thị dependency xác định hoàn toàn mọi phiên bản. go list -m all in ra kết quả:

go list -m all

example.com/myapp
github.com/google/uuid v1.6.0

Major version

Một module từ v2 trở lên phải ghi major version vào đường dẫn: github.com/yourname/project/v2. Đường dẫn import cũng thay đổi theo, nên project và project/v2 là hai module khác nhau và có thể cùng có mặt trong một bản build. Đây là quy tắc của Go cho các thay đổi phá vỡ tương thích, và là lý do bạn thấy những import như github.com/jackc/pgx/v5.

replace: làm việc với dependency ở máy cục bộ

Để thử các thay đổi trên một dependency trước khi phát hành, hãy trỏ đường dẫn của nó tới một thư mục cục bộ:

module example.com/myapp

go 1.24.5

require example.com/mylib v1.2.0

replace example.com/mylib => ../mylib

Hoặc từ dòng lệnh:

go mod edit -replace example.com/mylib=../mylib
go mod tidy

Thư mục đó phải có go.mod riêng. replace chỉ có hiệu lực khi build trực tiếp module này, không áp dụng khi người khác phụ thuộc vào nó, nên nhớ xóa nó trước khi gắn tag phát hành.

Để sửa nhiều module cùng lúc mà không động tới các tệp go.mod của chúng, Go 1.18 đã bổ sung workspace:

go work init . ../mylib

Lệnh này ghi ra một tệp go.work khiến mylib ở máy cục bộ được ưu tiên. Đừng đưa go.work vào hệ thống quản lý phiên bản, trừ khi cả nhóm dùng cùng một cấu trúc thư mục.

Dependency cho công cụ (Go 1.24)

Go 1.24 bổ sung chỉ thị tool, để các trình sinh code và linter có thể được quản lý phiên bản trong go.mod thay vì cài đặt toàn cục:

go get -tool golang.org/x/tools/cmd/stringer
go tool stringer -type=Color

func init là chuyện khác

Những lượt tìm kiếm "golang init" thường muốn nói đến hàm init, vốn không liên quan gì đến go mod init. Package nào cũng có thể khai báo func init(). Hàm này không nhận đối số, code của bạn không thể gọi nó, và nó tự động chạy một lần, sau khi các biến cấp package được gán giá trị và trước main:

package main

import "fmt"

var config = loadConfig()

func loadConfig() map[string]string {
	fmt.Println("1. package variables are initialized")
	return map[string]string{"env": "dev"}
}

func init() {
	fmt.Println("2. init runs next")
	config["region"] = "eu"
}

func main() {
	fmt.Println("3. main runs last:", config)
}

Một tệp có thể có nhiều hàm init, và chúng chạy theo thứ tự xuất hiện. Các package được import sẽ hoàn tất việc khởi tạo của chúng trước. Hãy giữ init thật nhỏ: những việc có thể thất bại sẽ dễ xử lý và kiểm thử hơn khi là một hàm bình thường được gọi từ main.

Module riêng tư và proxy

Theo mặc định, go tải module qua proxy.golang.org. Proxy đó không thấy được các repository riêng tư, nên hãy cho Go biết những đường dẫn nào là riêng tư:

go env -w GOPRIVATE=github.com/yourcompany/*

Các module khớp với GOPRIVATE được tải trực tiếp từ repository bằng thông tin xác thực git của bạn và bỏ qua cơ sở dữ liệu checksum.

module example.com/myapp

go 1.24.5