(Golang)You've Been Calling It a Handler Wrong All Along

Areesh Zafar — Wed, 08 Apr 2026 12:00:01 +0000

When routing in go, we attach a normal function to a router and call it a handler, for example :

package main

func home(w http.ResponseWriter, r *http.Request) {

     w.Write([]byte("Hello from Snippetbox")) 
}

func main(){
    mux := http.NewServeMux()
    mux.HandleFunc("/", home)
}

Most of would just call that home is a handler without knowing how its orginally not a handler and is transformer into one.

To understand this, first we need to understand what is a handler?

A Handler is any object that has the ServeHTTP() method, but why? Let's see in the source code of go, inside the net/http package, in server.go we will see this:

type Handler interface {
    ServeHTTP(ResponseWriter, *Request)
}

which means, to be a Handler, that thing should contain the ServeHTTP() method with the exact signature as above.

But now the question arises, so why does my routes work?

Here's the answer :

it works because when we register the route like this:

mux.HandleFunc("/", home)

HandleFunc() secretly wraps the home function inside http.HandlerFunc() which in turn attaches the ServeHTTP() method to the home function and makes it indirectly a "Handler"

type HandlerFunc func(ResponseWriter, *Request)

func (f HandlerFunc) ServeHTTP(w ResponseWriter, r *Request) {
    f(w, r) // just calls the home function
}

So to wrap this is the total flow:

You might also get it that we can directly call the HandlerFunc() instead of HandleFunc(), yes we can but HandleFunc() is easer to write and does the same work internally.

This is how we can directly call the HandlerFunc() :

mux := http.NewServeMux()
mux.Handle("/", http.HandlerFunc(home))

Furthermore, ServeMux itself is also a Handler, it has its own ServeHTTP() method, look at the source code :

Notice(line 2847), the *ServeMux in the receiver part of the function,that means ServerHTTP() belongs to ServeMux, making it a Handler too anddd that's why we can pass it directly to http.ListenAndServe()

notice, the second parameter of the ListenAndServe() function is a handler so the mux we pass in there to run our server is also a handler

err := http.ListenAndServe(":4000", mux)//mux is a handler!

Next time you write mux.HandleFunc("/",home) - you'll know that home alone isn't really a handler, but http.HandlerFunc(home) is and that's exactly what Go creates behind the scenes:)

Thanks for reading till here, see you in the next post ;)

How Go's Server Multiplexer Actually Works

Areesh Zafar — Tue, 07 Apr 2026 10:08:34 +0000

What is ServeMux in Go?

ServeMux is a request router that decides which function should handle an incoming request, it matches the URL of an incoming http request to a set of registered patterns which we define like so:

mux:= http.NewServeMux()

mux.HandleFunc("/", home)
mux.HandleFunc("/add",addNum)

when a user hits / url then the home function is run, similarly when a user hits the "/add" url the addNum function will be run.

Simple right?

But there's a catch, go's servemux supports two kinds of URL patterns:

Fixed Paths
Subtree Paths

Fixed Paths- These URL patterns do not have a trailing slash(a slash at end) like "/add" in the above example.

Subtree Paths- These URL patterns end with a trailing slash like "/add/" or simply "/" as in the above example.

What happens is that fixed path patterns are only matched when the URL path exactly matches the pattern we define like "/add", so if we go to the URL "/add/" the addNum function won't run because in the

mux.HandleFunc ("/add",addNum) function,

we are specifying that only run the addNum function if the URL matches exactly to "/add".

In contrast, the "/" is a subtree path (because it ends with a slash /) so if we go to any URL starting with the / (other than the "/add"), the home function will run as we defined mux.HandleFunc ("/", home), so any URL path starting with / will run the function home.

Another example of a subtree path would be "/multiply/", and let's say its defined as:

mux.HandleFunc("/multiply/",mulNum)

so if a user goes to the URL "/multiply/abcd", the servemux automatically redirects to "/multiply/" and runs the mulNum function, and even if the user goes to "/multiply" (no trailing slash), the ServeMux automatically adds a trailing slash and runs the mulNum function.

Longer URL wins

In go's ServeMux, the longer URL always takes precedence over the shorter ones, no matter the order in which the routes are defined in the code,

for example:

mux.HandleFunc("/",home)
mux.HandleFunc("/message",viewMessage)
mux.HandleFunc("/message/create",createMessage)

suppose a user goes to "/message/create", what happens is:

the "/" pattern matches ✅

the "/message" pattern also matches✅

the "/message/create" pattern also matches ✅

but the pattern which is longest will be selected and its corresponding function will be run, i.e. in this case: createMessage function will be run.

So this gives a really cool side effect- we can register routes in any order and go's ServeMux will always match the URL with the longest matching pattern:

(you can register the routes in any order ):

mux.HandleFunc("/message",viewMessage)
mux.HandleFunc("/",home)
mux.HandleFunc("/message/create",createMessage)

While this might seem like a small thing but if you are coming from nodejs and express, you know the pain, route order matters there and getting it wrong can cause bugs. Go's ServeMux just handles it automatically.

Forem: Areesh Zafar

(Golang)You've Been Calling It a Handler Wrong All Along

How Go's Server Multiplexer Actually Works

What is ServeMux in Go?

Longer URL wins