Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท Networking and the Web

Go http.HandleFunc() function

Reference for Go http.HandleFunc and ServeMux.HandleFunc: register a function for a pattern, method and wildcard patterns, duplicates, and the global mux risk.

http.HandleFunc(pattern, fn) registers an ordinary function to handle requests whose path matches pattern. The function takes an http.ResponseWriter and a *http.Request. ServeMux.HandleFunc does the same on a mux you created.

The package-level http.HandleFunc adds the route to http.DefaultServeMux, a global shared by every package in the program, and http.ListenAndServe(addr, nil) serves that mux. Prefer your own http.NewServeMux(), so nothing else (including imported packages) can add routes to your server.

Go
mux := http.NewServeMux()
mux.HandleFunc("GET /hello", func(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintln(w, "hi")
})

Try it

Go Patterns with methods and wildcards

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 Duplicate patterns panic

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 HandleFunc(pattern string, handler func(ResponseWriter, *Request))
func (mux *ServeMux) HandleFunc(pattern string, handler func(ResponseWriter, *Request))
func Handle(pattern string, handler Handler)
func (mux *ServeMux) Handle(pattern string, handler Handler)
Name Description
pattern [METHOD ][HOST]/[PATH]. See http.ServeMux for the full rules.
handler The function to call. It is wrapped in http.HandlerFunc.

Returns: nothing.

Errors and edge cases:

  • HandleFunc panics if the pattern is invalid, conflicts with an earlier pattern, or the handler is nil. Registering routes is start-up code, so the panic shows up immediately.
  • A pattern ending in / matches the whole subtree (/static/ matches /static/a/b). A pattern without a trailing slash matches only that path. {$} anchors an exact match for /.
  • Without a method in the pattern, all methods are accepted. With GET, HEAD is accepted as well.
  • Method patterns and wildcards need Go 1.22. In a single file without go.mod, add //go:debug httpmuxgo121=0; inside a module declaring go 1.22 or later, it is the default.

Usage notes

  • Handler functions are not middleware. They end the request. To run common code before them, wrap them: mux.Handle("GET /x", logging(http.HandlerFunc(fn))).
  • HandleFunc versus Handle: use Handle when you already have a type with ServeHTTP; use HandleFunc for plain functions.
  • Close over dependencies. A common style is a function that takes a database or logger and returns the handler: func listUsers(db *DB) http.HandlerFunc.
  • Do not use DefaultServeMux in libraries or large programs. Packages like net/http/pprof register on it as a side effect of being imported, which can expose debugging endpoints by accident.
  • Handlers run concurrently, one goroutine per request. Protect shared state with a mutex or channel.
  • Return after writing an error. http.Error(w, "bad", 400) does not stop your function; add return.