Go Package Structure & Modules - Architecture Guide

Package Structure & Modules

Category: Systems Architecture Topic: Dependency Management

Concept

Go programs are organized into packages, which are the units of code compilation and reuse. A Go project typically starts with a go.mod file that defines the module name and dependencies. Packages within a module are organized in directories beneath the module root. The module system replaced the older GOPATH-based workflow starting with Go 1.11, enabling better dependency management, versioning, and reproducibility.

Why It Exists

Before Go modules, developers relied on the GOPATH directory structure, which had limitations:

Single version of each dependency across all projects
Difficulty using different versions of the same library
No way to publish private modules easily
$GOPATH/src layout was cumbersome for monorepos and multi-project setups

Modules solve these by providing:

Explicit dependency declarations in go.mod
Versioned dependencies with go.sum checksums
Replace directives for local development
Retraction of faulty versions
Semantic import paths (e.g., github.com/user/repo/v2)

How It Works

The `go.mod` File

The go.mod file is the heart of the module system. Its minimal form:

module example.com/myproject

go 1.22

Key directives:

Directive	Description
`module`	Module path (URL-like, e.g., `github.com/user/repo`)
`go`	Minimum Go version required
`require`	Direct dependencies with versions
`exclude`	Exclude a specific version
`replace`	Replace a dependency with local path or version
`retract`	Remove or declare a version as unusable

`go.sum` File

go.sum contains checksums (SHA-256) of module contents at the recorded versions. It ensures reproducible builds: go mod tidy updates both go.mod and go.sum. The format is:

example.com/mydep v1.2.3 h1
example.com/mydep v1.2.3/go.mod h1

Direct vs Indirect Dependencies

Direct: Listed in go.mod require section. Your code imports them.
Indirect: Not directly imported by your code, but pulled in by your direct dependencies. Listed as // indirect in go.mod if declared, or only in go.sum.

`go mod` Commands

Command	Purpose
`go mod init <name>`	Create new `go.mod`
`go mod tidy`	Add missing dependencies, remove unused, update `go.sum`
`go mod download`	Download modules to local cache
`go mod verify`	Verify module contents against checksums
`go mod why`	Explain why a dependency is needed
`go mod graph`	Print module dependency graph

Package Organization

Within a module, packages are defined by directories containing Go source files. Each file starts with package name. Example layout:

myproject/
├── go.mod
├── main.go          // package main
├── utils/
│   └── helpers.go   // package utils
└── api/
    └── clients.go   // package api

Packages should be small and focused. The main package produces an executable; all others are libraries.

Internal Packages

The internal directory name is reserved: packages under .../internal/ are only importable by code within the same module tree. This is a compile-time restriction, not runtime.

// Package internal only importable by this module
package internal

import "fmt"

func Secret() string {
    return "secret stuff"
}

External Dependencies

Third-party code is fetched via the Go module proxy (proxy.golang.org) and verified via checksums. Example adding a dependency:

go get github.com/some/library@v1.2.3

Example

Initializing a new module and using a standard library package:

# Create new project
go mod init github.com/example/myproject

# main.go
package main

import (
    "fmt"
    "math"
)

func main() {
    // Using math package from standard library
    val := math.Pi
    fmt.Printf("Pi is %v\n", val)
    
    // Using a third-party dependency later:
    // go get github.com/some/crypto
    // import "github.com/some/crypto"
}

Running the project:

go run main.go
# Output: Pi is 3.141592653589793

Step-by-Step Execution

go mod init: Creates go.mod with module path and Go version go 1.22.
go get some/dep: Fetch some/dep from module proxy, record v1.0.0 in go.mod require block, add SHA checksums to go.sum.
go mod tidy: Analyzes source code, adds any missing imports to go.mod, removes unused dependencies, ensures go.sum checksums match.
go build or go run: Compiler reads go.mod, resolves all dependencies (direct + indirect), compiles code + dependencies into a single binary.
Import path resolution: The compiler prepends the module path to package names. import "fmt" resolves to standard library; import "github.com/user/repo/v2" fetches from module proxy.

Internals

Module Path Syntax

The module path follows URL conventions as a prefix for import paths (e.g., github.com/user/repo means imports like github.com/user/repo/pkg/foo).

Version Selection

When go get runs without a version, Go selects the latest matching constraints recorded in go.mod.

`go.sum` Checksums

Each module version has a recorded SHA-256 hash. During go build, the runtime verifies local modules against these checksums.

Module Mirror and Cache

Module proxy: proxy.golang.org serves module versions over HTTPS.
Module cache: ~/go/pkg/mod stores downloaded modules locally across projects.

`replace` Directive

Allows substituting a dependency with a local path or different version:

module example.com/myproject

go 1.22

require github.com/old/repo v1.0.0

replace github.com/old/repo => ./local/repo/v1.0.0

Complexity Matrix

Aspect	Complexity
Initial setup	`O(1)` - `go mod init`
Adding deps	`O(log n)` - proxy lookup, checksum verification
Building	`O(n)` - resolves full dependency graph
`go mod tidy`	`O(n)` - analyzes all source files

Common Mistakes

Not running go mod tidy: Leads to missing dependencies in builds, especially after moving code.
Using go get without version: Can pull unstable/latest versions; always pin versions in production.
Having go.sum checked into VCS unnecessarily: go.sum ensures reproducible builds and MUST be committed.
Forgetting // indirect: Explicit annotations prevent go get warnings.
Module path mismatches: Import paths in source code must strictly match the module path declared in go.mod.

Production Considerations

Commit go.mod and go.sum: Vital for reproducible builds across CI/CD environments.
Use semantic import paths: v2, v3 allow breaking changes without URL conflicts.
Private modules: Configure private module proxies or replace directives for non-public code.
Avoid GOPATH workflow: Standardize on Go Modules completely.
Dependency auditing: Use go list -m all and go vet for continuous security checks.

Interview Questions

Beginner Track

It defines the module's import path, minimum required Go version, and list of direct/indirect dependencies.

go.mod defines expected versions, whereas go.sum stores direct SHA-256 cryptographic checksums to verify reproducibility and prevent tampering.

Senior & Architecture Track

Use Go workspaces (go.work) for multi-module local coordination or a single top-level module if services share heavy domains.

Useful for local fork testing or bug fixing. Pitfall: replace directives in non-main modules are ignored when imported by higher-level modules.

Follow-Up Questions

Can you have multiple go.mod files in a single project? When would you use go.work?
How do you handle optional dependencies in Go?
What's the difference between go get -u and go get package@version?
How do you deal with a dependency that doesn't follow semantic versioning?

Practical Exercise

# Set up a Go project with a module and dependencies:

# 1. Initialize
go mod init github.com/yourname/sde3-prep

# 2. Add dependency
go get github.com/google/uuid

# 3. Clean up and verify
go mod tidy
go build ./...

# 4. Inspect outputs
cat go.mod
cat go.sum

Comments