# Go types explained: the foundation you need before writing HTTP handlers

# 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:

```go
// 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**:

```go
// 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`.

```go
// 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:

```go
// 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:

```go
// 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`:

```go
// 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:

```go
// 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`:

```go
// 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:

```go
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

```go
// 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:

```go
// 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:

```go
// 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.

*   [LinkedIn](https://www.linkedin.com/in/ferrios/)
    
*   [GitHub](https://github.com/FerRiosCosta)
    
*   [Twitter / X](https://x.com/ferztyle)
    

*Building from Asunción, Paraguay 🇵🇾*