Skip to content
Tutorials Center
My learning

Topics

Lesson 107 of 147 ยท Web and Networking

Handlers, Routing and Middleware

Structure Go web handlers properly - error-returning handlers, middleware chains for logging, panic recovery, request IDs and auth, context values, query and form parsing, JSON handlers and httptest.

The previous lesson gave you a working server with routes. Real services need more than a handler per URL. Every request should be logged, panics must not take a connection down without a good answer, many routes need a signed-in user, and every handler needs to parse input and report mistakes in the same predictable way. Copying that code into fifty handlers is how bugs and security holes appear.

Go's answer is small and composable. A middleware is a function that takes an http.Handler and returns a new http.Handler wrapped around it. Because a handler is just an interface with one method, wrapping needs no framework. This lesson shows the patterns used in real Go services: handlers that return errors, middleware for logging, recovery, request IDs and authentication, per-request values in the request context, careful parsing of paths, queries, forms and JSON, uniform error responses, and how to test all of it with httptest.NewRecorder without opening a port.

To keep the programs small, every example calls the handler directly with mux.ServeHTTP(recorder, request). httptest.NewRequest builds a request and httptest.NewRecorder captures the response. That is exactly how you unit-test handlers, and it needs no network at all. Programs that use method and wildcard patterns start with //go:debug httpmuxgo121=0, which switches on the Go 1.22 routing rules for a single file compiled without a go.mod. In a module with go 1.22 or newer in go.mod, leave that line out.

Handlers that return errors

The standard handler signature has no return value, so error handling is repetitive: every failing branch must write a status and a message and then remember to return. A common improvement is a small adapter type whose function returns an error. One place then decides how each kind of error is shown to the client:

Go An adapter for handlers that return errors

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

The handler body now reads like ordinary Go: parse, look up, return an error. The adapter turns an *HTTPError into its own status, a wrapped ErrNotFound into 404 (see wrapping errors for errors.Is and errors.As), and any other error into a generic 500. Look at the last line: the database message went to the log, and the client only saw internal server error. Never put internal error text in a response; it leaks details an attacker can use.

Middleware: a function that wraps a handler

The shape of every middleware is the same:

Go
func Name(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		// before: inspect or change the request, maybe reject it
		next.ServeHTTP(w, r)
		// after: inspect what happened
	})
}

The returned handler does some work, usually calls next, and may do more work afterwards. It can also not call next, which short-circuits the request (for example when authentication fails). Middleware that needs configuration is a function that returns a middleware: RequireRole("admin").

Wrapping is easier to read with a helper that applies a list of middleware to a handler. The first one in the list should be the outermost layer, so the helper wraps from the end. The program below prints a trace so that you can see the order:

Go The order of middleware layers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

The request travels inward through A, B, stopper, C, the handler, and the response travels back out in reverse order. The second request never reaches C or the handler, because stopper did not call next. Order matters: put recovery and logging on the outside so they see everything that happens inside, and put authentication before the handlers it protects.

You can attach middleware to the whole mux (http.ListenAndServe(addr, Chain(mux, ...))), to a group of routes (a sub-mux), or to one route (mux.Handle("GET /admin", Chain(admin, Authenticate))).

Logging, recovery and request IDs

Three middleware pieces appear in nearly every service.

Logging must report the response status, but http.ResponseWriter has no getter for it. The standard trick is a small wrapper type that embeds the original writer and remembers the status passed to WriteHeader. Embedding means all other methods are forwarded untouched (embedding). Add an Unwrap method so that http.NewResponseController can still reach the real writer for flushing and deadlines.

Recovery turns a panic in any handler into a clean 500 response and a log entry, rather than a dropped connection. It uses defer with recover (panic and recover). The special panic value http.ErrAbortHandler is meant to abort a response quietly, so recovery should re-panic it.

Request IDs tag every request with a unique value. The middleware reuses an incoming X-Request-ID (set by a load balancer) or makes a new one, puts it on the response, and stores it in the request context so that handlers and deeper layers can add it to their own log lines. Storing a value looks like this:

Go
type ctxKey int            // a private type, so no other package can collide with our keys
const requestIDKey ctxKey = 0

ctx := context.WithValue(r.Context(), requestIDKey, id)
next.ServeHTTP(w, r.WithContext(ctx))    // a shallow copy of the request with the new context

