Every Go developer encounters context.Context early. It shows up in function signatures everywhere — HTTP handlers, database calls, AWS SDK methods, gRPC stubs. Most beginners copy the pattern without fully understanding it, passing context.Background() everywhere and moving on.

That works until it doesn't. A Lambda that ignores context hangs past its timeout. A database query that ignores context keeps running after the HTTP client disconnected.

Context is a built-in package in the Go standard library that enables the propagation of cancellation signals, deadlines, and values across API boundaries and between processes.

Why Context Exists

Before context was added to the standard library in Go 1.7, there was no standard way to answer these questions across a call chain:

• Should this operation still be running, or has the caller given up?

• Is there a deadline this operation must finish by?

• What request-scoped data (trace ID, user ID, auth token) should flow with this call?

What is really a Context?

The context.Context type is an interface with exactly four methods. Every context implements all four.

type Context interface {
    Deadline() (deadline time.Time, ok bool)
    Done() <-chan struct{}
    Err() error
    Value(key any) any
}

Here's what each one does.

Deadline() — does this context have an expiry?

deadline, ok := ctx.Deadline()

Returns the time when this context will automatically cancel, and a boolean indicating whether a deadline was set at all. If you created the context with context.Background() or context.WithCancel(), there's no deadline — ok will be false. If you used context.WithTimeout() or context.WithDeadline(), ok is true and deadline tells you exactly when it expires.

You don't call this often in day-to-day code, but it's useful when you need to decide whether there's enough time left to start an expensive operation.

Done() — tell me when to stop

case <-ctx.Done():

Returns a channel that gets closed the moment the context is cancelled or times out. You listen to this channel, typically inside a select statement, to know when to abandon work. Until the context ends, the channel blocks. When it closes, your code unblocks and can clean up.

This is the method you'll use most often in loops and long-running operations.

Err() — why did we stop?

err := ctx.Err()

Returns nil while the context is still alive. Once the context ends, it returns one of two sentinel errors:

• context.DeadlineExceeded — the timeout fired automatically

• context.Canceled — someone called cancel() manually

This is how you distinguish between "we ran out of time" and "something upstream decided to abort". Both mean stop, but they mean different things for logging and debugging.

Value() — carry data across function calls

id := ctx.Value(myKey)

Retrieves a value stored in the context by key. This is used to pass request-scoped data — like a request ID, a user ID, or an auth token — through a chain of function calls without adding extra parameters to every function signature.

One important rule: use a custom unexported type for your keys (not a plain string), otherwise different packages might accidentally overwrite each other's values.

Context's creation

With contexts, there is a tree structure. The parent context is located at the root of the context tree, and the newly derived context from the parent context is called the child context. Through the parent context, four types of contexts can be derived using the four With methods, and each new context can continue to derive child contexts, making the whole structure look like a tree.

Parent Context

There are two ways to create the parent context: an empty context still with no functionality.

context.Background()

ctx := context.Background()

Use this at the top of your program — in main(), in init(), or as the starting point when creating a server. It's the foundation everything else derives from.

context.TODO()

Semantically identical to context.Background() at runtime, but signals intent: "I know a context should go here, I haven't figured out which one yet."

ctx := context.TODO() // placeholder — replace with a real context later

Use it when you're refactoring code to add context support and haven't wired up the full chain yet. It's a marker for future work, not a production pattern.

Child Contexts

To make the context useful, we use one of the following child contexts:

func WithCancel(parent Context) (ctx Context, cancel CancelFunc)
func WithDeadline(parent Context, deadline time.Time) (Context, CancelFunc)
func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc)
func WithValue(parent Context, key, val interface{}) Context

context.WithCancel()

Returns a copy of the parent context with a new Done channel, plus a cancel function. Calling cancel closes the Done channel and marks the context as canceled.

ctx, cancel := context.WithCancel(context.Background())
defer cancel() // always call cancel

Always call cancel. If you don't, the context and everything derived from it leaks until the parent is canceled or the program exits. defer cancel() immediately after creation is the idiomatic pattern.

context.WithTimeout() and context.WithDeadline()

These set an automatic cancellation time. WithTimeout takes a duration; WithDeadline takes an absolute time.Time.

// Cancel after 5 seconds
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

// Cancel at a specific moment
deadline := time.Now().Add(5 * time.Second)
ctx, cancel := context.WithDeadline(context.Background(), deadline)
defer cancel()

