Which Go framework should you choose when none is the obvious choice?

A backend application has one main job: receive requests, process them, and respond. Those requests almost always arrive over HTTP, the protocol of the web: that’s the case for a REST API called by a browser or a mobile app.

Let’s take an example that will follow us through the whole article: Notebook, a small fictional service written in Go that manages notebooks. A client asks it for notebook no. 42. Let’s follow that request, from its arrival to the response:

Steps 1 to 3 look much the same from one application to the next, and nobody wants to rewrite them every time. That’s the framework’s job:

And yet, in the diagram, only one block has the framework’s color, and it’s dashed. That’s because in Go, the standard library, shipped with the language, already handles most of the plumbing. Let’s compare with Java, where the framework does everything:

The absence of a big framework in Go is neither a delay nor an accident. It follows from choices made when the language was designed: a culture wary of magic, and a standard library trusted with the essentials. Two recent events reinforced them.

A culture wary of magic

Go was designed at Google for large codebases maintained by many people, with one obsession: code should read without surprises.

A little copying is better than a little dependency.

Everything that makes Spring powerful, convention-based configuration, annotations, automatic injection, is precisely what this culture looks at with suspicion. A Go framework has to justify every line it adds.

Betting everything on the standard library

This culture has a direct consequence: rather than leaving the essentials to the ecosystem, Go ships them with the language. Elsewhere, the standard library can speak HTTP, but nobody trusts it with production: Python’s documentation says so in plain words about its http.server module, and in Java the server has historically come from Tomcat or Jetty. In Go, the standard library covers almost everything a backend uses day to day:

net/http, its centerpiece

For a web backend, the centerpiece of this library is net/http, the package that handles steps 1 and 2 of the journey. Three reasons make it the center of gravity of the whole ecosystem:

This standard plug deserves a closer look, because everything that follows depends on it. It’s a one-method interface, called at step 4 to make your handler respond:

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

// A middleware is just a function
// that wraps one Handler in another.
func Logging(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		start := time.Now()
		next.ServeHTTP(w, r)
		slog.Info("request", "path", r.URL.Path, "duration", time.Since(start))
	})
}

A framework that keeps this plug inherits all of that for free. A framework that replaces it has to rewrite these pieces or provide adapters.

Two events that changed the game

The first showed, at scale, what the standard plug is worth: since gorilla/mux keeps it, the affected teams could switch routers by rewriting only their route declarations. The second took away third-party routers’ simplest selling point. Since then, “the standard library is enough” is no longer a purist’s stance, but a reasonable option for many services.

In Go, a framework is an assembly

One last difference, the one that confuses people coming from Java the most: Spring Boot covers the whole stack, while a Go web framework almost always covers only the HTTP layer. The rest is chosen piece by piece, whatever the framework.

The middle column is almost full. In Go, “choosing a framework” therefore means choosing the layer that turns an HTTP request into a call to your code, and deciding how far from the standard library to put it. The only exceptions: a few full platforms, such as Encore, which take over much of the table.

To compare tools this different, you need a grid. Eight criteria make it up. The first outweighs all the others, because it follows directly from the language’s philosophy. And the one people always mention first, speed, barely belongs on the list.

1. 1Distance from the standard library
2. 2Error handling
3. 3Input parsing
4. 4Contract and documentation
5. 5Observability
6. 6Maintenance
7. 7Protocols
8. 8The team
9. ✕Raw speed

1Distance from the standard library, the criterion above all

Go bets everything on its standard library, and for the web on net/http. So a Go framework is judged first by what it puts between your code and that library:

That distance has a price, which you only pay when you leave:

That day comes more often than people think:

How to measure it: the signature

Distance can be read in a single line, at step 4 of the journey: the signature of the handlers, that is, what they take and what they return. The further it strays from the standard plug, http.Handler, the greater the distance. Here’s a handler’s signature in five tools:

Here’s what that changes for two identical projects, one written with Chi, the other with Gin, on the day you leave them:

That’s not a flaw: it’s a trade, comfort for freedom. But it’s decided on day one, not on the day you leave.

The seven other criteria

