go-router is a lightweight, flexible, and idiomatic HTTP router for Go web applications. It leverages Go's standard net/http package and the latest routing enhancements in Go 1.22 to provide powerful routing capabilities without external dependencies.
- Method-Based Routing: Easily define routes for
GET,POST,PUT,PATCHandDELETEmethods. - Route Grouping: Organize routes under common base paths using groups.
- Middleware Support: Apply middleware functions globally or per group.
- Custom Status Handlers: Set custom handlers for any possible status code.
- Trailing Slash Handling: Configure automatic redirection of trailing slashes.
- Static File Serving: Serve static files and directories seamlessly.
- Built on Standard Library: Utilizes Go's net/http package, ensuring performance and reliability.
- No External Dependencies: Keeps your application lightweight and maintainable.
Ensure you have Go 1.22 or later installed to leverage the latest routing enhancements.
To install go-router, run:
go get github.com/donseba/go-routerThe Router struct is the core of the package, providing methods to define routes, apply middleware, and configure routing behavior.
Fields
- *mux http.ServeMux: The underlying HTTP request multiplexer.
- basePath string: The base path for the router, used in route grouping.
- redirectTrailingSlash bool: Determines whether to redirect trailing slashes to their non-trailing counterparts.
- middlewares []Middleware: A slice of middleware functions applied to the router.
- notFoundHandler http.HandlerFunc: Custom handler for 404 Not Found responses.
- methodNotAllowedHandler http.HandlerFunc: Custom handler for 405 Method Not Allowed responses.
type Middleware func(http.Handler) http.Handler
Represents a middleware function that wraps an http.Handler to perform actions before or after the handler executes.
Creates a new Router instance using the provided http.ServeMux.
Creates a new Router instance with a default http.ServeMux.
Route Definition Methods
Define routes for specific HTTP methods.
- (*Router) Get(pattern string, handler http.HandlerFunc)
- (*Router) Post(pattern string, handler http.HandlerFunc)
- (*Router) Put(pattern string, handler http.HandlerFunc)
- (*Router) Patch(pattern string, handler http.HandlerFunc)
- (*Router) Delete(pattern string, handler http.HandlerFunc)
- pattern string: The URL pattern for the route. Patterns can include placeholders like {id}. A pattern that ends in “/” matches all paths that have it as a prefix, as always. To match the exact pattern including the trailing slash, end it with
{$}, as in/exact/match/{$}. - handler http.HandlerFunc: The function to handle requests matching the pattern and method.
(*Router) Group(basePath string, fn func(*Router))
Organize routes under a common base path.
- basePath string: The base path for the group.
- fn func(*Router): A function that receives a sub-router for defining grouped routes.
(*Router) Use(middleware Middleware)
Apply middleware functions to the router.
- middleware Middleware: A middleware function to be applied.
- (*Router) HandleStatus(http.StatusCode, handler http.HandlerFunc): Set a custom handler for any status code.
handler http.HandlerFunc: The function to handle the specific response.
(*Router) RedirectTrailingSlash(redirect bool)
Configure automatic redirection of trailing slashes.
- redirect bool: If true, requests with trailing slashes are redirected to their non-trailing counterparts.
- (*Router) ServeFiles(pattern string, fs http.FileSystem): Serve static files from a directory.
- (*Router) ServeFile(pattern string, filepath string): Serve a single static file.
- pattern string: The URL pattern under which the files are served.
- fs http.FileSystem: The file system to serve files from.
- filepath string: The path to the file to be served.
(*Router) ServeHTTP(w http.ResponseWriter, req *http.Request)
Implements the http.Handler interface, allowing the router to serve HTTP requests.
handle(method, pattern string, handler http.HandlerFunc)
An internal method used to register handlers for specific HTTP methods and patterns.
- method string: The HTTP method (e.g., GET, POST).
- pattern string: The URL pattern.
- handler http.HandlerFunc: The handler function.
- DefaultRedirectTrailingSlash bool: The default setting for trailing slash redirection (default is true).
Use the provided methods to define routes for specific HTTP methods. Patterns can include placeholders for path parameters.
r.Get("/users/{id}", userHandler)Group related routes under a common base path using the Group method.
r.Group("/api", func(api *Router) {
api.Get("/users", apiUsersHandler)
api.Post("/users", apiCreateUserHandler)
})Apply middleware functions globally or to specific route groups.
// Global middleware
r.Use(loggingMiddleware)
// Middleware for a group
r.Group("/admin", func(admin *Router) {
admin.Use(authMiddleware)
admin.Get("/dashboard", adminDashboardHandler)
})Set custom handlers to provide consistent error responses.
r.HandleStatus(http.StatusNotFound, notFoundHandler)
r.HandleStatus(http.StatusMethodNotAllowed, methodNotAllowedHandler)
r.HandleStatus(http.StatusInternalServerError,internalServerErrorHandler)Configure the router to automatically redirect trailing slashes.
r.RedirectTrailingSlash(true) // Enabled by defaultServe files from a directory or serve a single file.
// Serve files from the "./static" directory under "/static/"
fs := http.Dir("./static")
r.ServeFiles("/static/", fs)
// Serve a single file
r.ServeFile("/favicon.ico", "./static/favicon.ico")- Pattern Matching: Patterns not ending with a slash (/) are treated as exact matches, while patterns ending with a slash are treated as prefix matches.
- Middleware Order: Middleware functions are applied in the order they are added, wrapping subsequent middleware and the final handler.
- Custom Status Handling: The router uses intercepting response writers to capture status code responses from the underlying http.ServeMux and invoke custom handlers.
- Trailing Slash Redirection: When enabled, requests with trailing slashes are redirected to the same path without the trailing slash.
- Error Handling Enhancements: Provide mechanisms for handling other HTTP status codes.