An Introduction to Handlers and Servemuxes in Go
Processing HTTP requests with Go is primarily about two things: handlers and servemuxes.
If you’re coming from an MVC-background, you can think of handlers as being a bit like controllers. Generally speaking, they're responsible for carrying out your application logic and writing response headers and bodies.
Whereas a servemux (also known as a router) stores a mapping between the predefined URL paths for your application and the corresponding handlers. Usually you have one servemux for your application containing all your routes.
net/http package ships with the simple but effective
servemux, plus a few functions to generate common handlers including
Let's take a look at a simple (but slightly contrived!) example which uses these:
Go ahead and run the application:
And if you make a request to
http://localhost:3000/foo you should find that it gets successfully
redirected like so:
Whereas all other requests should be met with a
404 Not Found error response.
The handlers that ship with
net/http are useful, but most of the time when building a web application
you'll want to use your own custom handlers instead. So how do you do that?
The first thing to explain is that anything in Go can be a handler so long as it
which looks like this:
If you're not familiar with interfaces in Go I've written an explanation here, but in simple terms all it
means is that a handler must have a
ServeHTTP() method with the following signature:
To help demonstrate, let's create a custom handler which responds with the current time in a specific format. Like this:
The exact code here isn't too important.
All that really matters is that we have an object (in this case it's a
timeHandler struct, but it could
equally be a string or function or anything else), and we've implemented a method with the signature
ServeHTTP(http.ResponseWriter, *http.Request) on it. That's all we need to make a handler.
Let's try this out in a concrete example:
Run the application, then go ahead and try making a request to
http://localhost:3000/time. You should
get a response containing the current time, similar to this:
Let's step through what's happening here:
- When our Go server receives an incoming HTTP request, it hands it off to our servemux (the one that we passed to
- The servemux then looks up the appropriate handler based on the request path (in this case, the
/timepath maps to our
- The serve mux then calls the
ServeHTTP()method of the handler, which in turn writes out the HTTP response.
The eagle-eyed of you might have also noticed something interesting: the signature for the
http.ListenAndServe() function is
ListenAndServe(addr string, handler Handler), but we passed a servemux as the second argument.
We were able to do this because the
http.ServeMux type has a
ServeHTTP() method, meaning that it
too satisfies the
For me it simplifies things to think of
http.ServeMux as just being a special kind of handler,
which instead of
providing a response itself passes the request on to a second handler. This isn't as much of a leap as it first
— chaining handlers together is very commonplace in Go.
Functions as handlers
For simple cases (like the example above) defining new a custom type just to make a handler feels a bit verbose. Fortunately, we can rewrite the handler as a simple function instead:
Now, if you've been following along, you're probably looking at that and wondering: How can that be a handler? It
doesn't have a
And you'd be correct. This function itself is not a handler. But we can coerce it into
being a handler by converting it to a
Basically, any function which has the signature
func(http.ResponseWriter, *http.Request) can be
converted into a
http.HandlerFunc type. This is useful because
http.HandlerFunc objects come with an
ServeHTTP() method which
— rather cleverly and conveniently — executes the content of the original function.
If that sounds confusing, try taking a look at the relevant
source code. You'll see that it's
a very succinct way of making a function satisfy the
Let's reproduce the our application using this technique:
In fact, converting a function to a
http.HandlerFunc type and then adding it to a servemux like this is
so common that Go
provides a shortcut: the
method. You can use this like so:
Passing variables to handlers
Most of the time using a function as a handler like this works well. But there is a bit of a limitation when things start getting more complex.
You've probably noticed that, unlike the method before, we've had to hardcode the time format in the
timeHandler function. What happens when you want to pass information or variables from
main() to a handler?
A neat approach is to put our handler logic into a closure, and close over the variables we want to use, like this:
timeHandler() function now has a subtly different role. Instead of coercing the function into a
handler (like we did previously), we are now using it to return a handler. There's two key elements to
making this work.
First it creates
fn, an anonymous function which accesses — or closes over — the
format variable forming a closure. Regardless of what we do with the closure it will always be
able to access the variables that are local to the scope it was created in — which in this case means it'll
always have access to the
Secondly our closure has the signature
func(http.ResponseWriter, *http.Request). As you may remember
from a moment ago, this means that we can convert it into a
http.HandlerFunc type (so that it satisfies
timeHandler() function then returns this converted closure.
In this example we've just been passing a simple string to a handler. But in a real-world application you could use this method to pass database connection, template map, or any other application-level context. It's a good alternative to using global variables, and has the added benefit of making neat self-contained handlers for testing.
You might also see this same pattern written as:
Or using an implicit conversion to the
http.HandlerFunc type on return:
The default servemux
You've probably seen the default servemux mentioned in a lot of places, from the simplest Hello World examples to the Go source code.
It took me a long time to realise it isn't anything special. The default servemux is just a plain ol' servemux like
we've already been using, which gets instantiated by default when the
net/http package is used and is
stored in a global variable. Here's the relevant line from the Go source:
Generally speaking, I recommended against using the default servemux because it makes your code less clear and explicit and it poses a security risk. Because it's stored in a global variable, any package is able to access it and register a route — including any third-party packages that your application imports. If one of those third-party packages is compromised, they could use the default servemux to expose a malicious handler to the web.
Instead it's better to use your own locally-scoped servemux, like we have been so far. But if you do decide to use the default servemux...
net/http package provides a couple of shortcuts for registering routes with the default servemux:
http.HandleFunc(). These do exactly the same
as their namesake functions we've already looked at, with the difference that they add handlers to the default
servemux instead of one that you've created.
http.ListenAndServe() will fall back to using the default servemux if no other handler is provided (that is,
the second argument is set to
So as a final step, let's demonstrate how to use the default servemux in our application instead: