DEV Community: Fer Rios

Go HTTP middleware explained: what it is, how it works, and how to build your own

Fer Rios — Mon, 22 Jun 2026 14:31:52 +0000

This is part 2 of 2 in the series Go HTTP middleware from scratch. If you're new to Go types, → read part 1 first.

The same code keeps showing up everywhere

You're building an HTTP server. Every request needs a unique ID for tracing. Every request needs to check authentication. Every request needs its duration logged. The naive approach: copy that code into every handler.

// Without middleware — same boilerplate in every single handler
func getUserHandler(w http.ResponseWriter, r *http.Request) {
    // Auth check — copy/pasted from every other handler
    token := r.Header.Get("Authorization")
    if token == "" {
        http.Error(w, "unauthorized", http.StatusUnauthorized)
        return
    }

    // Request ID — copy/pasted from every other handler
    requestID := uuid.New().String()
    log.Printf("requestID=%s handling getUser", requestID)

    // actual handler logic finally starts here...
}

Do this across 20 handlers, and you have a maintenance nightmare. Change the auth logic once, and you have to update 20 files.

Middleware is the Go way to solve this. Write the cross-cutting logic once, wrap it around your handlers, and never think about it again.

What is this post about

What middleware is and how Go's HTTP model makes it natural.
How the http.Handler interface works, the foundation everything builds on.
How to write your own middleware from scratch.
How to chain multiple middleware together.
How to pass data through the chain using context.
Tips for advanced usage: ordering, third-party routers, and common pitfalls.

The foundation: the http.Handler interface

As I mentioned in the first part of this serie, everything in Go's HTTP stack is built on one tiny interface:

// This is the entire http.Handler interface — just one method.
// Any type that has a ServeHTTP method satisfies it automatically.
type Handler interface {
    ServeHTTP(ResponseWriter, *Request)
}

If you've read the previous posts in this series, you'll recognize this pattern. Go interfaces are just method signatures. Any Go type with ServeHTTP(ResponseWriter, *Request) is automatically an HTTP handler. No registration, no declaration. If you remember, http.HandlerFunc is a convenience type that lets you turn a plain function into an http.Handler:

// HandlerFunc is a function type that also implements http.Handler.
// This is how you write handlers without creating a struct.
type HandlerFunc func(ResponseWriter, *Request)

func (f HandlerFunc) ServeHTTP(w ResponseWriter, r *Request) {
    f(w, r)
}

This means these two ways of writing a handler are equivalent:

// Option A: using http.HandleFunc, to convert a plain function 
// to a HandlerFunc type
http.HandleFunc("/hello", func(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintln(w, "hello")
})

// Option B: a struct implementing http.Handler
type HelloHandler struct{}

func (h HelloHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintln(w, "hello")
}

Most people use option A for simple handlers. The struct approach becomes useful when your handler needs to hold state (like a database client).

What is middleware?

Middleware is a function that:

Accepts an http.Handler.
Returns a new http.Handler.
Does something before and/or after calling the original handler.

// This is the shape of every middleware in Go.
// It wraps a handler and returns a new one.
func MyMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Do something BEFORE the handler runs
        // (auth check, logging, adding context...)

        next.ServeHTTP(w, r) // call the actual handler

        // Do something AFTER the handler runs
        // (log the response, record timing...)
    })
}

The next parameter is the handler this middleware wraps. Calling next.ServeHTTP(w, r) passes control forward, like handing a baton in a relay race.

The relay race explained

Here's the mental model that makes middleware click:

Request comes in
      │
      ▼
┌─────────────────┐
│   Middleware 1    ← does its work (e.g. logs start time)
│       │         
│       ▼         
│  Middleware 2     ← does its work (e.g. checks auth)
│       │         
│       ▼         
│    Handler        ← does the actual business logic
│       │         
│       ▼         
│  Middleware 2     ← does its work after (e.g. checks result)
│       │         
│       ▼         
│  Middleware 1     ← does its work after (e.g. logs duration)
└─────────────────┘
      │
      ▼