Once the distance is measured, you still need to know what the framework gives you in return. Seven criteria tell you.

What about speed?

Open any comparison of Go frameworks: it starts with a requests-per-second chart. It’s the most visible criterion and, for most projects, the least relevant. The most cited router benchmark, go-http-routing-benchmark, hasn’t been updated since 2020, and the results published in its README were measured with Go 1.3, in 2014. They show that a fast router finds a route in about a hundred nanoseconds, and a slow one in a few microseconds. The difference is real, but it needs putting in perspective.

The HTTP engine, however, can matter, in one specific case: a server that receives a huge number of small requests and does almost nothing with each (a proxy, a gateway, an event collector). The only way to know is to profile your service, with pprof, under your load. If the HTTP server doesn’t show up at the top of the profile, the framework isn’t your performance problem.

With these criteria in hand, we can rephrase the starting question. The one everyone asks has no answer; the one you should ask has one, different for every project.

The first question has no answer: the rankings that claim to answer it mostly compare microbenchmarks. The second has one, different for every project. I’ll also tell you which one I like best, and why.

Each half of the right question is weighed with the criteria from part 3:

To apply it, seven concrete questions to ask as a team before writing the first route. The answers almost always point to the right candidate:

1. What doesn’t the standard library give me?criteria 2 to 8Write the list down. If it’s short, the standard library and twenty lines of adapter may be enough.
2. Who consumes this API?criterion 4Your own apps, or partners? If a published contract is a deliverable, the contract-first tools come before all the others.
3. Which protocols in two years?criterion 7HTTP/2, gRPC, streaming, WebSocket: anything added later is easier close to the standard library.
4. Who will maintain this code?criterion 8Not today’s team: the one three years from now. What it already knows, and what it will easily find online.
5. Who maintains the tool, and how often does it break?criterion 6Date of the latest release, number of active maintainers, history of major versions.
6. What would I have to rewrite to leave?criterion 1Look at the handler signature. It’s the most honest answer you’ll get.
7. Does my business code import the framework?criterion 1The answer must be no, whatever tool you pick. It’s the only rule that holds for every candidate.

Seven candidates, ranked from closest to the standard library to furthest away. For each: an introduction, where it stands on the eight criteria, the situations where it fits best, its challenges and risks, and my verdict.

mux := http.NewServeMux()
mux.HandleFunc("GET /notebooks/{id}",
	func(w http.ResponseWriter, r *http.Request) {
		n, err := store.Notebook(r.Context(), r.PathValue("id"))
		if errors.Is(err, ErrNotFound) {
			http.Error(w, "notebook not found", http.StatusNotFound)
			return
		}
		if err != nil {
			http.Error(w, "internal error", http.StatusInternalServerError)
			return
		}
		w.Header().Set("Content-Type", "application/json")
		json.NewEncoder(w).Encode(n)
	})

mux := http.NewServeMux()
mux.HandleFunc("GET /healthz", healthz)

admin := http.NewServeMux()
admin.HandleFunc("GET /admin/users", listUsers)
admin.HandleFunc("POST /admin/users/{id}/suspend", suspend)
mux.Handle("/admin/", requireAdmin(admin))

// Global middleware is stacked by hand,
// from innermost to outermost.
var h http.Handler = mux
h = logging(h)
h = recoverer(h)
http.ListenAndServe(":8080", h)

r := chi.NewRouter()
r.Use(middleware.RequestID, middleware.Recoverer)
r.Use(logging)

r.Get("/healthz", healthz)

r.Route("/admin", func(r chi.Router) {
	r.Use(requireAdmin)
	r.Get("/users", listUsers)
	r.Post("/users/{id}/suspend", suspend)
})

http.ListenAndServe(":8080", r)

// Handler is an http.Handler that returns an error.
type Handler func(w http.ResponseWriter, r *http.Request) error

func (h Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
	if err := h(w, r); err != nil {
		writeError(w, r, err) // one place for status codes, the JSON format and logs
	}
}