r.WithContext returns a new request; the original is never modified. Reading the value back is a type assertion that you hide in a helper function, so callers never see the key. Use context values only for request-scoped data such as IDs, authenticated users and trace spans, never as a way to pass optional function parameters (the context package).

Go Request ID, logging and panic recovery together

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Check the log lines against the answers. The first request got req-1; the second reused the ID that came in the header. The panic was recovered, logged with its ID and turned into a 500. And Logging sees the 500 because Recovery is inside it: the status passes through the wrapper on its way out. If you put Recovery outside Logging, a panic would unwind straight through the logger and no log line would be written for the failed request.

A wrapper like statusRecorder hides optional interfaces of the original writer, such as http.Flusher and http.Hijacker. Code that does w.(http.Flusher) fails on the wrapper. Prefer http.NewResponseController(w).Flush(), which follows Unwrap chains, and keep wrappers minimal.

Authentication and authorization

Authentication asks "who are you?", authorization asks "are you allowed to do this?". Both fit middleware naturally. The first step reads a credential, finds the user, and stores the user in the context. The second checks the user against what the route requires. Splitting them lets you protect a route with one or both:

Go Bearer-token auth with a user in the context

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Notice the status codes. 401 Unauthorized means "we don't know who you are" and should come with a WWW-Authenticate header; 403 Forbidden means "we know who you are, and you may not". Two security details are visible in the code: the token check uses subtle.ConstantTimeCompare so the time to reject does not depend on how many leading characters were right, and the context key is a private empty struct type, so only this package can read or overwrite the user.

This example uses a fixed table of tokens to stay short. Real services verify signed tokens (JWT or similar), look up sessions in a store, or delegate to an identity provider. The middleware shape stays the same: authenticate, put the user in the context, let the next layer decide what the user may do.

Parsing paths, queries and forms

Everything that arrives in a request is a string chosen by someone else. Convert and validate it at the edge of your handler, and answer 400 Bad Request (with a helpful message) when it is wrong. Collect your conversions into small helpers so each handler stays short:

  • Path values: r.PathValue("id"), then strconv.Atoi or strconv.ParseInt.
  • Query values: r.URL.Query() returns a url.Values. A missing key gives "", so decide on a default. Clamp numeric limits (limit=1000000 should not be honored), and check values against an allowed list for things like sort order.
  • Forms: call r.ParseForm() once, then use r.PostForm (body only) or r.Form (body and query merged). r.FormValue("k") calls ParseForm for you and reads from r.Form; r.PostFormValue("k") reads only the body, which is what you want for a POST, so that ?email=... in the URL can't override the body. File uploads use multipart/form-data, where r.ParseMultipartForm(maxMemory) and r.FormFile("field") apply.
Go Validating query strings and forms

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

The last request carries a different email in the URL, but the handler used PostFormValue, so it subscribed the address from the form body. Choosing the right accessor is a small decision that closes a whole class of confusion.

400 fits "the request could not be understood" (a missing parameter, text where a number was expected). 422 Unprocessable Content fits "the request was understood, but the content breaks a rule" (an email without @). Pick one convention for your API and use it consistently.

JSON handlers

A JSON endpoint needs the same four steps every time: check the content type, limit the body size, decode into a struct with strict rules, and write the answer with the right header. Wrap them in helpers once and use them everywhere. The decoding helper below also translates the different failure modes of encoding/json into precise, friendly messages (see JSON for the encoding basics and struct tags for the json:"..." names):

Go A JSON API with strict decoding and a uniform error format

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Every failure has a precise status and the same JSON shape ({"error": {"code": ..., "message": ...}}), so client programs can branch on code instead of parsing sentences. A few choices deserve explanation:

  • DisallowUnknownFields catches typos like "titel" instead of silently ignoring them. For public APIs that must tolerate new fields from newer clients, leave it off.
  • http.MaxBytesReader protects memory. When the limit is exceeded, the decode error unwraps to *http.MaxBytesError, which carries the limit.
  • The extra dec.Token() call rejects a body such as {"a":1} {"b":2}. json.Unmarshal would have rejected it, but a Decoder reads one value and stops.
  • Locking around the map is needed because handlers run concurrently (sync package).
  • Location on a 201 tells the client where the new resource lives.

