HTTP Servers, Handlers & ServeMux Patterns

net/http routes requests through ServeMux to Handler implementations.

Go 1.22 modernized pattern matching so method-aware REST routes work without a third-party router.

Summary

An HTTP server listens on a port, parses requests, and dispatches them to handlers.

http.Server wraps the listener with timeout and TLS knobs.

http.ServeMux maps host, method, and path patterns to handlers.

Handlers implement ServeHTTP or use the HandlerFunc adapter.

Middleware wraps handlers to add logging, auth, and metrics before your business logic runs.

Recipe

Quick-reference recipe card - copy-paste ready.

mux := http.NewServeMux()
mux.HandleFunc("GET /api/health", func(w http.ResponseWriter, r *http.Request) {
    w.WriteHeader(http.StatusOK)
})
mux.HandleFunc("GET /api/users/{id}", func(w http.ResponseWriter, r *http.Request) {
    id := r.PathValue("id")
    fmt.Fprintf(w, `{"id":%q}`, id)
})
srv := &http.Server{Addr: ":8080", Handler: mux, ReadHeaderTimeout: 5 * time.Second}
log.Fatal(srv.ListenAndServe())

When to reach for this:

• Building REST APIs with explicit method and path rules on Go 1.22+.
• Services that must stay stdlib-only without chi or gorilla/mux.
• Sidecars and admin ports that need a handful of well-defined routes.

Working Example

package main
 
import (
    "encoding/json"
    "log"
    "net/http"
    "strings"
    "time"
)
 
type user struct {
    ID   string `json:"id"`
    Name string `json:"name"`
}
 
var users = map[string]user{
    "1": {ID: "1", Name: "Ada"},
    "2": {ID: "2", Name: "Lin"},
}
 
func main() {
    mux := http.NewServeMux()
 
    mux.HandleFunc("GET /api/health", func(w http.ResponseWriter, r *http.Request) {
        w.WriteHeader(http.StatusNoContent)
    })
 
    mux.HandleFunc("GET /api/users/{id}", getUser)
    mux.HandleFunc("POST /api/users", createUser)
 
    api := stripPrefix("/api", mux)
 
    srv := &http.Server{
        Addr:              ":8080",
        Handler:           logging(api),
        ReadHeaderTimeout: 5 * time.Second,
        WriteTimeout:      10 * time.Second,
        IdleTimeout:       60 * time.Second,
    }
    log.Fatal(srv.ListenAndServe())
}
 
func getUser(w http.ResponseWriter, r *http.Request) {
    id := r.PathValue("id")
    u, ok := users[id]
    if !ok {
        http.Error(w, "not found", http.StatusNotFound)
        return
    }
    w.Header().Set("Content-Type", "application/json")
    _ = json.NewEncoder(w).Encode(u)
}
 
func createUser(w http.ResponseWriter, r *http.Request) {
    var in user
    if err := json.NewDecoder(r.Body).Decode(&in); err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }
    in.ID = "3"
    users[in.ID] = in
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusCreated)
    _ = json.NewEncoder(w).Encode(in)
}
 
func stripPrefix(prefix string, h http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        p := strings.TrimPrefix(r.URL.Path, prefix)
        if p == "" {
            p = "/"
        }
        r2 := r.Clone(r.Context())
        r2.URL.Path = p
        h.ServeHTTP(w, r2)
    })
}
 
func logging(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()
        next.ServeHTTP(w, r)
        log.Printf("%s %s %s", r.Method, r.URL.Path, time.Since(start))
    })
}

What this demonstrates:

• Method-specific patterns on a dedicated ServeMux.
• r.PathValue for {id} segments.
• Prefix stripping to mount a sub-router at /api.
• Production-oriented http.Server timeout fields.
• Logging middleware wrapping the entire API tree.

Deep Dive

How It Works

• The listener accepts TCP connections; each connection may serve many keep-alive requests.
• ServeMux matches the longest applicable pattern considering method and host rules.
• The winning handler's ServeHTTP runs on the connection's goroutine unless you spawn work yourself.
• ResponseWriter buffers headers until the first Write or explicit WriteHeader.

Pattern Syntax (Go 1.22+)

Go Notes

// Avoid registering on the global mux in libraries:
// http.HandleFunc(...)  // bad in reusable packages
 
mux := http.NewServeMux() // good: local, testable
 
// Host-scoped routes:
mux.HandleFunc("GET example.com/admin/", adminHandler)

Handler Types

Gotchas

• Using http.DefaultServeMux in libraries - Third-party imports can register conflicting routes. Fix: Pass http.NewServeMux() from main.
• Forgetting ReadHeaderTimeout - Slow clients can hold connections without sending headers. Fix: Set it on every production http.Server.
• Writing body before status on errors - First Write locks status to 200. Fix: Call WriteHeader or http.Error before body bytes.
• Assuming path params work on Go 1.21 - r.PathValue requires Go 1.22+ patterns. Fix: Upgrade Go or use a router like chi.
• Trailing slash mismatches - /users and /users/ are different patterns. Fix: Register both or redirect consistently.
• Spawning unbounded goroutines per request - Can exhaust memory under load. Fix: Use worker pools or bound concurrency with semaphores.

Alternatives

FAQs

Related

• net/http Basics - introductory snippets
• Middleware Chains & Request Context - compose wrappers
• HTTP/2, Timeouts & ReverseProxy - server timeouts and HTTP/2
• Production net/http Configuration Checklist - deploy checklist
• httptest for Handler Integration Tests - test routing

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).