ServeMux模式匹配路由请求

Go 的 net/http.ServeMux 可以把请求的方法、主机和路径直接写进模式字符串。对于大多数中小型服务，先声明路由，再让 ServeMux 选择最具体的模式，就能避免在每个处理函数里手工判断 HTTP 方法和拆路径。

如果你使用 Go 1.22 或更新版本，推荐优先采用新模式：例如 GET /users/{id} 只接收 GET（同时匹配 HEAD），并通过 r.PathValue("id") 取得路径参数。旧式的 /users/ 仍然可用，但它表达的是一个子树，不是一个带参数的精确资源。

一句话结论：把固定部分写成字面量，把变化部分写成通配符，把方法写在路径前；多个模式同时命中时，ServeMux 按“最具体模式优先”选择，而不是按注册先后选择。

先把 ServeMux 模式拆成三部分

一个完整模式的形状是 [METHOD ][HOST]/[PATH]，三部分都可以省略。没有方法时匹配所有方法；写成 GET 时还会匹配 HEAD；其它方法必须精确相同。没有主机时匹配所有主机，带主机的模式只接收指定 Host。

package main

import (
	"fmt"
	"net/http"
)

func main() {
	mux := http.NewServeMux()

	// 方法写在路径前，明确只处理读取请求。
	mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintln(w, "ok")
	})

	// 主机限定只对 api.example.test 生效，路径仍是根路径。
	mux.HandleFunc("api.example.test/{$}", func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintln(w, "api root")
	})

	// 把 mux 交给服务器；服务会按请求选择已注册的模式。
	_ = http.ListenAndServe(":8080", mux)
}

这三部分的价值在于把路由约束提前放到注册阶段。处理函数可以专注于业务，不需要先判断 r.Method 再判断路径是否属于自己。

用通配符读取路径参数

Go 1.22 起，路径通配符必须是完整的路径段，形式为 {name} 或 {name...}，名称需要符合 Go 标识符规则。前者只匹配一个路径段，后者匹配模式末尾的剩余路径，并且可能包含斜杠。

package main

import (
	"fmt"
	"net/http"
)

func userHandler(w http.ResponseWriter, r *http.Request) {
	id := r.PathValue("id") // 读取单段通配符；这里得到的是 URL 路径值。
	fmt.Fprintf(w, "user id: %s\n", id)
}

func fileHandler(w http.ResponseWriter, r *http.Request) {
	path := r.PathValue("path") // {path...} 可包含后续的多个路径段。
	fmt.Fprintf(w, "file path: %s\n", path)
}

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("GET /users/{id}", userHandler)
	mux.HandleFunc("GET /files/{path...}", fileHandler)

	// 处理函数不再手工切分 URL；监听错误直接交给顶层返回。
	if err := http.ListenAndServe(":8080", mux); err != nil {
		panic(err)
	}
}

GET /users/{id} 只接受恰好两段路径，例如 /users/42；GET /files/{path...} 可以覆盖 /files/a.txt 和 /files/archive/2026/a.txt。通配符不能嵌在字面量中，像 /users/{id}.json 不是合法的完整段写法。

重叠模式按“最具体”取胜

ServeMux 允许模式重叠，但不依赖注册先后。一个模式如果匹配另一个模式请求集合的严格子集，就更具体。例如固定路径 /posts/latest 比 /posts/{id} 更具体，因此前者会处理 /posts/latest。

mux := http.NewServeMux()

// 通用模式覆盖所有两段式文章路径。
mux.HandleFunc("GET /posts/{id}", func(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintln(w, "generic post", r.PathValue("id"))
})

// 固定字面量匹配范围更小，因此会优先处理 /posts/latest。
mux.HandleFunc("GET /posts/latest", func(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintln(w, "latest post")
})

方法也参与具体性比较：GET /posts/{id} 只覆盖 GET 和 HEAD，比不写方法的 /posts/{id} 更具体。相反，如果两个模式互相有覆盖、但没有谁是另一个的严格子集，例如 /posts/{id} 和 /{resource}/latest，它们会冲突，注册时触发 panic。这个问题应在服务启动前修正，而不是依赖运行时顺序。

尾斜杠、根路径和 {$}

带尾斜杠的模式代表子树。注册 /images/ 后，/images/ 与其下的路径都能匹配；请求 /images 通常会被重定向到带尾斜杠的形式。若只想精确匹配根路径，应使用 /{$}，因为单独的 / 会匹配所有未被更具体模式接管的路径。

mux := http.NewServeMux()

// /assets/ 表示一个子树，而不是只匹配 /assets/ 本身。
mux.HandleFunc("GET /assets/", func(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintln(w, "asset subtree")
})

// /{$} 只匹配根路径，不会吞掉其它未知地址。
mux.HandleFunc("GET /{$}", func(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintln(w, "home")
})

如果接口设计要求同时保留不带尾斜杠的资源名，可以另外注册精确路径，例如 /assets；这样就不会把是否加斜杠交给 ServeMux 的子树重定向规则。这个选择应和 API 文档、缓存键以及客户端行为保持一致。

升级 Go 版本时要检查哪些地方

ServeMux 的模式语义在 Go 1.22 有明显增强：花括号从普通字面量变成通配符语法，路径按段进行解码，非法模式会在注册时 panic。旧项目如果曾经把 /{x} 当作字面量路径，需要在升级前搜索这些注册语句。

如果暂时必须维持 Go 1.21 的旧行为，可以在进程启动时设置 GODEBUG=httpmuxgo121=1。它是迁移缓冲，不应替代对新模式的整理；新代码应明确写出方法、通配符和精确边界。

# 只在迁移旧项目时临时使用旧版 ServeMux 语义。
GODEBUG=httpmuxgo121=1 go run ./cmd/server

日常注册可以按下面的判断清单收敛：

常见问题

ServeMux 是按注册顺序匹配吗？不是。重叠模式按最具体模式优先，注册顺序不应作为业务逻辑的一部分。

为什么 GET /x 也能处理 HEAD？这是 ServeMux 对 GET 的特殊规则；除 GET 外，方法模式通常需要精确相同。

为什么注册路由时直接 panic？常见原因是模式语法非法，或者新模式与已注册模式互相冲突。把模式集中注册并在启动阶段尽早暴露冲突，通常比运行时排查更容易。

还需要第三方路由器吗？ServeMux 已覆盖方法、主机、通配符和具体性优先等常见需求；如果项目需要更复杂的参数约束、插件生态或特殊中间件，再评估第三方方案。

小结

ServeMux 的核心不是记住很多字符串，而是理解模式代表的请求集合：字面量越具体，方法限制越窄，固定主机越明确，匹配范围就越小。用 PathValue 读取通配符，用 /{$} 区分精确根路径，用单独的注册处理尾斜杠，升级 Go 时再检查花括号和冲突模式，就能让标准库路由保持清晰可预测。

资料来源

Go 官方路由增强说明：https://go.dev/blog/routing-enhancements

net/http ServeMux 文档：https://pkg.go.dev/net/http#ServeMux