Documentation
¶
Overview ¶
Package mux routes HTTP requests using path templates compiled to Go regular expressions.
Templates ¶
Templates match the complete path visible to their router and are anchored automatically. Literal segments are escaped. A :placeholder matches one non-empty segment, while a *wildcard matches one or more segments:
m.Get("/users/:id", func(w http.ResponseWriter, r *http.Request) {
id := mux.URLParam(r, "id")
// ...
})
m.Get("/files/*path", func(w http.ResponseWriter, r *http.Request) {
path := mux.URLParam(r, "path")
// ...
})
A placeholder or wildcard must occupy its complete path segment. Use RegisterConstraint before registering routes to replace the default matcher for parameters with a particular name.
Routes are evaluated in registration order and the first matching route with a handler for the request method wins.
Sub-routers ¶
Route mounts a child router at a path prefix. The prefix is removed from the path used for matching in the child, while handlers retain the original URL:
m.Route("/api", func(r mux.Router) {
r.Get("/widgets/:id", ...) // matches GET /api/widgets/123
})
Once a Route prefix matches, its child owns the namespace and produces the final 404 or 405 response when no child endpoint handles the request.
Index ¶
- func URLParam(r *http.Request, name string) string
- func URLParamFromCtx(ctx context.Context, name string) string
- func ValidPattern(pattern string) error
- type Logger
- type Middlewares
- type Mux
- func (mx *Mux) Connect(pattern string, handler http.HandlerFunc)
- func (mx *Mux) Delete(pattern string, handler http.HandlerFunc)
- func (mx *Mux) Get(pattern string, handler http.HandlerFunc)
- func (mx *Mux) Group(fn func(r Router)) Router
- func (mx *Mux) Handle(pattern string, handler http.Handler)
- func (mx *Mux) HandleFunc(pattern string, handler http.HandlerFunc)
- func (mx *Mux) Head(pattern string, handler http.HandlerFunc)
- func (mx *Mux) Method(method, pattern string, handler http.Handler)
- func (mx *Mux) MethodFunc(method, pattern string, handler http.HandlerFunc)
- func (mx *Mux) MethodNotAllowed(handler http.HandlerFunc)
- func (mx *Mux) NotFound(handler http.HandlerFunc)
- func (mx *Mux) Options(pattern string, handler http.HandlerFunc)
- func (mx *Mux) Patch(pattern string, handler http.HandlerFunc)
- func (mx *Mux) Post(pattern string, handler http.HandlerFunc)
- func (mx *Mux) Put(pattern string, handler http.HandlerFunc)
- func (mx *Mux) RegisterConstraint(name, expression string)
- func (mx *Mux) Route(pattern string, fn func(r Router)) Router
- func (mx *Mux) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (mx *Mux) Trace(pattern string, handler http.HandlerFunc)
- func (mx *Mux) Use(middlewares ...func(http.Handler) http.Handler)
- func (mx *Mux) With(middlewares ...func(http.Handler) http.Handler) Router
- type Option
- type Router
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func URLParam ¶
URLParam returns the value of the named regex capture group for the current request, or "" if no such group matched.
func URLParamFromCtx ¶
URLParamFromCtx returns the value of the named regex capture group stored in ctx, or "" if no such group matched.
func ValidPattern ¶
ValidPattern reports whether pattern is a valid route template. Route templates begin with '/', contain literal path segments, and may use :placeholder or *wildcard segments.
Types ¶
type Logger ¶
Logger is the minimal logging surface mux uses. *slog.Logger satisfies it directly, so New(WithLogger(slog.Default())) works without an adapter; other loggers need only a small shim.
type Middlewares ¶
Middlewares is a slice of standard middleware handlers.
type Mux ¶
type Mux struct {
// contains filtered or unexported fields
}
Mux routes HTTP requests using path templates.
func New ¶
New returns a newly initialized Mux that implements the Router interface, configured by the given options. Call New() for defaults, or pass options such as WithNotFoundHandler to customize behavior.
func (*Mux) Connect ¶
func (mx *Mux) Connect(pattern string, handler http.HandlerFunc)
Connect registers a CONNECT handler for pattern.
func (*Mux) Delete ¶
func (mx *Mux) Delete(pattern string, handler http.HandlerFunc)
Delete registers a DELETE handler for pattern.
func (*Mux) Get ¶
func (mx *Mux) Get(pattern string, handler http.HandlerFunc)
Get registers a GET handler for pattern.
func (*Mux) HandleFunc ¶
func (mx *Mux) HandleFunc(pattern string, handler http.HandlerFunc)
HandleFunc registers handler for all methods matching pattern.
func (*Mux) Head ¶
func (mx *Mux) Head(pattern string, handler http.HandlerFunc)
Head registers a HEAD handler for pattern.
func (*Mux) MethodFunc ¶
func (mx *Mux) MethodFunc(method, pattern string, handler http.HandlerFunc)
MethodFunc registers handler for method and pattern.
func (*Mux) MethodNotAllowed ¶
func (mx *Mux) MethodNotAllowed(handler http.HandlerFunc)
MethodNotAllowed sets the handler used when a path matches but its method does not.
func (*Mux) NotFound ¶
func (mx *Mux) NotFound(handler http.HandlerFunc)
NotFound sets the handler used when no route matches.
func (*Mux) Options ¶
func (mx *Mux) Options(pattern string, handler http.HandlerFunc)
Options registers an OPTIONS handler for pattern.
func (*Mux) Patch ¶
func (mx *Mux) Patch(pattern string, handler http.HandlerFunc)
Patch registers a PATCH handler for pattern.
func (*Mux) Post ¶
func (mx *Mux) Post(pattern string, handler http.HandlerFunc)
Post registers a POST handler for pattern.
func (*Mux) Put ¶
func (mx *Mux) Put(pattern string, handler http.HandlerFunc)
Put registers a PUT handler for pattern.
func (*Mux) RegisterConstraint ¶
RegisterConstraint sets the regular-expression fragment used by parameters with name in routes registered through this router scope. Constraints are inherited by child scopes and may be overridden there. It panics when the name or expression is invalid, when the name was already registered in this scope, or when routes have already been registered through this scope.
func (*Mux) Route ¶
Route creates a child router and mounts it at pattern. Once pattern matches, the child router owns that path namespace, including its 404 and 405 responses. The matched prefix is removed from the path used for child route matching; handlers continue to see the original request URL.
func (*Mux) Trace ¶
func (mx *Mux) Trace(pattern string, handler http.HandlerFunc)
Trace registers a TRACE handler for pattern.
type Option ¶
type Option func(*Mux)
Option configures a Mux at construction time. Pass options to New.
func WithLogger ¶
WithLogger sets the debug logger. By default the router logs nothing.
func WithMethodNotAllowedHandler ¶
func WithMethodNotAllowedHandler(h http.HandlerFunc) Option
WithMethodNotAllowedHandler sets the handler invoked when a route matches the request path but not its method.
func WithNotFoundHandler ¶
func WithNotFoundHandler(h http.HandlerFunc) Option
WithNotFoundHandler sets the handler invoked when no route matches the request path.
type Router ¶
type Router interface {
http.Handler
// Use appends one or more middlewares to the Router stack.
Use(middlewares ...func(http.Handler) http.Handler)
// Group adds an inline Router with a fresh middleware and constraint scope.
Group(fn func(r Router)) Router
// Route creates and mounts a child Router at pattern.
Route(pattern string, fn func(r Router)) Router
// RegisterConstraint defines the regular-expression fragment used for
// parameters with name in routes registered through this scope.
RegisterConstraint(name, expression string)
// Handle and HandleFunc add routes matching all HTTP methods.
Handle(pattern string, h http.Handler)
HandleFunc(pattern string, h http.HandlerFunc)
// Method and MethodFunc add routes matching method.
Method(method, pattern string, h http.Handler)
MethodFunc(method, pattern string, h http.HandlerFunc)
Connect(pattern string, h http.HandlerFunc)
Delete(pattern string, h http.HandlerFunc)
Get(pattern string, h http.HandlerFunc)
Head(pattern string, h http.HandlerFunc)
Options(pattern string, h http.HandlerFunc)
Patch(pattern string, h http.HandlerFunc)
Post(pattern string, h http.HandlerFunc)
Put(pattern string, h http.HandlerFunc)
Trace(pattern string, h http.HandlerFunc)
// NotFound defines a handler for unmatched routes.
NotFound(h http.HandlerFunc)
// MethodNotAllowed defines a handler for matched paths without a handler for
// the request method.
MethodNotAllowed(h http.HandlerFunc)
}
Router is the routing surface implemented by Mux.
Source Files