// A business error becomes an HTTP response here, and nowhere else.
func writeError(w http.ResponseWriter, r *http.Request, err error) {
	status, message := http.StatusInternalServerError, "internal error"
	switch {
	case errors.Is(err, notebook.ErrNotFound):
		status, message = http.StatusNotFound, "notebook not found"
	case errors.Is(err, notebook.ErrInvalid):
		status, message = http.StatusBadRequest, err.Error()
	default:
		slog.ErrorContext(r.Context(), "request failed", "err", err, "path", r.URL.Path)
	}
	writeJSON(w, status, map[string]string{"error": message})
}

func (a *API) getNotebook(w http.ResponseWriter, r *http.Request) error {
	n, err := a.notebooks.Get(r.Context(), r.PathValue("id"))
	if err != nil {
		return err
	}
	return writeJSON(w, http.StatusOK, n)
}

func (a *API) Routes() http.Handler {
	r := chi.NewRouter()
	r.Use(middleware.RequestID, middleware.Recoverer)
	r.Method("GET", "/notebooks/{id}", Handler(a.getNotebook))
	return r
}

type NotebookInput struct {
	ID string `path:"id" maxLength:"36" doc:"Notebook ID"`
}
type NotebookOutput struct {
	Body Notebook
}

r := chi.NewRouter()
r.Get("/healthz", healthz) // internal routes stay pure Chi

// The public API goes through Huma, which generates /openapi.json and the docs
api := humachi.New(r, huma.DefaultConfig("Notebook", "1.0.0"))
huma.Get(api, "/notebooks/{id}",
	func(ctx context.Context, in *NotebookInput) (*NotebookOutput, error) {
		n, err := store.Notebook(ctx, in.ID)
		if errors.Is(err, ErrNotFound) {
			return nil, huma.Error404NotFound("notebook not found")
		}
		if err != nil {
			return nil, err
		}
		return &NotebookOutput{Body: n}, nil
	})

r := gin.New()
r.Use(gin.Recovery())
r.GET("/notebooks/:id", func(c *gin.Context) {
	n, err := store.Notebook(c.Request.Context(), c.Param("id"))
	if errors.Is(err, ErrNotFound) {
		c.JSON(http.StatusNotFound, gin.H{"error": "notebook not found"})
		return
	}
	if err != nil {
		c.AbortWithStatus(http.StatusInternalServerError)
		return
	}
	c.JSON(http.StatusOK, n)
})

e := echo.New()
e.Use(middleware.Recover())
e.GET("/notebooks/:id", func(c *echo.Context) error {
	n, err := store.Notebook(c.Request().Context(), c.Param("id"))
	if errors.Is(err, ErrNotFound) {
		return echo.NewHTTPError(http.StatusNotFound, "notebook not found")
	}
	if err != nil {
		return err // the central handler will respond 500
	}
	return c.JSON(http.StatusOK, n)
})

app := fiber.New()
app.Get("/notebooks/:id", func(c fiber.Ctx) error {
	n, err := store.Notebook(c.Context(), c.Params("id"))
	if errors.Is(err, ErrNotFound) {
		return fiber.NewError(fiber.StatusNotFound, "notebook not found")
	}
	if err != nil {
		return err
	}
	return c.JSON(n)
})

//encore:api public method=GET path=/notebooks/:id
func Get(ctx context.Context, id string) (*Notebook, error) {
	n, err := store.Notebook(ctx, id)
	if errors.Is(err, ErrNotFound) {
		return nil, &errs.Error{Code: errs.NotFound, Message: "notebook not found"}
	}
	return n, err
}

The profiles start from the candidates; the compass goes the other way. It starts from your project, asks four questions and tells you which candidate to start with. It doesn’t replace the reasoning of the previous parts: it sums it up.

If you were to keep only one page of this article, it would be this one.

1. In Go, the standard library already does most of the work

   The HTTP server, the router, testing: a framework doesn’t provide the foundation there, only comfort on top.

2. The criterion above all: distance

   The further a tool moves from the standard library, the more it does for you, and the more leaving costs. Its handler signature tells you in one line.

3. The smallest distance that’s enough for you

   List what the standard library doesn’t give you, pick the closest tool that covers it, and keep the business logic out of the framework’s reach.

Your turn

I’ve only given my reading, and my preferences. I’d love to hear yours.