Response goes out

Each middleware wraps the next layer. Code before next.ServeHTTP runs on the way in. Code after runs on the way out. This is sometimes called the "onion model."

Building three real middleware functions

Let's build three practical middleware functions and chain them together. You can find the repo here.

But before writing any code, here's how the project is laid out. You will get a clearer understanding of how a Golang project should be structured if you read this post first about Go Packages. Each middleware gets its own file inside a shared middleware package, and cmd/server/main.go wires everything together.

go-middleware-examples/
├── go.mod
├── cmd/
│   └── server/
│       └── main.go            ← entry point — registers routes and chains middleware
└── internal/
    └── middleware/
        ├── requestid.go       ← RequestID middleware + context key + getter
        ├── logger.go          ← Logger middleware + responseWriter wrapper
        ├── auth.go            ← Auth middleware
        └── chain.go           ← Chain helper for readable middleware composition

A few decisions worth noting:

All middleware lives under internal/middleware/, it's private to this module. If you later wanted to publish this middleware as a reusable library for other projects, it would move to pkg/middleware/ instead.
Each middleware gets its own file even though they all declare package middleware. This keeps each one focused and easy to find, requestid.go only ever deals with request IDs, auth.go only ever deals with authentication.
The context key (RequestIDKey) and its getter (GetRequestID) live in the same file as the middleware that sets it (requestid.go). Anything that reads the request ID imports the middleware package and calls middleware.GetRequestID(ctx), never reaching into the context directly. You can know more about Go contexts here.
cmd/server/main.go stays thin, it only registers handlers and chains middleware together. No middleware logic lives there.

From the root directory (go-middleware-examples), run the following commands to create your Go project, and install the uuid package:

go mod init github.com/<your-username>/go-middleware-examples
go get github.com/google/uuid

You can name your project as you want. I usually name my projects according to my GitHub app repo name.

Here's the go.mod for reference:

module github.com/FerRiosCosta/go-middleware-examples

go 1.26.3

require github.com/google/uuid v1.6.0 // indirect

Now let's build each file.

Request ID middleware

Please consider the first comment line, which specifies where the file should be created. This middleware attaches a unique ID to every request. Useful for tracing a single request through your logs.

// internal/middleware/requestid.go
package middleware

import (
    "context"
    "net/http"

    "github.com/google/uuid"
)

// key is an unexported type for context keys in this package.
// Using a custom type prevents collisions with keys from other packages.
// (Two packages both using the string "requestID" would overwrite each other.)
type key string

// RequestIDKey is the context key for the request ID.
// Exported so handlers in other packages can retrieve it.
const RequestIDKey key = "requestID"