WithTimeout(parent, d) is shorthand for WithDeadline(parent, time.Now().Add(d)). They behave identically. When the deadline passes, the context's Done channel is closed automatically and Err() returns context.DeadlineExceeded.

Still call defer cancel() even with a timeout — if your operation finishes before the deadline, calling cancel releases the timer resources immediately rather than waiting for it to fire.

context.WithValue

Creates a child context from the parent context for value passing. Used for passing context information, such as the unique request ID and trace ID, for link tracing and configuration passing.

ctx := context.WithValue(context.Background(), authToken, "XYZ_123")
fmt.Println(ctx.Value(authToken))

How Cancellation Propagates

Remember, contexts form a tree. When a parent context is canceled, all contexts derived from it are canceled too — automatically, immediately, without any extra code.

parent, cancelParent := context.WithCancel(context.Background())

child1, cancelChild1 := context.WithCancel(parent)
child2, cancelTimeout := context.WithTimeout(parent, 10*time.Second)

// Canceling the parent cancels both children
cancelParent()

// child1.Err() == context.Canceled
// child2.Err() == context.Canceled

This is the mechanism that makes context useful across a call tree. An HTTP handler creates a context with a timeout. It passes that context to a database call, which passes it to a connection pool, which passes it to a network read. When the HTTP client disconnects, the handler's context is canceled, and that cancellation flows down through every layer automatically.

Real-World Use Cases

HTTP Servers: Respecting Client Disconnects

Go's net/http package attaches a context to every incoming request. The context is canceled when the client disconnects or the server's write deadline fires. Your handler receives it via r.Context().

The following is a fully runnable example. It simulates a slow db.Search using a select with time.After, shows what happens when the client disconnects mid-query, and adds a middleware that attaches a request ID to the context, so every layer of the call chain can log it without it being passed as an explicit argument. You can find the repo here:

package main

import (
    "context"
    "errors"
    "fmt"
    "log/slog"
    "net/http"
    "os"
    "time"

    "github.com/google/uuid"
)

// contextKey is an unexported type for context keys in this package.
// Using a custom type prevents collisions with keys from other packages
// that might also store something under a plain string like "request_id".
type contextKey string

const keyRequestID contextKey = "request_id"

// withRequestID attaches a request ID to the context.
func withRequestID(ctx context.Context, id string) context.Context {
    return context.WithValue(ctx, keyRequestID, id)
}

// requestIDFromContext retrieves the request ID from the context.
// Returns an empty string if no ID was set — callers should handle that gracefully.
func requestIDFromContext(ctx context.Context) string {
    id, _ := ctx.Value(keyRequestID).(string)
    return id
}

var logger = slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
    ReplaceAttr: func(_ []string, a slog.Attr) slog.Attr {
        if a.Key == slog.TimeKey {
            return slog.Attr{}
        }
        return a
    },
}))

// requestIDMiddleware generates a unique ID for every incoming request,
// attaches it to the context, and sends it back in the response header.
// Every function below the handler can read it from ctx for logging —
// without it being passed as a function argument anywhere.
func requestIDMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        requestID := uuid.NewString()

        ctx := withRequestID(r.Context(), requestID)
        w.Header().Set("X-Request-ID", requestID)

        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

// Search simulates a slow database query that respects context cancellation.
// It reads the request ID directly from ctx — no extra parameter needed.
func Search(ctx context.Context, query string, delay time.Duration) ([]string, error) {
    requestID := requestIDFromContext(ctx)

    logger.Info("db.Search started",
        "request_id", requestID,
        "query", query,
        "simulated_delay", delay,
    )

    select {
    case <-time.After(delay):
        logger.Info("db.Search completed", "request_id", requestID, "query", query)
        return []string{"result-1", "result-2", "result-3"}, nil

    case <-ctx.Done():
        logger.Warn("db.Search aborted",
            "request_id", requestID,
            "query", query,
            "reason", ctx.Err(),
        )
        return nil, ctx.Err()
    }
}

