Modules

Go Modules

The Go Module (go.mod)

Concept: A collection of Go packages stored in a file tree with a go.mod file at its root. It is the unit of dependency management, versioning, and distribution.

• Why: Before modules (the GOPATH era), versioning was inconsistent. Modules allow projects to live anywhere on your disk and ensure Reproducible Builds by locking dependencies.
• Behavior: The go.mod file acts as the project's identity and manifest.

module github.com/username/myproject // Identity
go 1.23.0 // Minimum Go version

require (
    github.com/google/uuid v1.6.0 // Direct dependency
    golang.org/x/crypto v0.0.0-202301... // Indirect/Pseudo-version
)

The Semantic Import Versioning

Concept: In Go, "Major" versions (v2, v3, etc.) are treated as entirely different packages.

• Behavior:

  • v0 and v1: Imported normally as github.com/foo/bar.
  • v2+: The module path must change to include the version suffix.

// Importing a v1 library
import "github.com/go-chi/chi" 

// Importing a v5 library (treated as a different package)
import "github.com/go-chi/chi/v5" 

• Why: This prevents the "Diamond Dependency" problem. It allows a project to use both v1 and v2 of the same library simultaneously without naming collisions. It forces developers to be intentional about breaking changes.

Integrity Checking (go.sum)

Concept: A list of cryptographic checksums for every dependency.

• Behavior: This is not a lockfile like package-lock.json. It is a security verification list. You should never manually edit it; use go mod tidy instead.

• Why: It ensures the code downloaded today matches what was downloaded months ago. If a dependency is hacked and the code changes without a version bump, Go will catch the mismatch and refuse to build.

Minimal Version Selection (MVS)

Concept: Go's unique algorithm for choosing dependency versions.

• Behavior: Unlike npm which might pull the latest "compatible" version, MVS picks the minimum version that satisfies all requirements in the dependency graph.

• Why: This creates extreme stability. Your build won't suddenly break because a dependency released a "safe" minor update that actually contained a bug.

Access Control & Local Workflow

Internal Packages (internal/)

Concept: A special directory that restricts visibility to the local module.

Setup:

• Project structure

myproject/
├── main.go
├── utils/
│   ├── helper.go
├── internal/
│   ├── secret/
│   │   └── secret.go

• Import directives

// Inside myproject/main.go
import "github.com/username/myproject/internal/secret" // ALLOWED ✅

// Inside an EXTERNAL project (e.g., github.com/otheruser/app)
import "github.com/username/myproject/internal/secret" // COMPILER ERROR ❌

• Why: It enforces Encapsulation. It prevents "public API bloat" by hiding implementation details, ensuring users only interact with your intended public interface.

The Vendor Directory (vendor/)

Concept: A local physical copy of all external dependencies stored inside your project.

• Behavior: Run go mod vendor to create a folder containing all source code for your dependencies.

myproject/
├── go.mod
├── main.go
└── vendor/           # Contains the actual source of uuid, chi, etc.
    └── github.com/

• Why: Crucial for "Air-gapped" environments or CI/CD pipelines where you cannot rely on the internet to fetch code during a build.

Module Replacement (replace directive)

Concept: Overriding a remote dependency with a different source (usually local).

• Behavior: Tells the compiler: "When you look for this URL, look at this local folder instead."

go mod edit -replace github.com/user/dep=../local-dep

• Why: Essential for local testing when developing two modules simultaneously.
• Note: These must be removed before merging/releasing.

Reference Guides

Crucial Commands

Summary Table