// RequestID generates a unique ID for every incoming request,
// stores it in the context, and adds it to the response headers.
func RequestID(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Generate a new UUID for this request.
        id := uuid.New().String()

        // Store the ID in a new context derived from the request's context.
        // r.Context() returns the existing context, we build on top of it,
        // not replace it, so any previously set values are preserved.
        ctx := context.WithValue(r.Context(), RequestIDKey, id)

        // Add the ID to the response header.
        // This lets clients (and load balancers) correlate their logs with yours.
        w.Header().Set("X-Request-ID", id)

        // This is the line from the previous explanation:
        // create a copy of the request with the new context attached,
        // then pass it to the next handler in the chain.
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

// GetRequestID is a helper to retrieve the request ID from a context.
// Handlers call this instead of reaching into the context directly.
func GetRequestID(ctx context.Context) string {
    id, _ := ctx.Value(RequestIDKey).(string)
    return id
}

Logger middleware

Logs every request: method, path, duration, and status code. But, before looking at the full code, let's first try to understand how this logger middleware works under the hood.

What is http.ResponseWriter?

Before looking at the code, it helps to understand the type we're about to wrap.

http.ResponseWriter is an interface, every handler you write receives one as its first argument. It's how your handler sends a response back to the client: the status code, the headers, and the body.

// http.ResponseWriter is an interface with three methods:
type ResponseWriter interface {
    Header() http.Header         // get/set response headers
    Write([]byte) (int, error)   // write the response body
    WriteHeader(statusCode int)  // write the status code (200, 404, 500...)
}

A typical handler uses it like this:

func myHandler(w http.ResponseWriter, r *http.Request) {
    w.WriteHeader(http.StatusOK)        // write the status code
    w.Write([]byte("hello!"))            // write the body
}

The problem: you can't read the status code back

Here's the catch. http.ResponseWriter lets you write a status code, but it has no method to read it back afterward. There's no w.StatusCode() you can call. Once you write it, it's gone, sent straight to the client over the network.

This is a problem for our Logger middleware. Remember the relay race model: Logger calls next.ServeHTTP(w, r), waits for the handler to finish, and only then logs the result. But by the time the handler finishes, it has already called w.WriteHeader(404) (or whatever status it chose), and Logger has no way to find out what that status was. The information is gone.

The solution: wrap it in our own struct

To solve this, we create our own type that:

Embeds the original http.ResponseWriter, so it still behaves exactly the same way for the handler
Adds a field to remember the status code
Intercepts the one method we care about (WriteHeader) to save the value before passing it through.

// responseWriter wraps http.ResponseWriter to capture the status code.
// http.ResponseWriter doesn't expose the status code after it's written,
// so we intercept WriteHeader to save it.
type responseWriter struct {
    http.ResponseWriter            // embed the original, we get all its methods for free
    statusCode         int         // the status code the handler wrote
}

The embedded http.ResponseWriter is the key part. In Go, embedding a type inside a struct means the outer struct automatically gets all of the embedded type's methods, for free, with no extra code. So our responseWriter already has Header(), Write(), and WriteHeader() just by embedding http.ResponseWriter. As far as the handler is concerned, our responseWriter looks and behaves exactly like a normal http.ResponseWriter, because it satisfies the same interface.

The only thing left to do is override WriteHeader, the one method we actually need to intercept:

// WriteHeader intercepts the status code before passing it through.
func (rw *responseWriter) WriteHeader(code int) {
    rw.statusCode = code               // save it for logging
    rw.ResponseWriter.WriteHeader(code) // pass it through to the real writer
}

This is the trick: when our responseWriter defines its own WriteHeader method, that one overrides the embedded version. So when a handler calls w.WriteHeader(404), it actually calls our version, which saves 404 into rw.statusCode, then calls the original ResponseWriter.WriteHeader(404) so the client still receives the real response. The handler never notices anything different happened.

Now Logger can read wrapped.statusCode after the handler finishes, something that was impossible with a plain http.ResponseWriter.

Here's the full middleware:

// internal/middleware/logger.go
package middleware

import (
    "log/slog"
    "net/http"
    "time"
)

// responseWriter wraps http.ResponseWriter to capture the status code.
// http.ResponseWriter doesn't expose the status code after it's written,
// so we intercept WriteHeader to save it.
type responseWriter struct {
    http.ResponseWriter            // embed the original — we get all its methods for free
    statusCode         int         // the status code the handler wrote
}

// WriteHeader intercepts the status code before passing it through.
func (rw *responseWriter) WriteHeader(code int) {
    rw.statusCode = code               // save it for logging
    rw.ResponseWriter.WriteHeader(code) // pass it through to the real writer
}

// Logger logs each request's method, path, status code, duration,
// and request ID (if set by the RequestID middleware).
func Logger(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Record when the request arrived.
        start := time.Now()

        // Wrap the ResponseWriter so we can capture the status code.
        wrapped := &responseWriter{
            ResponseWriter: w,
            statusCode:     http.StatusOK, // default to 200 if WriteHeader is never called
        }

        // Call the next handler — this is where the actual work happens.
        next.ServeHTTP(wrapped, r)

        // By the time we reach here, the handler has finished.
        // We can now log everything we know about this request.
        slog.Info("request",
            "method",     r.Method,
            "path",       r.URL.Path,
            "status",     wrapped.statusCode,
            "duration",   time.Since(start).String(),
            "requestID",  GetRequestID(r.Context()), // set by RequestID middleware
        )
    })
}

