Mastering Go Modules and Packages: A Complete Guide

1. Go Packages

In Go a package groups one or more .go source files. Built‑in packages include fmt, strconv, strings, sort, errors, time, encoding/json, os, io and others.

Packages fall into three categories:

System built‑in packages

Custom packages written by developers

Third‑party packages that must be downloaded, e.g. github.com/shopspring/decimal for precise floating‑point arithmetic.

2. Go Modules (go mod)

Before Go 1.11 custom code had to reside under GOPATH. Since Go 1.11 modules allow a project to live anywhere, and from Go 1.13 the GOPATH is no longer required.

2.1 Initialise a module

Run go mod init <module-name> in the project directory. Example for a folder demo02: go mod init demo02 This creates a go.mod file that records the module path and its dependencies.

2.2 Common go mod commands

go mod tidy

– adds missing modules and removes unused ones. go mod download – downloads modules needed for the current build. go list -m all – lists all required modules.

3. Creating Custom Packages

A package corresponds to a directory containing one or more .go files. Every file in the directory must start with the same package <name> declaration.

Key rules :

All files in a directory belong to a single package; a package cannot span multiple directories.

Package names may differ from the directory name but cannot contain hyphens.

A package named main is the entry point and produces an executable.

3.1 Example package calc

package calc

// Upper‑case identifiers are exported, lower‑case are private
var a = 100 // private variable
var Age = 20 // exported variable

func Add(x, y int) int {
    return x + y
}

func Sum(x, y int) int {
    return x - y
}

3.2 Importing the package

In main.go import the package and use its exported symbols:

package main

import (
    "fmt"
    "demo02/calc"
)

func main() {
    c := calc.Add(10, 20)
    fmt.Println(c)
}

3.3 Import styles

Single‑line: import "fmt" Multi‑line: import ("fmt" "os") Anonymous import (side‑effects only): import _ "github.com/lib/pq" Alias import to avoid name conflicts:

import db "github.com/go-sql-driver/mysql"

4. The init() Function

When a package is imported, its init() function is executed automatically. The function has no parameters or return values and cannot be called explicitly.

Package initialisation order:

The compiler builds a dependency tree starting from the main package.

At runtime the deepest imported package is initialised first (its init() runs), then the next level up, and so on until main is initialised.

5. Using Third‑Party Packages

Third‑party modules can be discovered on https://pkg.go.dev/. Typical workflow:

Initialise the module with go mod init <module-name>.

Download the required package, e.g. go get github.com/shopspring/decimal. The decimal package provides arbitrary‑precision decimal arithmetic and avoids float precision loss.

Import the package in source code and use its API.

Run go mod tidy to add any missing dependencies and prune unused ones.

6. Overview of Common Go Commands

go build – compiles the package and its dependencies into an executable or archive.

go install – compiles and installs the package and its dependencies to the module cache.

go get – downloads or updates the specified module and its dependencies, then builds them.

go doc – prints documentation for a Go identifier.

godoc – serves documentation for a package (built‑in since Go 1.5).

go test – runs tests for the package.

go list – lists information about the specified packages.

go fix / go tool fix – updates source code from older Go versions to newer syntax.