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.
Let's connect!
One of the best parts of writing in public is the people you meet along the way, engineers at different stages of their journey, working on similar problems from completely different angles.
If something in this post resonated, if you spotted a bug, or if you just want to talk Go, Kubernetes, Platform Engineering, DevOps, or whatever, I'm always happy to hear from you.
Building from Asunción, Paraguay 🇵🇾