Auth middleware

Checks for a valid Bearer token before allowing the request through.

This one looks more complicated than RequestID and Logger at first glance, it's a function that returns a function that returns a function. Let's slow down and unpack why, before looking at the full code.

Why Auth needs an extra layer

RequestID and Logger both have this shape:

func RequestID(next http.Handler) http.Handler {
    // ...
}

One input (next), one output (http.Handler). That's the standard middleware shape we covered earlier.

But Auth needs something extra: a configurable token. Every other middleware works the same way no matter what, but Auth needs to know which token counts as valid, and that's different for every app (and usually comes from an environment variable, not a hardcoded value).

So Auth can't just be a middleware, it needs to be a function that produces a middleware, once you tell it which token to check:

// Auth is NOT middleware itself.
// It's a function that BUILDS a middleware, once you give it a token.
func Auth(validToken string) func(http.Handler) http.Handler {
    // ...
}

Breaking down the three layers

Here's the same function with each layer labeled:

//        ┌─── Layer 1: takes your config (the token)
//        │
func Auth(validToken string) func(http.Handler) http.Handler {
    //                        └─── Layer 2: this is what gets returned —
    //                             a real middleware function, with the
    //                             standard func(http.Handler) http.Handler shape

    return func(next http.Handler) http.Handler {
        //     └─── Layer 2 starts here. This is now a normal middleware,
        //          identical in shape to RequestID and Logger.

        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            //   └─── Layer 3: the actual handler logic that runs per-request.
            //        This is the same as the inner function in every middleware
            //        you've already seen.

            // ... auth check logic goes here ...
        })
    }
}

Three layers, three different jobs:

Layer	Runs when	Job
1 — `Auth(validToken)`	Once, at startup	Receives your config (the token)
2 — `func(next http.Handler) http.Handler`	Once, when you build your middleware chain	Receives the next handler to wrap
3 — `func(w, r)`	On every single request	Does the actual work — checks the header

Why this pattern, and how you use it

The payoff is that calling Auth looks almost identical to using RequestID or Logger, you just add one extra set of parentheses to pass in the token:

// RequestID and Logger take no config, pass them directly
middleware.RequestID
middleware.Logger

// Auth takes config, call it first to get back a real middleware
middleware.Auth("my-secret-token")   // ← this call returns a middleware function

That's it. Auth("my-secret-token") runs Layer 1 immediately and hands you back Layer 2, a normal func(http.Handler) http.Handler, ready to be used exactly like any other middleware in your Chain:

Chain(mux,
    middleware.RequestID,                // sets the request ID first
    middleware.Logger,                   // then logs — sees the ID
    middleware.Auth("my-secret-token"),  // called with () — returns a middleware
)

If this still feels unfamiliar, it helps to compare it to something simpler, a function that builds a greeting function:

// Same shape, much simpler example.
// MakeGreeter takes a name and returns a NEW function
// that already "remembers" that name.
func MakeGreeter(name string) func() string {
    return func() string {
        return "Hello, " + name + "!"
    }
}

sayHiToAlice := MakeGreeter("Alice") // returns a function
fmt.Println(sayHiToAlice())          // "Hello, Alice!"

Auth does the exact same thing, it just returns a middleware function instead of a greeting function. Once you see MakeGreeter, Auth(validToken) stops looking complicated; it's the same "function that builds and returns another function" pattern, just doing more useful work inside.

Now here's the full code with that context in mind:

// internal/middleware/auth.go
package middleware

import (
    "net/http"
    "strings"
)

// Auth checks for a valid Bearer token in the Authorization header.
// If the token is missing or invalid, it returns 401 and stops the chain —
// next.ServeHTTP is never called, so the handler never runs.
func Auth(validToken string) func(http.Handler) http.Handler {
    // Return a middleware function — this pattern lets us configure
    // middleware with parameters (the token) while keeping the standard shape.
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            // Read the Authorization header.
            authHeader := r.Header.Get("Authorization")

            // Check the format: "Bearer <token>"
            parts := strings.SplitN(authHeader, " ", 2)
            if len(parts) != 2 || parts[0] != "Bearer" {
                // Respond with 401 and stop. next.ServeHTTP is never called.
                http.Error(w, "missing or malformed token", http.StatusUnauthorized)
                return
            }

            // Validate the token.
            // In a real app you'd verify a JWT or look up the token in a database.
            if parts[1] != validToken {
                http.Error(w, "invalid token", http.StatusUnauthorized)
                return
            }

            // Token is valid — pass the request to the next handler.
            next.ServeHTTP(w, r)
        })
    }
}

Chaining middleware together

Now let's wire everything up. But first, create your own secret token and paste it into your main.go file, you can create it from here. Remember to also include that token in your request. You can see how to do it in the section about testing the server.

The standard Go way to chain middleware is to nest the calls:

// cmd/server/main.go
package main

import (
    "fmt"
    "net/http"

    "github.com/yourname/myapp/internal/middleware"
)

// userHandler is the actual business logic.
// It doesn't know about auth, logging, or request IDs —
// all of that is handled by middleware before it runs.
func userHandler(w http.ResponseWriter, r *http.Request) {
    // Retrieve the request ID that was set by RequestID middleware.
    id := middleware.GetRequestID(r.Context())
    fmt.Fprintf(w, "hello! your request ID is %s\n", id)
}

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/user", userHandler)

    // Chain middleware by wrapping from the outside in.
    // The outermost middleware runs first on the way IN,
    // and last on the way OUT.
    //
    // RequestID must wrap Logger — not the other way around.
    // Logger only ever sees the *r it directly receives. If RequestID
    // runs AFTER Logger, Logger is holding the original request,
    // not the enriched one RequestID produces — so the ID would be empty.
    //
    // Execution order for a request:
    //   RequestID → Logger → Auth → userHandler
    //               (then back out in reverse)
    handler := middleware.RequestID(
        middleware.Logger(
            middleware.Auth("your-secret-token")(
                mux,
            ),
        ),
    )

    http.ListenAndServe(":8080", handler)
}

Testing the server

# Start the server
go run ./cmd/server

# Valid request — should return 200 with a request ID
curl -H "Authorization: Bearer your-secret-token" http://localhost:8080/user

# Missing token — should return 401
curl http://localhost:8080/user

# Invalid token — should return 401
curl -H "Authorization: Bearer wrong-token" http://localhost:8080/user

Server logs:

2026/06/21 20:46:13 INFO request method=GET path=/user status=200 duration=7.208µs requestID=e667de2b-310a-4038-9891-2d948613e93b
2026/06/21 20:46:15 INFO request method=GET path=/user status=200 duration=90.667µs requestID=23a61730-4dd2-4b01-8dc5-986fbcb46436

Every request gets logged. The request ID ties your server log to the X-Request-ID header in the response, if a client reports a bug, they can give you their request ID and you can find exactly that request in your logs.

Best practices

Order matters, RequestID before Logger, Logger before Auth

The outermost middleware runs first on the way in and last on the way out. Two rules drive the order here:

RequestID must be outermost (or at least before Logger), Logger can only read context values from the exact *http.Request it was handed. context.WithValue and r.WithContext don't mutate the original request, they return a new one. If RequestID runs after Logger, Logger is stuck holding the original, un-enriched request, GetRequestID will always come back empty. If you are new to Go contexts, you can check this post about it; it explains everything you need to know about Go contexts.
Logger should wrap Auth, so that failed (401) requests still get logged, not just successful ones.