func searchHandler(w http.ResponseWriter, r *http.Request) {
    requestID := requestIDFromContext(r.Context())

    query := r.URL.Query().Get("q")
    if query == "" {
        query = "gophers"
    }

    delay := 5 * time.Second
    if d := r.URL.Query().Get("delay"); d != "" {
        if parsed, err := time.ParseDuration(d); err == nil {
            delay = parsed
        }
    }

    logger.Info("handler started",
        "request_id", requestID,
        "query", query,
        "client", r.RemoteAddr,
    )

    // r.Context() carries both the cancellation signal AND the request ID value.
    // Search receives one ctx and gets everything it needs from it.
    results, err := Search(r.Context(), query, delay)
    if err != nil {
        if errors.Is(err, context.Canceled) {
            logger.Warn("client disconnected before query finished, no response sent",
                "request_id", requestID,
            )
            return
        }
        logger.Error("unexpected search error", "request_id", requestID, "error", err)
        http.Error(w, "search failed", http.StatusInternalServerError)
        return
    }

    logger.Info("handler finished — sending response",
        "request_id", requestID,
        "result_count", len(results),
    )
    fmt.Fprintf(w, "results: %v\n", results)
}

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/search", searchHandler)

    // Wrap the mux — every request gets a request ID attached to its context
    handler := requestIDMiddleware(mux)

    logger.Info("server listening on :8080")
    logger.Info("try: curl -v 'http://localhost:8080/search?q=gophers&delay=5s'")
    logger.Info("cancel with Ctrl+C before 5s to trigger client disconnect")

    if err := http.ListenAndServe(":8080", handler); err != nil {
        logger.Error("server error", "error", err)
        os.Exit(1)
    }
}

Before running, initialize the module and fetch the uuid package, which is in charge of creating random uuids for the incoming requests:

go mod init example/context-demo
go get github.com/google/uuid

To test the cancellation path:

# Terminal 1 — start the server
go run main.go

# Terminal 2 — send a request with a 5s delay, then hit Ctrl+C before it finishes
curl 'http://localhost:8080/search?q=gophers&delay=5s'
# Press Ctrl+C after ~2 seconds

You should see in the server logs:

level=INFO msg="handler started" request_id=4a1f9c2e-... query=gophers client=127.0.0.1:PORT
level=INFO msg="db.Search started" request_id=4a1f9c2e-... query=gophers simulated_delay=5s
level=WARN msg="db.Search aborted" request_id=4a1f9c2e-... query=gophers reason="context canceled"
level=WARN msg="client disconnected before query finished, no response sent" request_id=4a1f9c2e-...

Notice the same request_id appears in every log line, from the middleware, through the handler, all the way into Search, without it ever being passed as a function argument. It traveled through the context.

You can also verify the ID was sent back in the response header:

curl -v 'http://localhost:8080/search?q=gophers&delay=5s'| grep X-Request-ID
# X-Request-ID: 4a1f9c2e-...

To test the happy path

Let the query finish before disconnecting:

curl 'http://localhost:8080/search?q=gophers&delay=2s'
# Wait for it to complete

level=INFO msg="handler started" request_id=9b3d7f1a-... query=gophers client=127.0.0.1:PORT
level=INFO msg="db.Search started" request_id=9b3d7f1a-... query=gophers simulated_delay=2s
level=INFO msg="db.Search completed" request_id=9b3d7f1a-... query=gophers
level=INFO msg="handler finished — sending response" request_id=9b3d7f1a-... result_count=3

The key is the select inside Search. It blocks on two channels simultaneously: time.After(delay) represents the slow query, and ctx.Done() represents the client. Whichever fires first wins. If the client disconnects, ctx.Done() closes and Search returns context.Canceled immediately, without waiting for the timer.

This example shows both things context is good for working together in one flow: the cancellation signal (ctx.Done()) stops the query when the client leaves, and the value (request_id) flows through every layer for correlated logging, all through the same single ctx argument.

Database Calls: Enforcing Query Timeouts

Most database drivers in Go accept a context. Pass one with a timeout to prevent slow queries from holding connections indefinitely.

func getUserByID(ctx context.Context, db *sql.DB, userID string) (*User, error) {
    // Give the query 3 seconds — no matter what the caller's deadline is
    queryCtx, cancel := context.WithTimeout(ctx, 3*time.Second)
    defer cancel()

    var user User
    err := db.QueryRowContext(queryCtx,
        "SELECT id, name, email FROM users WHERE id = $1", userID,
    ).Scan(&user.ID, &user.Name, &user.Email)
    if err != nil {
        if errors.Is(err, context.DeadlineExceeded) {
            return nil, fmt.Errorf("user query timed out after 3s: %w", err)
        }
        return nil, fmt.Errorf("querying user %s: %w", userID, err)
    }

    return &user, nil
}