The REST API lesson builds a whole service from these pieces; it also covers pagination, filtering and PATCH semantics.

More building blocks from the standard library

Before you write your own, know what net/http already offers:

Helper What it does
http.StripPrefix("/static/", h) Removes a path prefix before calling h (often used with http.FileServer)
http.TimeoutHandler(h, d, msg) Answers 503 with msg if h takes longer than d
http.MaxBytesHandler(h, n) Applies MaxBytesReader to every request
http.FileServer(http.Dir("public")) / http.FileServerFS(fsys) Serves static files; pair it with //go:embed to ship them inside the binary
http.NotFoundHandler(), http.RedirectHandler(url, code) Ready-made handlers
http.NewResponseController(w) Flush, set per-request deadlines, hijack, even through wrappers

Middleware libraries exist for CORS, compression, rate limiting and tracing, and they all follow the func(http.Handler) http.Handler shape you just learned, so they combine with your own pieces through Chain.

Testing handlers and middleware

The pieces you have used all along in this lesson are the testing tools: httptest.NewRequest makes a request (and panics on a malformed URL, which is fine in a test), httptest.NewRecorder is a ResponseWriter that stores the status, headers and body, and h.ServeHTTP(rec, req) runs the handler synchronously. After the call you can read rec.Code, rec.Header() and rec.Body, or call rec.Result() to get a real *http.Response, which is the better choice for checking things the way a client sees them (for example, headers set after the first write are not in the result).

A middleware is tested the same way, with a stub as the next handler: assert that it calls next when it should, that it doesn't when it shouldn't, and what it adds to the request. The example below is a table-driven test (table-driven tests). It runs through the testing package from main, since this site cannot run go test; in a real project the same TestXxx functions sit in a _test.go file.

Go Testing a handler and a middleware with httptest.NewRecorder

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Some habits that pay off when testing HTTP code:

  • Test through the whole stack you ship. Build the same mux plus middleware chain that main uses (put its construction in a function like func newRouter(deps) http.Handler), and send requests to that. A test of a bare handler won't notice a wrong route pattern or a missing Authenticate.
  • Inject dependencies (stores, clocks, ID generators) so tests control them; see designing testable code.
  • Use httptest.NewServer when real networking matters: redirects, cookies across requests, timeouts, TLS (NewTLSServer) and anything involving an http.Client. See the HTTP client lesson.
  • Check the contract, not the formatting. For JSON, decode the body and compare fields instead of comparing whole strings, which break when indentation or key order changes.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the signature shape of a middleware in the standard net/http style?

    A middleware takes the next handler and returns a new handler that wraps it, so any number of them can be stacked.
  2. 2. With Chain(h, A, B, C) as defined in this lesson, which runs first when a request arrives?

    Chain wraps from the end of the list, so the first middleware ends up as the outermost layer and sees the request first (and the response last).
  3. 3. Why should Recovery be placed inside Logging in the chain?

    If Recovery is inside, the panic is turned into a normal 500 response before it reaches Logging, which then logs the real status. Outside, the panic would unwind past the logger.
  4. 4. A request has a valid token for a user without the required role. Which status should the middleware send?

    403 means the server knows who you are and refuses the action. 401 is for missing or invalid credentials.
  5. 5. How do you attach a value to the request context in middleware so later handlers can read it?

    Contexts are immutable. context.WithValue returns a new context, and r.WithContext returns a shallow copy of the request that carries it. Use a private key type to avoid collisions.

Summary

  • A middleware is func(http.Handler) http.Handler; it can act before and after next, or stop the request by not calling it. A Chain helper makes the order explicit: the first middleware is the outermost.
  • An error-returning handler adapter centralizes error responses: map known errors to client-safe statuses and log the rest, never leaking internals.
  • Standard middleware: request ID (context value), logging (status-capturing wrapper), recovery (defer + recover), and authentication (user in context, then a separate role check with 401 vs 403).
  • Store request-scoped data in the context with r.WithContext and a private key type; read it through a helper function.
  • Validate every path value, query parameter and form field at the edge; use PostFormValue for bodies and answer 400 or 422 with clear messages.
  • JSON handlers check the content type, limit the body, decode strictly, translate decode errors precisely and answer in one uniform error shape.
  • Test with httptest.NewRequest and httptest.NewRecorder, through the same router and middleware chain that production uses.

Next: The HTTP Client