// Good order
Chain(mux,
    middleware.RequestID, // outermost: enriches the request first
    middleware.Logger,    // sees the enriched request — requestID shows up in logs
    middleware.Auth(...), // innermost: blocks invalid requests, but they're still logged
)

// Bad order — this is the bug you'll hit if you swap these two
Chain(mux,
    middleware.Logger,    // ← runs first, but hasn't seen RequestID's context yet
    middleware.RequestID, // ← enriches the request, but only for handlers AFTER this point
    middleware.Auth(...),
)
// Logger's slog.Info call reads r.Context() from its OWN copy of r —
// which was captured before RequestID ever ran. requestID="" every time.

The general rule: any middleware that reads a context value must be positioned after (further in than) the middleware that sets it.

Never call next.ServeHTTP more than once

Calling it twice sends a double response, which causes a panic in Go's HTTP stack. Always return after an early exit:

// Good — returns after writing the error
if !valid {
    http.Error(w, "unauthorized", http.StatusUnauthorized)
    return // ← critical: stops execution here
}
next.ServeHTTP(w, r)

// Bad — falls through and calls next anyway
if !valid {
    http.Error(w, "unauthorized", http.StatusUnauthorized)
    // missing return — next.ServeHTTP still runs!
}
next.ServeHTTP(w, r)

Use unexported context keys

Always define context keys as a custom unexported type, not a plain string. This prevents key collisions between packages:

// Bad — any package using the string "userID" will collide
ctx = context.WithValue(ctx, "userID", id)

// Good — only this package can access this key
type key string
const userIDKey key = "userID"
ctx = context.WithValue(ctx, userIDKey, id)

Tips for advanced users

Tip 1: Use a third-party router for cleaner middleware

The standard library's http.ServeMux applies middleware to all routes at once. If you need per-route middleware (auth on some routes, not others), a router like chi or gorilla/mux makes this clean:

r := chi.NewRouter()

r.Use(middleware.Logger)    // applies to all routes
r.Use(middleware.RequestID) // applies to all routes

r.Group(func(r chi.Router) {
    r.Use(middleware.Auth("secret")) // applies only to routes in this group
    r.Get("/admin", adminHandler)
    r.Get("/users", usersHandler)
})

r.Get("/health", healthHandler) // no auth required

Tip 2: Capture response body size

Extend responseWriter to also track bytes written — useful for monitoring:

type responseWriter struct {
    http.ResponseWriter
    statusCode int
    bytes      int
}

func (rw *responseWriter) Write(b []byte) (int, error) {
    n, err := rw.ResponseWriter.Write(b)
    rw.bytes += n // track how many bytes were written
    return n, err
}

Tip 3: Recover from panics

A panic in any handler crashes the goroutine handling that request. A recovery middleware catches it and returns a 500 instead of crashing:

func Recovery(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        defer func() {
            if err := recover(); err != nil {
                slog.Error("panic recovered", "error", err, "requestID", GetRequestID(r.Context()))
                http.Error(w, "internal server error", http.StatusInternalServerError)
            }
        }()
        next.ServeHTTP(w, r)
    })
}

Add this as the outermost middleware so it catches panics from every layer:

Chain(mux,
    middleware.Recovery,  // outermost — catches panics from every layer below
    middleware.RequestID, // sets the request ID next
    middleware.Logger,    // sees the enriched request — requestID shows up in logs
    middleware.Auth("secret"),
)

Summary

Middleware is just a function that wraps a handler and returns a new one. Everything else follows from that.

Three things to take away:

next.ServeHTTP(w, r.WithContext(ctx)), this is the line that passes the request forward with an enriched context. Understanding it unlocks the whole pattern.
Order matters, outermost middleware runs first on the way in, last on the way out. Anything that sets a context value (like RequestID) must come before anything that reads it (like Logger), or the value will be empty.
Always return after early exits, calling next.ServeHTTP after writing an error response causes a double response panic.

The three middleware functions in this post, RequestID, Logger, and Auth, are production-ready. Add Recovery and you have a solid foundation for any Go HTTP server.

Go types explained: the foundation you need before writing HTTP handlers

Fer Rios — Mon, 22 Jun 2026 14:22:54 +0000

A quick introduction to Go types

According to https://go.dev/ref/spec#Types, in Go, a type specifies a set of values, along with operations and methods specific to those values.

This is something fundamental about Go: you can define your own types based on existing ones, and those types can have methods attached to them.

You've probably seen this with structs:

// A struct type — groups fields together
type User struct {
    Name  string
    Email string
}

// A method attached to the User type
func (u User) Greet() string {
    return "Hello, " + u.Name
}

But Go lets you do the same thing with any type, including functions.

Function types

In Go, functions are values. You can assign them to variables, pass them as arguments, and — most importantly here, define a named type based on a function signature:

// This defines a new type called "Greeter"
// whose underlying type is a function that takes a string and returns a string.
type Greeter func(name string) string

Now Greeter is a type, just like int or string or User. Any function with the right signature (func(string) string) is automatically a Greeter.

// This function matches the Greeter signature
func sayHello(name string) string {
    return "Hello, " + name
}

// So we can assign it to a Greeter variable
var g Greeter = sayHello

fmt.Println(g("Alice")) // Hello, Alice

Attaching methods to a function type

Here's where it gets interesting. Because Greeter is now a named type, you can attach methods to it, exactly like you would with a struct:

// A method on a function type — this is valid Go
func (g Greeter) Shout(name string) string {
    return strings.ToUpper(g(name)) // call the function, then shout it
}

fmt.Println(g.Shout("Alice")) // HELLO, ALICE

This might look strange at first. A function with a method? But it makes perfect sense in Go. Greeter is just a type, and any type can have methods.

Why this matters for HTTP handlers

Now that you understand function types, let's look at how Go's HTTP package uses this exact pattern to make your life easier.

Go's HTTP package has two things that are easy to confuse at first: http.Handler and http.HandlerFunc. They sound almost identical, but they play different roles: one is an interface, and one is a type.

http.Handler — the interface

An HTTP handler in GO is an object or function responsible for processing an incoming HTTP request and constructing an HTTP response.

http.Handler is the interface that represents anything that can handle an HTTP request. It has exactly one method:

// http.Handler is an interface — a contract.
// It says: "I don't care what you are.
// As long as you have a ServeHTTP method, you can handle HTTP requests."
type Handler interface {
    ServeHTTP(ResponseWriter, *Request)
}

http.ResponseWriter: An interface used to construct and send the HTTP response (setting headers, status codes, and writing the body).
*http.Request: A pointer to a struct containing all incoming data (headers, query parameters, URL path, and request body).

So, to be recognized as a handler, a type must implement the http.Handler interface by defining a ServeHTTP.

This is what Go's HTTP server actually works with internally. When you call http.ListenAndServe, the second argument must be an http.Handler:

// The second argument is an http.Handler —
// Go's server calls ServeHTTP on it for every incoming request.
http.ListenAndServe(":8080", myHandler)

Any type that has a ServeHTTP method satisfies this interface automatically. A struct, a function type, anything, as long as it has that one method.

http.HandlerFunc — the type

Here's the problem: writing a full struct with a ServeHTTP method for every single handler in your app is verbose. Most of the time, you just want to write a plain function:

// This is clean and simple, just a function.
// But it's NOT an http.Handler because it has no ServeHTTP method.
func greetUser(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintln(w, "Hello!")
}

This function can't be passed to http.ListenAndServe directly, it's not an http.Handler. It has no ServeHTTP method.