Notice that queryCtx derives from ctx — the caller's context. If the caller's context is already canceled (client disconnected, Lambda timed out), queryCtx is canceled immediately regardless of the 3-second timeout. The child inherits the parent's cancellation, but can set a tighter deadline on top of it.

Checking for Cancellation in Long Loops

If your function does significant work in a loop, check ctx.Err() periodically so it can exit early when canceled.

func processFiles(ctx context.Context, files []string) error {
    for _, file := range files {
        // Check at the top of each iteration
        if err := ctx.Err(); err != nil {
            return fmt.Errorf("processing canceled after %s: %w", file, err)
        }

        if err := processFile(ctx, file); err != nil {
            return fmt.Errorf("processing %s: %w", file, err)
        }
    }
    return nil
}

Without this check, a canceled context doesn't stop the loop — it only stops operations that accept and check the context themselves. If processFile takes 500ms and you have 1000 files, a cancellation mid-loop still runs all remaining iterations.

Common Mistakes and Gotchas

Passing context.Background() everywhere. It works, but it opts every operation out of cancellation and timeout propagation. If your HTTP handler times out, your database queries keep running. Pass the incoming context through your call chain — that's the whole point.

Not calling cancel(). Every WithCancel, WithTimeout, and WithDeadline must have its cancel called. The Go runtime cannot garbage-collect a context until cancel is called or the parent is canceled. defer cancel() right after creation is non-negotiable.

Storing contexts in structs. The Go documentation is explicit: do not store contexts in structs. A context is for a single operation, not for the lifetime of an object. Pass it as the first argument to every function that needs it.

// Wrong
type Service struct {
    ctx context.Context // don't do this
}

// Right
func (s *Service) DoWork(ctx context.Context) error { ... }

Using context.WithValue for function dependencies. If you're pulling a database client out of a context, something has gone wrong. Use dependency injection or package-level variables for clients and config. Context values are for request-scoped metadata.

Ignoring ctx.Err() in loops. Passing a context to a function that calls ctx.Err() isn't enough if your own loop never checks it. Long-running loops need explicit cancellation checks.

Wrapping errors without checking for cancellation. When a context-aware call fails, check whether the cause is cancellation before deciding how to handle it:

if err != nil {
    if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
        // The operation was stopped — not necessarily a bug
        return err
    }
    // Real error — log, alert, or return
    return fmt.Errorf("unexpected error: %w", err)
}

Summary

The context package gives every Go operation a standard way to answer three questions: should I keep running, when must I finish by, and what metadata flows with this request?

The key things to take away:

• context.Background() is the root — use it at program entry points.

• WithCancel, WithTimeout, and WithDeadline create derived contexts — always defer cancel().

• Cancellation propagates from parent to child automatically — wire it through your call chain and it works for free.

• Pass context as the first argument to every function that does I/O — HTTP, database, AWS SDK, gRPC.

• WithValue is for cross-cutting metadata like trace IDs, not for dependencies.

• Check ctx.Err() explicitly in long-running loops.

In Go, every Go program is made up of packages. A package is a directory of .go files that share the same package declaration. The primary purpose of packages is to help you isolate and reuse code.

myapp/
├── main.go       ← package main
└── math/
    ├── add.go    ← package math
    └── sub.go    ← package math

Both add.go and sub.go declare package math. They can call each other's functions directly — no import needed within the same package.

Inside a package, every .go file should begin with a package {name} statement which indicates the name of the package that the file is a part of. Every exported identifier (capitalized name) in that directory is accessible to anyone who imports the package.

Here's what that looks like in practice:

// math/add.go
package math

// pi is an unexported variable.
var pi = 3.14159

// Add returns the sum of two integers.
// Exported — starts with a capital letter.
func Add(a, b int) int {
    return a + b
}

// math/sub.go
package math

// Exported — starts with a capital letter.
func Subtract(a, b int) int {
    
    return a-b
}

// main.go
package main

import (
    "fmt"
    "github.com/yourname/myapp/math"
)

