Go Reference ยท Networking and the Web
Go http.ServeMux type
Reference for Go http.ServeMux: pattern syntax with methods, hosts and wildcards, precedence rules, PathValue, automatic 404 and 405 answers, redirects and conflicts.
http.ServeMux is Go's built-in request router. It compares each incoming request with a table of registered patterns and calls the handler of the best match. Since Go 1.22 a pattern can include an HTTP method and named wildcards, which covers most routing needs without a third-party router.
A ServeMux is itself an http.Handler, so you pass it to a server or wrap it with middleware. Create your own with http.NewServeMux(); the package-level functions use the shared http.DefaultServeMux.
mux := http.NewServeMux() mux.HandleFunc("GET /items/{id}", showItem)
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
Syntax
func NewServeMux() *ServeMux func (mux *ServeMux) Handle(pattern string, handler Handler) func (mux *ServeMux) HandleFunc(pattern string, handler func(ResponseWriter, *Request)) func (mux *ServeMux) Handler(r *Request) (h Handler, pattern string) func (mux *ServeMux) ServeHTTP(w ResponseWriter, r *Request) func (r *Request) PathValue(name string) string func (r *Request) SetPathValue(name, value string)
Pattern syntax: [METHOD ][HOST]/[PATH]
| Pattern | Matches |
|---|---|
/about |
exactly /about |
/static/ |
/static/ and everything below it (subtree) |
/{$} |
only / (without it, / matches every path) |
/items/{id} |
/items/ plus exactly one segment, read with r.PathValue("id") |
/files/{path...} |
the rest of the path, including slashes |
GET /items |
GET and HEAD requests only |
example.com/ |
only requests with that Host |
Precedence: the most specific pattern wins, regardless of registration order: a literal segment beats a wildcard, and a pattern with a method beats one without. Two patterns that could match the same request and neither is more specific cause a panic at registration.
Automatic answers:
- No match:
404 Not Found. A path that matches only under other methods:405 Method Not Allowedwith anAllowheader. - A subtree pattern
/docs/redirects/docsto/docs/(301) unless/docsis registered. - Request paths with
.,.., or repeated slashes are redirected to their cleaned form. - Wildcards match whole segments;
/a/b{x}is invalid. A wildcard name may appear only once per pattern. - Path values are unescaped, so
%2Fin a wildcard becomes/inPathValue, but does not add a segment.
Usage notes
- Version note: method and wildcard patterns arrived in Go 1.22. In a single
main.gowithoutgo.mod, put//go:debug httpmuxgo121=0on top; in a module withgo 1.22or later it is already on. r.Pattern(Go 1.23) holds the matched pattern. It is handy for metrics, because it is the same for all ids.- Return custom 404/405 pages by wrapping the mux: call
mux.Handler(r)and check whether the pattern is empty. - Trailing slash behavior surprises people:
/images/is a subtree,/imagesis one path. Decide which you mean. - No regex, no groups, no per-route middleware in
ServeMux. Wrap handlers on registration, or wrap the whole mux. - Mount sub-apps with
http.StripPrefix("/api", apiMux)registered at/api/. - Register at start-up. Registration is safe while serving, but changing routes at run time is rarely a good idea.