HttpRouter - High-Performance HTTP Request Router for Go

HttpRouter exists because Go's default ServeMux is slow and can't handle path parameters. When you need to route /users/:id without writing regex nightmares, HttpRouter is the tool. Been running this in production recently and haven't hit any major performance walls yet.

The Real Story

Here's what actually matters: HttpRouter uses a radix tree for route matching, which means lookups are stupidly fast. The creator Julien Schmidt built this because he was tired of slow routers that allocated garbage like it was going out of style.

What you get:

• Path parameters that don't suck: /user/:id works exactly like you'd expect
• Zero memory allocations for static routes (proven by benchmarks)
• Method-specific routing that doesn't require middleware bloat
• Custom 404/405 handlers because the default ones are useless

What you don't get:

• Regex support (this will bite you when you need /user/\d+)
• Built-in middleware (you're writing wrapper functions for everything)
• Automatic parameter validation (Path parameters accept any garbage - validate everything yourself)

You'll end up writing ugly validation functions for every damn parameter. Ask me how I know - spent a Tuesday debugging why my user endpoint was accepting emoji as user IDs.

Performance Reality Check

The benchmark numbers look impressive but take them with a grain of salt. In real-world usage:

• HttpRouter matters when you're serving 10k+ requests/second
• For most CRUD apps, the performance difference is negligible
• We switched from Gorilla Mux and CPU usage dropped noticeably - response times improved by maybe 30-40% but honestly the database queries were still the real bottleneck
• The lack of middleware means you'll spend time building your own CORS, authentication, and logging wrappers

Production Gotchas I Learned the Hard Way

Catch-all routes are greedy as hell: If you define /files/*filepath, it'll match /files/whatever/goes/here but can break other patterns. Order matters more than the docs let on. We had this production incident where a catch-all route was eating our health checks. Spent most of a weekend debugging why our monitoring was failing while PagerDuty was lighting up like a Christmas tree - turns out route order matters way more than the useless docs suggest.

Panic recovery is good but the default handler is useless: You'll want to customize the panic handler to actually log useful error details instead of generic 500s.

The middleware story is annoying: Unlike Gin or Echo, you're on your own for middleware. Here's the wrapper pattern you'll end up using everywhere.

When to Actually Use This

Perfect for:

• High-throughput APIs where every millisecond counts
• Microservices that need minimal overhead
• Performance nerds who want to squeeze every nanosecond
• Teams comfortable writing their own middleware

Skip it for:

• Rapid prototyping (use Gin instead)
• Complex routing needs (use chi)
• Teams that need extensive middleware ecosystems (Echo or Fiber)

Current Status (Not What Marketing Says)

The latest release is v1.3.0 from September 2019, which either means it's rock solid or maybe the maintainer got distracted by life. Recent commits show some bug fixes through 2024, so it's probably not completely dead.

But honestly, it's simple enough that it doesn't need constant updates. Unlike some frameworks that break your app with every update (cough Node.js ecosystem).

Update (2024/2025): Go 1.22's enhanced ServeMux changed the game. HttpRouter is still faster, but now the stdlib doesn't completely suck for most projects. Note: Go 1.21 and below will break your build spectacularly if you try to use the new ServeMux features - learned that one the hard way during a Docker build that took... what, 45 minutes? Maybe an hour? Long enough to question my career choices.

Gin framework uses a custom router inspired by HttpRouter's design, which is probably the strongest endorsement you'll get. If you're building something that needs to handle serious traffic and you don't mind writing your own middleware, HttpRouter mostly delivers on its performance promises.

Basic Setup That Actually Works

Copy this - takes 30 seconds if Go modules cooperate, 10 minutes if they decide to download half the internet, or forever if you're on Windows and hit that PATH limit (because Microsoft thought 260 characters was plenty). Also note: if you're stuck on Go 1.20 or earlier, you'll get import errors that make about as much sense as assembling IKEA furniture without instructions:

package main

import (
    "fmt"
    "net/http"
    "github.com/julienschmidt/httprouter"
)

func main() {
    router := httprouter.New()

    // Basic routes
    router.GET("/", func(w http.ResponseWriter, r *http.Request, _ httprouter.Params) {
        fmt.Fprint(w, "Hello, World!")
    })

    // Path parameters - finally, no more regex hell
    router.GET("/user/:id", func(w http.ResponseWriter, r *http.Request, ps httprouter.Params) {
        id := ps.ByName("id")
        fmt.Fprintf(w, "User ID: %s", id)
    })

    http.ListenAndServe(":8080", router)
}

Key difference from Gin: You pass httprouter.Params as the third argument. This trips up every developer switching from Gin.

Path Parameters (The Good and The Annoying)

Named parameters like :id work exactly like you'd expect:

• /user/:id matches /user/123
• :id parameter accepts any garbage - no validation
• You'll write validation for everything: if id == "" { http.Error(w, "Bad Request", 400); return }

Catch-all parameters like *filepath are useful but dangerous:

• /files/*filepath matches /files/docs/readme.txt
• Also matches /files/../../../etc/passwd if you're not careful
• Sanitize your file paths or get owned

The Middleware Situation (Prepare for Boilerplate)

HttpRouter doesn't have built-in middleware. You'll write wrapper functions like this constantly (took me... I don't know, half a day and way too many Stack Overflow tabs to figure this pattern out):

func basicAuth(h httprouter.Handle) httprouter.Handle {
    return func(w http.ResponseWriter, r *http.Request, ps httprouter.Params) {
        // Check auth token, database lookup, whatever
        if !isAuthenticated(r) {
            http.Error(w, "Unauthorized", 401)
            return
        }
        h(w, r, ps)
    }
}

router.GET("/admin", basicAuth(adminHandler))

The Features That Actually Matter

CORS handling: No built-in CORS support. You'll set this up manually:

router.GlobalOPTIONS = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Access-Control-Allow-Origin", "*")
    w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE")
    w.WriteHeader(204)
})

Method-not-allowed responses: HttpRouter automatically sends 405 responses with correct Allow headers. This is actually useful.

Path cleanup: Automatically redirects /users// to /users/ and handles other common URL mess-ups. Enable with RedirectTrailingSlash. If this stops working, restart everything and try again.

Common Gotchas That Will Waste Your Time

Static file serving breaks easily:

// This works
router.ServeFiles("/static/*filepath", http.Dir("./public/"))

// This doesn't work and the error message is useless
router.ServeFiles("/static/", http.Dir("./public/"))

Panic recovery default handler is garbage: The built-in PanicHandler just returns a generic 500. Set your own:

router.PanicHandler = func(w http.ResponseWriter, r *http.Request, err interface{}) {
    log.Printf("Panic: %v", err)
    http.Error(w, "Internal Server Error", 500)
}

Route conflicts will make you want to quit programming:

• /user/:id and /user/settings conflict (define /user/settings first - learned this during a holiday weekend deployment when everything broke)
• /files/*path eats everything after /files/ including your hopes and dreams
• Route priority rules are about as intuitive as Windows registry editing and the error messages are completely useless

When to Choose HttpRouter Over Alternatives

Use HttpRouter when:

• You're building a high-throughput API gateway
• Performance benchmarks actually matter for your use case
• You need zero-allocation routing for real reasons
• Your team is comfortable writing middleware from scratch

Use Gin when:

• You want middleware that doesn't suck
• JSON binding and validation matter more than nanoseconds
• You're building a REST API for humans, not machines

Use chi when:

• You want the standard library feel with better routing
• Nested routing and route groups matter
• You don't want to rewrite every middleware function

HttpRouter delivers on its performance promises, but you'll spend extra time building basic functionality that other routers include. Perfect for high-traffic APIs, overkill for your blog.