func main() {
    fmt.Println(math.Add(3, 4))      // 7
    fmt.Println(math.Subtract(10, 3)) // 7
    // fmt.Println(math.pi) — compile error: unexported
}

Two rules to remember:

• Capital letter = exported (public). Lowercase = unexported (private to the package).

• One package per directory. One directory per package.

What is a module?

If a package is a folder, a module is the whole project — a tree of packages with a name, a Go version requirement, and a list of external dependencies.

When you start a Go project, you create a module, and inside that module, there will be packages.

Every Go project has exactly one go.mod file at its root. That file defines the module. Here's what a real one looks like:

module github.com/yourname/weather-cli

go 1.21

require (
    github.com/aws/aws-sdk-go-v2 v1.24.0
    github.com/aws/aws-sdk-go-v2/service/s3 v1.47.0
    gopkg.in/yaml.v3 v3.0.1
)

Three things in every go.mod:

• module — the module path. This is the base import path for every package in your project. It's usually your GitHub URL, but it can be anything.

• go — the minimum Go version your code requires.

• require — the external dependencies your module needs, each pinned to an exact version.

go.sum — the lockfile

Alongside go.mod lives go.sum. You never edit this by hand. It contains cryptographic checksums for every dependency (and their dependencies) your module uses:

github.com/aws/aws-sdk-go-v2 v1.24.0 h1:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=
github.com/aws/aws-sdk-go-v2 v1.24.0/go.mod h1:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=

go.sum guarantees that the code you download is bit-for-bit identical to what was there when you first added the dependency. It's your protection against supply chain attacks and "works on my machine" problems. Always commit both go.mod and go.sum.

Working with modules day to day

Creating a new module

So, let's say you want to start a new project: you create the folder first, then you create your go.mod file, passing your module path to it (github.com/yourname/myapp).

mkdir myapp && cd myapp
go mod init github.com/yourname/myapp

This creates go.mod with your module path. That's it — you're ready to write Go.

Adding a dependency

go get github.com/aws/aws-sdk-go-v2/service/s3@latest

go get does three things: downloads the package, adds it to go.mod, and updates go.sum. After running it your go.mod will have a new require entry.

You can also just write the import in your code and run go mod tidy — it figures out what's missing and adds it:

go mod tidy

go mod tidy is the command you'll run most often. It adds missing dependencies and removes unused ones, keeping go.mod clean.

Upgrading a dependency

# Upgrade to the latest minor/patch version
go get github.com/aws/aws-sdk-go-v2@latest

# Upgrade to a specific version
go get github.com/aws/aws-sdk-go-v2@v1.25.0

Removing a dependency

Remove the import from your code, then run:

go mod tidy

go mod tidy will remove the require entry automatically if nothing in your code imports it anymore.

Viewing your dependency tree

go mod graph

This prints the full dependency graph — your dependencies, their dependencies, and so on. Useful for debugging version conflicts.

Vendoring dependencies

For environments without internet access (some CI setups, air-gapped servers), you can vendor all dependencies into a local vendor/ directory:

go mod vendor

After vendoring, go build uses vendor/ instead of the module cache. Commit vendor/ to your repo and your build never needs to call the internet.

How modules and packages connect

Let's make the relationship tangible. Say you run:

go get github.com/spf13/cobra@v1.8.0

Your go.mod now contains:

require (
    github.com/spf13/cobra v1.8.0
)

Cobra is a module at github.com/spf13/cobra. Inside that module, there are multiple packages:

github.com/spf13/cobra          ← the root package
github.com/spf13/cobra/doc      ← generates documentation
github.com/spf13/cobra/completions ← shell completions

When you import github.com/spf13/cobra in your code, you're importing one specific package from that module. The module is what gets versioned and downloaded; the package is what you actually use in your code.

import (
    "github.com/spf13/cobra"     // imports the root package of the cobra module
)

One require in go.mod, many importable packages available. That's the module/package split.

Package main is special

Every Go program needs exactly one package main with exactly one main() function. That's the entry point. Everything else is a library package — it exports functions and types but can't be run directly.

// This is a runnable program
package main

import "fmt"

func main() {
    fmt.Println("hello from main")
}

// This is a library — can't be run, only imported
package greet

import "fmt"

func Hello(name string) string {
    return fmt.Sprintf("Hello, %s!", name)
}