This is exactly the problem http.HandlerFunc solves. It's a named function type with a ServeHTTP method attached, which makes it an http.Handler:

// HandlerFunc is a named type based on a function signature.
// Any function that matches func(ResponseWriter, *Request)
// is automatically compatible with this type.
type HandlerFunc func(ResponseWriter, *Request)

// ServeHTTP is attached to HandlerFunc.
// It just calls the function itself — f is the function, so f(w, r) runs it.
// This single method is what makes HandlerFunc satisfy http.Handler.
func (f HandlerFunc) ServeHTTP(w ResponseWriter, r *Request) {
    f(w, r)
}

Now Go can convert your plain function into an http.HandlerFunc, which has ServeHTTP, which satisfies http.Handler.

You can imagine that this is what Go does under the hood:

var fn http.HandlerFunc = greetUser  // convert the function to HandlerFunc
var h  http.Handler    = fn          // HandlerFunc satisfies http.Handler

But, in practice, you never write these steps manually; you use the http.HandleFunc function.

http.HandleFunc

// Registers the "/hello" route on the default mux.
// http.HandleFunc converts greetUser to HandlerFunc internally —
// you never see that conversion happen.
http.HandleFunc("/hello", greetUser)

http.HandleFunc register a route on the default server mux. It takes a path and a handler function, converts the function to a HandlerFunc internally, and registers it.

http.HandleFunc actually uses http.HandlerFunc internally, it's just hiding it from you:

// This is roughly what http.HandleFunc does under the hood:
func HandleFunc(pattern string, handler func(ResponseWriter, *Request)) {
    // converts your function to HandlerFunc, then registers it
    DefaultServeMux.Handle(pattern, HandlerFunc(handler))
    //                                ^^^^^^^^^^^^^
    //                                HandlerFunc TYPE doing the conversion
}

So http.HandleFunc is convenience on top of http.HandlerFunc. When you call http.HandleFunc("/hello", greetUser), Go silently wraps greetUser in an http.HandlerFunc and registers it. You only need to use http.HandlerFunc directly when you're building something lower-level, like middleware, where you need to return an http.Handler explicitly.

Putting it all together

Here's the full picture in one example:

// A plain function — clean and simple to write
func greetUser(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintln(w, "Hello!")
}

// A struct handler — useful when you need to hold state like a DB client
type UserHandler struct {
    db *sql.DB // injected dependency
}

func (h *UserHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    // can use h.db here
    fmt.Fprintln(w, "Hello from UserHandler!")
}

func main() {
    mux := http.NewServeMux()

    // http.HandleFunc converts greetUser → HandlerFunc → Handler automatically
    mux.HandleFunc("/hello", greetUser)

    // UserHandler already has ServeHTTP — it satisfies http.Handler directly
    mux.Handle("/user", &UserHandler{db: myDB})

    // Both routes are registered on the same mux —
    // the server calls ServeHTTP on whichever one matches the request path.
    http.ListenAndServe(":8080", mux)
}

TIP: Use a plain function (via HandlerFunc) for simple handlers. Use a struct for handlers that need dependencies like a database client or a config object. The server doesn't care which one you chose — it just calls ServeHTTP.

Summary

Think of it this way:

http.Handler is the job description: "must be able to handle HTTP requests"
http.HandlerFunc is one way to fulfill that job description: "a plain function that handles HTTP requests"
Your struct with a ServeHTTP method is another way to fulfill it

The server only knows about http.Handler. It never knows whether you used a struct or a HandlerFunc — and it doesn't need to. That's the power of the interface.

Go Context Package

Fer Rios — Wed, 17 Jun 2026 00:08:53 +0000

What is context

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.

Go Packages and Modules explained

Fer Rios — Thu, 11 Jun 2026 00:37:56 +0000

What is a package?

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)
    }
}

💡No business logic in main.go. Ever. It's a wiring diagram, not an application.

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.