repository·master·Indexed 42 days ago
https://github.com/go-pkgz/routegroupA lightweight Go wrapper for http.ServeMux that enables efficient route grouping and middleware application. It allows developers to organize routes into logical groups, apply scoped middleware using Use and With, and manage nested routing via Mount. Requires Go 1.23 or higher to utilize enhanced http.ServeMux routing behavior and http.Request.Pattern.
routegroup is a lightweight Go package designed to provide efficient route grouping and middleware integration for the standard http.ServeMux. It acts as a wrapper that allows you to organize routes into logical groups and apply middleware to those groups or individual routes seamlessly.Middleware registration follows strict rules to ensure predictable execution:
Use(...) before registering any routes (via Handle, HandleFunc, etc.) on that specific bundle.Use on a bundle after any handler has already been registered on that bundle will cause a panic.router.Use) apply to all requests.group.Use) apply to that group and its descendants.With(...) is the preferred way to add scoped middleware to specific routes without affecting the parent group.To use routegroup, your project must meet the following requirement:
http.ServeMux routing behavior introduced in Go 1.22/1.23 and specifically uses http.Request.Pattern to make route patterns available to global middlewares.Use routegroup.New(mux) to initialize a new route group wrapping an http.ServeMux. You can add routes using Handle or HandleFunc and apply middleware to the entire group using Use.
To create nested groups under a specific path prefix, use the Mount method. To create a new group without a path prefix (useful for inheriting middleware from a parent), use the Group method.
// Initialize
mux := http.NewServeMux()
group := routegroup.New(mux)
// Add middleware to the group
group.Use(loggingMiddleware, corsMiddleware)
// Add routes
group.Handle("/hello", helloHandler)
// Create a nested group under /api
apiGroup := group.Mount("/api")
apiGroup.Handle("/v1", apiV1Handler)To install or update routegroup in your Go project, use the following command:
go get -u github.com/go-pkgz/routegroupThe routegroup package uses a hierarchical model to manage middleware application across different URL segments:
New. Middlewares added here are 'Global Middlewares'. They wrap the entire http.ServeMux and execute for every request. They can see the route pattern via r.Pattern but cannot access path parameters (like r.PathValue("id")) because they run before the mux performs parameter parsing.Mount or Group. These inherit the middleware stack of their parent. Middlewares added to a group execute after the mux has routed the request, meaning they have full access to path parameters.// 1. Root bundle with global logging
root := routegroup.New(mux)
root.Use(loggingMiddleware)
// 2. Mounted group with auth
// authMiddleware can access path parameters
api := root.Mount("/api")
api.Use(authMiddleware)
// 3. Route registration
api.HandleFunc("/user/{id}", userHandler)
// Execution flow: loggingMiddleware -> authMiddleware -> userHandlerThe following example demonstrates how to use routegroup to organize a real-world web service. It showcases:
routegroup.Mount(http.NewServeMux(), s.rootURL) to create a bundle with a base path..Use()..Group().Route(func(b *routegroup.Bundle) { ... }) to create logical segments (like /admin) with their own middleware stack..With(middleware) to apply specific middleware to a subset of routes within a group without affecting the rest of the group..Mount(path).Route(...) to create deeply nested route hierarchies.http.FileServer with routegroup patterns.// Routes returns http.Handler that handles all the routes for the Service.
func (s *Service) Routes() http.Handler {
router := routegroup.Mount(http.NewServeMux(), s.rootURL)
// add common middlewares
router.Use(rest.Maybe(handlers.CompressHandler, func(*http.Request) bool { return !s.skipGZ }))
router.Use(rest.Throttle(s.limitActiveReqs))
router.Use(s.middleware.securityHeaders(s.skipSecurityHeaders))
// prepare csrf middleware
csrfMiddleware := s.middleware.csrf(s.skipCSRFCheck)
// add open routes
router.HandleFunc("GET /login", s.loginPageHandler)
router.HandleFunc("POST /login", s.loginCheckHandler)
router.HandleFunc("GET /logout", s.logoutHandler)
// add routes with auth middleware
router.Group().Route(func(auth *routegroup.Bundle) {
auth.Use(s.middleware.Auth())
auth.HandleFunc("GET /update", s.pwdUpdateHandler)
auth.With(csrfMiddleware).HandleFunc("PUT /update", s.pwdUpdateHandler)
})
// add admin routes
router.Mount("/admin").Route(func(admin *routegroup.Bundle) {
admin.Use(s.middleware.Auth("admin"))
admin.Use(s.middleware.AdminOnly)
admin.HandleFunc("GET /", s.admin.renderHandler)
admin.With(csrfMiddleware).Route(func(csrf *routegroup.Bundle) {
csrf.HandleFunc("DELETE /sessions", s.admin.deleteSessionsHandler)
csrf.HandleFunc("POST /user", s.admin.addUserHandler)
csrf.HandleFunc("DELETE /user", s.admin.deleteUserHandler)
})
})
router.HandleFunc("GET /static/*", s.fileServerHandlerFunc())
return router
}When using Mount, a request to the group's base path (e.g., /api) might not match a route defined as /api/ due to how http.ServeMux handles trailing slashes (which often triggers a redirect).
To handle the exact path without a trailing slash and avoid the redirect round-trip, use HandleRoot or HandleRootFunc. This is particularly useful for non-GET requests.
apiGroup := router.Mount("/api")
// This handles requests to exactly "/api" without a redirect
apiGroup.HandleRoot("GET", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Write([]byte("API Documentation"))
}))
// You can also specify different methods for the root path
apiGroup.HandleRoot("POST", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Write([]byte("Create API Resource"))
}))If you want to apply middleware to a specific route without affecting the existing middleware stack of the current group, use the With method. With returns a new bundle (group) containing the additional middlewares, allowing you to register routes on it immediately.
// apiGroup's existing middleware is preserved,
// but this specific route also gets corsMiddleware and apiMiddleware
apiGroup.With(corsMiddleware, apiMiddleware).Handle("GET /hello", helloHandler)If you do not need a full route group and simply want to apply one or more middlewares to a single http.Handler, use the routegroup.Wrap function. This is useful when working directly with a standard http.ServeMux.
mux := http.NewServeMux()
// Wrap the handler directly in the mux registration
mux.HandleFunc("/hello", routegroup.Wrap(helloHandler, loggingMiddleware, corsMiddleware))You can set a custom handler to run when a request matches no routes in the underlying http.ServeMux. This handler only executes on 404 errors and does not interfere with 405 Method Not Allowed responses or path-cleanup redirects. Global middlewares applied to the root bundle will still run for this handler.
group.NotFoundHandler(func(w http.ResponseWriter, _ *http.Request) {
http.Error(w, "404 page not found!", http.StatusNotFound)
})The HandleFiles helper is a wrapper around http.FileServer that allows you to serve static files from a specific directory at a given path prefix.
// Serves files from "assets/static" at the "/static/" URL path
router.HandleFiles("/static/", http.Dir("assets/static"))