You can have multiple package main files in a project — but each one must live in its own directory. This is exactly what the cmd/ convention is for, which we'll get to shortly.

How imports work

The import path is always: module path (from go.mod) + directory path from the module root.

module github.com/yourname/myapp   ← module path

myapp/
├── go.mod
└── internal/
    └── config/
        └── config.go              ← import path: github.com/yourname/myapp/internal/config

// Importing your own packages — always use the full module path
import "github.com/yourname/myapp/internal/config"

// Importing from the standard library — no module path needed
import "fmt"
import "net/http"
import "encoding/json"

// Importing a third-party package — use its full module path + sub-path
import "github.com/spf13/cobra"
import "github.com/aws/aws-sdk-go-v2/service/s3"

Aliasing imports

When two packages have the same name, or when a name is too long, you can alias the import:

import (
    "fmt"

    // Alias to avoid conflict with standard library math
    gomath "github.com/yourname/myapp/math"

    // Alias for readability
    yaml "gopkg.in/yaml.v3"
)

func main() {
    fmt.Println(gomath.Add(1, 2))
    _ = yaml.Marshal
}

The blank identifier import

Sometimes you import a package only for its side effects — database drivers are the classic example. The _ alias tells Go "import this but don't use its name":

import (
    "database/sql"
    _ "github.com/lib/pq" // registers the postgres driver via init()
)

Without the _, Go's compiler would complain about an unused import and refuse to compile.

A practical project structure

Here's a real structure that scales from small to large. This is what most production Go projects converge on:

myapp/
├── go.mod
├── go.sum
├── Makefile
│
├── cmd/
│   ├── server/
│   │   └── main.go     ← the HTTP server entry point
│   └── worker/
│       └── main.go     ← the background worker entry point
│
├── internal/
│   ├── handler/
│   │   ├── handler.go
│   │   └── handler_test.go
│   ├── store/
│   │   ├── postgres.go
│   │   └── store.go
│   └── config/
│       └── config.go
│
└── pkg/
    └── validate/
        ├── validate.go
        └── validate_test.go

Let's walk through each directory.

cmd/ — entry points

One subdirectory per runnable binary. Each contains a single main.go. The main.go should do almost nothing except wire dependencies together and start the program.

// cmd/server/main.go
package main

import (
    "log/slog"
    "net/http"
    "os"

    "github.com/yourname/myapp/internal/config"
    "github.com/yourname/myapp/internal/handler"
    "github.com/yourname/myapp/internal/store"
)

func main() {
    cfg := config.Load()

    db, err := store.Connect(cfg.DatabaseURL)
    if err != nil {
        slog.Error("failed to connect to database", "error", err)
        os.Exit(1)
    }

    h := handler.New(db)

    slog.Info("starting server", "port", cfg.Port)
    if err := http.ListenAndServe(":"+cfg.Port, h); err != nil {
        slog.Error("server failed", "error", err)
        os.Exit(1)
    }
}

internal/ — private application code

The internal/ directory is enforced by the Go toolchain. Packages inside internal/ can only be imported by code in the parent directory tree. Code outside your module cannot import them — not even if they find your repo on the internet.

This is how you keep implementation details private:

// internal/config/config.go
package config

import "os"

type Config struct {
    Port        string
    DatabaseURL string
    LogLevel    string
}

// Load reads config from environment variables.
// This is internal — callers outside this module can't import it.
func Load() Config {
    port := os.Getenv("PORT")
    if port == "" {
        port = "8080"
    }
    return Config{
        Port:        port,
        DatabaseURL: os.Getenv("DATABASE_URL"),
        LogLevel:    os.Getenv("LOG_LEVEL"),
    }
}

// internal/store/store.go
package store

import (
    "context"
    "database/sql"
    "fmt"

    _ "github.com/lib/pq"
)

// Store handles database operations.
type Store struct {
    db *sql.DB
}

func Connect(dsn string) (*Store, error) {
    db, err := sql.Open("postgres", dsn)
    if err != nil {
        return nil, fmt.Errorf("open db: %w", err)
    }
    if err := db.Ping(); err != nil {
        return nil, fmt.Errorf("ping db: %w", err)
    }
    return &Store{db: db}, nil
}

