Skip to content
Tutorials Center
My learning

Topics

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.

Go
mux := http.NewServeMux()
mux.HandleFunc("GET /items/{id}", showItem)

Try it

Go Wildcards, precedence and automatic answers

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.

Go Inspecting a match without a server

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

Go
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 Allowed with an Allow header.
  • A subtree pattern /docs/ redirects /docs to /docs/ (301) unless /docs is 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 %2F in a wildcard becomes / in PathValue, but does not add a segment.

Usage notes

  • Version note: method and wildcard patterns arrived in Go 1.22. In a single main.go without go.mod, put //go:debug httpmuxgo121=0 on top; in a module with go 1.22 or 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, /images is 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.