Go net/http 怎么用 ServeMux 分组注册带公共前缀的路由

如果你想在 Go 标准库里做出类似“用户路由组”的效果，关键不是寻找一个额外的 Group API，而是把公共前缀作为注册约定集中管理。Go 1.22 及更高版本的 net/http.ServeMux 已经支持方法模式、路径通配符和子树匹配，因此可以用一个函数统一注册 /api/v1 下的路由。

先把公共前缀和根路径分开

公共前缀通常写成 /api/v1/，它代表一棵子树：/api/v1/users、/api/v1/users/42 等路径都可能落入这棵树。若只希望处理精确的前缀根，则应使用 /api/v1/{$}。这两个 pattern 看起来只差一个 {$}，匹配范围却完全不同。

还要留意结尾斜杠。注册 /api/v1/ 后，请求 /api/v1 通常会被 ServeMux 重定向到带斜杠的形式；如果接口契约不允许重定向，可以再单独注册无斜杠路径。

用注册函数集中挂载同一前缀下的路由

下面这个例子把“路由组”变成普通 Go 函数。函数内部仍然注册完整 pattern，所以 ServeMux 的匹配规则保持透明，测试时也能直接看到每条路由的真实边界。

package main

import (
    "fmt"
    "net/http"
)

func registerAPIRoutes(mux *http.ServeMux) {
    const prefix = "/api/v1"

    // 子树入口负责公共前缀下未被更具体路由接管的请求。
    mux.HandleFunc("GET "+prefix+"/", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintln(w, "api root")
    })

    // 动态段只占一个路径段，值从 PathValue 读取。
    mux.HandleFunc("GET "+prefix+"/users/{id}", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintf(w, "read user %s\\n", r.PathValue("id"))
    })

    // 创建接口只接受 POST，避免在处理器里重复判断方法。
    mux.HandleFunc("POST "+prefix+"/users", func(w http.ResponseWriter, r *http.Request) {
        w.WriteHeader(http.StatusCreated)
        fmt.Fprintln(w, "user created")
    })
}

func main() {
    mux := http.NewServeMux()
    registerAPIRoutes(mux)
    // 让服务器使用显式创建的 mux，而不是隐式 DefaultServeMux。
    _ = http.ListenAndServe(":8080", mux)
}

这里的 GET /api/v1/users/{id} 比 GET /api/v1/ 更具体，因此请求 GET /api/v1/users/42 会进入用户处理器。对没有对应方法的请求，ServeMux 会返回方法不允许的结果；处理器不必再写一层“是不是 POST”的分支。

用方法和通配符缩小匹配范围

pattern 的基本形状是 [METHOD ][HOST]/[PATH]。不写方法表示任意方法；写 GET 时还自动覆盖 HEAD，其他方法则按精确方法匹配。单段参数使用 {name}，例如 {id}；剩余所有路径段使用结尾的 {path...}。后者只能出现在 pattern 末尾。

不要把 {id} 当成任意字符串替换：它只匹配一个路径段；当路径中包含编码斜杠时，ServeMux 会按段进行解码。匹配关系冲突时，注册阶段就会 panic，因此应在服务启动时一次性完成路由注册。

斜杠、冲突和旧版本兼容怎么检查

上线前可以按下面的清单逐项确认：

• 公共前缀是否真的需要子树语义？需要精确根时改用 {$}。
• 同一路径的读写是否已经写进 pattern？没有方法的兜底路由不要意外接收修改请求。
• 动态段是否与静态段冲突？像 /users/latest 和 /users/{id} 要明确哪个模式更具体。
• 部署环境是否至少是 Go 1.22？Go 1.21 会把大括号当普通字符；临时兼容行为可通过 GODEBUG=httpmuxgo121=1 恢复。

这套写法适合中小型服务和标准库优先的项目。需要中间件链、参数校验、复杂嵌套组或运行时路由管理时，再考虑专门的路由库；不要为了“分组”而牺牲 ServeMux 本身清晰的匹配规则。

常见问题

ServeMux 能不能像框架一样直接创建 Group？

标准库没有独立的 Group 类型。用 registerAPIRoutes 这类函数集中注册完整 pattern，就是最简单且可测试的替代方式。

为什么 GET 路由也能响应 HEAD？

这是 ServeMux 的特殊规则。带 GET 的 pattern 同时匹配 HEAD；POST、PUT 等其他方法仍然要求精确匹配。

为什么访问 /api/v1 会跳到 /api/v1/？

因为以斜杠结尾的 pattern 表示子树，ServeMux 会把子树根规范化为带斜杠的路径。需要避免跳转时，单独注册不带斜杠的 pattern。