// GetUser fetches a user by ID.
func (s *Store) GetUser(ctx context.Context, id string) (string, error) {
    var name string
    err := s.db.QueryRowContext(ctx, "SELECT name FROM users WHERE id = $1", id).Scan(&name)
    if err != nil {
        return "", fmt.Errorf("get user %s: %w", id, err)
    }
    return name, nil
}

pkg/ — reusable public code

pkg/ contains packages that are safe to import by external projects. Put things here that are genuinely reusable across projects — validation logic, utility functions, shared types. If in doubt, use internal/ instead.

// pkg/validate/validate.go
package validate

import (
    "errors"
    "strings"
)

// Email returns an error if the given string is not a valid email address.
// Simple check — not RFC 5322 compliant, but good enough for most cases.
func Email(email string) error {
    if email == "" {
        return errors.New("email is required")
    }
    if !strings.Contains(email, "@") || !strings.Contains(email, ".") {
        return errors.New("email is invalid")
    }
    return nil
}

// Required returns an error if the string is empty or whitespace only.
func Required(field, value string) error {
    if strings.TrimSpace(value) == "" {
        return fmt.Errorf("%s is required", field)
    }
    return nil
}

A practical example: a CLI tool

GitHub Repository: https://github.com/FerRiosCosta/weather-cli

Let's make this concrete with a small but complete project — a CLI that fetches weather for a city. It shows package structure, separation of concerns, and how packages talk to each other. Let's create the following directory structure:

weather-cli/
├── go.mod
├── cmd/
│   └── weather/
│       └── main.go
└── internal/
    ├── api/
    │   └── api.go        ← HTTP client for weather API
    └── display/
        └── display.go    ← formats output for the terminal

Open your terminal and create the following directories and files:

mkdir weather-cli
cd weather-cli
mkdir -p cmd/weather
touch cmd/weather/main.go
mkdir -p internal/api
touch internal/api/api.go
mkdir -p internal/display
touch internal/display/display.go

Open VSCode while you are in the weather-cli root directory:

code .

Go to the Openweathermap portal and create an account if you don't have one. Once you have created it, your API key will be enabled after a couple of hours.

Open a new terminal from VScode since we are going to run our program from here, but first we need to export our API KEY.

export WEATHER_API_KEY=<your-api-key>

Now, initialize your module (or project) by running the following command:

go mod init

You should see your new go.mod file created now:

module github.com/FerRiosCosta/weather-cli

go 1.26.3

Start filling the files you created with the code below:

// internal/api/api.go
package api

import (
	"context"
	"encoding/json"
	"fmt"
	"net/http"
)

// WeatherResponse holds the data we care about from the API.
type WeatherResponse struct {
	City        string  `json:"name"`
	Temperature float64 `json:"main.temp"`
	Description string  `json:"weather.0.description"`
}

// apiResponse mirrors the actual nested JSON structure from OpenWeatherMap.
// Go's JSON decoder doesn't support dot notation like `json:"main.temp"` —
// nested fields require nested structs.
//
// The API returns something like:
//
//	{
//	  "name": "Asuncion",
//	  "main": { "temp": 28.4 },
//	  "weather": [{ "description": "partly cloudy" }]
//	}
type apiResponse struct {
	Name string `json:"name"`
	Main struct {
		Temp float64 `json:"temp"`
	} `json:"main"`
	Weather []struct {
		Description string `json:"description"`
	} `json:"weather"`
}

// Client makes requests to the weather API.
type Client struct {
	apiKey     string
	httpClient *http.Client
}

// NewClient creates and returns a new Client configured with the given API key.
// This is a constructor function — Go doesn't have classes or `new` keywords,
// so by convention we define a function named New<TypeName> to build a struct.
func NewClient(apiKey string) *Client {
	return &Client{
		// Store the API key so every request this client makes can use it.
		// It's set once here and reused — no need to pass it on every call.
		apiKey: apiKey,
		// Create a default HTTP client for making requests.
		// We initialize it here rather than inside GetWeather so it's
		// reused across calls — http.Client maintains a connection pool
		// internally, so reusing it is more efficient than creating a new
		// one each time.
		httpClient: &http.Client{},
	}
}

// GetWeather fetches current weather for the given city.
func (c *Client) GetWeather(ctx context.Context, city string) (*WeatherResponse, error) {
	url := fmt.Sprintf(
		"https://api.openweathermap.org/data/2.5/weather?q=%s&appid=%s&units=metric",
		city, c.apiKey,
	)

	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
	if err != nil {
		return nil, fmt.Errorf("create request: %w", err)
	}

	resp, err := c.httpClient.Do(req)
	if err != nil {
		return nil, fmt.Errorf("fetch weather: %w", err)
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("unexpected status: %d", resp.StatusCode)
	}

	// Decode into the nested API struct first.
	var raw apiResponse
	if err := json.NewDecoder(resp.Body).Decode(&raw); err != nil {
		return nil, fmt.Errorf("decode response: %w", err)
	}

	// Guard against an empty weather array — the API should always return
	// at least one entry, but defensive code is good code.
	description := ""
	if len(raw.Weather) > 0 {
		description = raw.Weather[0].Description
	}

	// Return the clean, flat struct callers actually care about.
	return &WeatherResponse{
		City:        raw.Name,
		Temperature: raw.Main.Temp,
		Description: description,
	}, nil
}

// internal/display/display.go
package display

import (
    "fmt"
    "io"

    "github.com/yourname/weather-cli/internal/api"
)

// Weather prints a formatted weather summary to w.
func Weather(w io.Writer, data *api.WeatherResponse) {
    fmt.Fprintf(w, "City:        %s\n", data.City)
    fmt.Fprintf(w, "Temperature: %.1f°C\n", data.Temperature)
    fmt.Fprintf(w, "Conditions:  %s\n", data.Description)
}

// cmd/weather/main.go
package main

import (
    "context"
    "log/slog"
    "os"

    "github.com/yourname/weather-cli/internal/api"
    "github.com/yourname/weather-cli/internal/display"
)

func main() {
    if len(os.Args) < 2 {
        fmt.Fprintln(os.Stderr, "usage: weather <city>")
        os.Exit(1)
    }

    city := os.Args[1]
    apiKey := os.Getenv("WEATHER_API_KEY")
    if apiKey == "" {
        slog.Error("WEATHER_API_KEY environment variable is required")
        os.Exit(1)
    }

    client := api.NewClient(apiKey)

    weather, err := client.GetWeather(context.Background(), city)
    if err != nil {
        slog.Error("failed to get weather", "city", city, "error", err)
        os.Exit(1)
    }

    display.Weather(os.Stdout, weather)
}

Run it:

go run ./cmd/weather Asuncion

City:        Asuncion
Temperature: 28.4°C
Conditions:  partly cloudy

Notice how each package has one job:

• api — knows how to talk to the weather API. Nothing else.

• display — knows how to format output. Nothing else.

• cmd/weather/main.go — wires them together. Nothing else.

Adding a second output format (JSON, CSV) means a new file in display/. Adding a second weather provider means a new file in api/. Neither change touches the other.

Common gotchas

1. Circular imports — Go forbids them

Package A cannot import package B if package B imports package A. Go will refuse to compile.

// This will not compile
package a imports package b
package b imports package a  ← circular — error

The fix: extract the shared type into a third package that neither A nor B imports from each other.

2. Package name vs directory name

The directory name and the package name don't have to match — but they should. The one common exception is main: the directory is usually named after the binary (server, worker, weather), but the package is always package main.

// Directory: cmd/server/
// File: main.go
package main  // always "main", not "server"

3. Trying to have multiple packages in one directory

Every .go file in a directory must declare the same package name (with the exception of _test.go files, which can use package foo_test for black-box testing). This is a compile error:

myapp/
├── server.go    ← package server
└── handler.go   ← package handler  ← ERROR: can't mix packages in one directory

4. Exporting by accident

If you capitalize a function name, it's exported — immediately accessible to anyone who imports the package. This isn't always what you want, especially for internal helpers. Default to lowercase until you know something needs to be public.

Summary

Go's package and module system is built on a few simple rules that compound into something powerful.

Four things to take away:

• A package is a folder — everything in it shares a namespace, capital letters are exported.

• A module is a versioned collection of packages — defined by go.mod, locked by go.sum.

• Use cmd/ for entry points, internal/ for private code, pkg/ for reusable public code.

• go mod tidy is your best friend — run it whenever you add, remove, or change dependencies.

The project structure in this post is the same one I'll use for every project on this blog. Every Go + Lambda, Go + Kubernetes, and Go + AWS post builds on it. Once it's familiar, you'll recognize it instantly in any Go project you open on GitHub.