Go ServeMux 同时注册方法和路径模式时怎么判断匹配优先级

ServeMux 比较的是模式能匹配的整个请求集合：如果一个模式匹配的请求是另一个模式的严格子集，它就更具体，优先匹配。方法与路径要一起比较；不存在普遍的“方法永远优先”或“路径永远优先”。两个模式有交集却互不包含时，会在注册时冲突，而不是按注册先后挑一个。

官方地址：https://pkg.go.dev/net/http#ServeMux

路由增多后，先后顺序为什么不够用

设想一个库存接口最初只有 /inventory/ 子树入口，随后增加单件读取、汇总读取以及单独的 HEAD 处理。路由数量增加后，如果仍用“把特殊接口写在前面”的思路维护，就很难解释哪些组合能共存、哪些会直接注册失败。

这个场景讨论 Go 1.22 起引入的方法与通配符模式语义，不把旧版最长路径经验直接套用到新模式。这里只讨论路由匹配，不延伸中间件、数据库访问或接口吞吐量。路由设计是否清楚，要看新增模式与既有模式的关系，而不是凭一份没有实际测量的性能结论。

把方法和路径一起当作请求集合

先固定同一主机条件。没有方法前缀的模式覆盖所有方法；GET 模式还覆盖 HEAD；其他明确方法只覆盖自身。路径中的 {sku} 表示单个路径段，固定的 summary 则只对应这个字面段。比较时，把这两个维度同时放进集合。

因此 GET /inventory/summary 比 GET /inventory/{sku} 更具体：前者能匹配的每个请求，后者都能匹配，但后者还包含 A17、B28 等其他单段路径。相同固定路径下，HEAD 模式又比 GET 模式更具体，因为 HEAD 集合包含在 GET 与 HEAD 的合集中。

“更具体”是一种包含关系，不是给方法、字符串长度、通配符个数各打分后求和。变量名 sku 改成 id 不会缩小集合，也就不会凭名称变化产生新的优先级。

建立有包含关系的路由表

下面用自建 ServeMux 注册四种模式。main 只展示通过 Handler 查看选中模式的写法，不启动监听服务；代码供读者在自己的 Go 环境使用，本文未执行示例。

package main

import (
    "fmt"
    "net/http"
)

func buildMux() *http.ServeMux {
    mux := http.NewServeMux()
    // 注册顺序不充当优先级；这里故意先放宽泛的子树模式。
    mux.HandleFunc("/inventory/", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintln(w, "inventory fallback")
    })
    mux.HandleFunc("GET /inventory/{sku}", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintln(w, "item", r.PathValue("sku"))
    })
    mux.HandleFunc("GET /inventory/summary", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintln(w, "summary")
    })
    mux.HandleFunc("HEAD /inventory/summary", func(w http.ResponseWriter, r *http.Request) {
        // HEAD 单独注册时，只准备响应头，不输出响应正文。
        w.Header().Set("X-Route", "summary-head")
    })
    return mux
}

func main() {
    mux := buildMux()
    cases := []struct{ method, path string }{
        {"GET", "/inventory/summary"},
        {"HEAD", "/inventory/summary"},
        {"GET", "/inventory/A17"},
        {"POST", "/inventory/A17"},
        {"GET", "/inventory/A17/detail"},
    }
    for _, c := range cases {
        req, err := http.NewRequest(c.method, c.path, nil)
        if err != nil { panic(err) }
        // Handler 只用来查看选中的模式，不直接调用它执行业务。
        _, pattern := mux.Handler(req)
        fmt.Printf("%s %s => %s\n", c.method, c.path, pattern)
    }
}

表格是规则推导，不是本机执行日志。正常服务将请求交给 mux.ServeHTTP 分发时，通配符处理器可用 PathValue 取得匹配值；上例中的 Handler 查询仅用于查看模式，不等同于完成分发，也不要依赖它为请求填好通配符值。

两个方向各自更具体时会发生什么

把原来的 GET 单段读取保留，再尝试注册没有方法前缀的 /inventory/summary，就会出现交叉：GET /inventory/summary 同时属于两者；GET /inventory/A17 只属于单段读取模式；POST /inventory/summary 只属于无方法汇总模式。

双方都存在对方覆盖不到的请求，因此互不包含。路径一侧更具体，方法一侧更具体，不能凭直觉宣布任何一方获胜。这是注册冲突，Handle 或 HandleFunc 会 panic；交换两条注册语句顺序也不能解决。

若汇总只需要读取，把它明确为 GET /inventory/summary，就与示例形成清楚的子集关系。若汇总确实需要其他方法，按实际需求注册明确的方法模式，而不是无意中开放所有方法。修改应来自接口需求，不应只为让注册通过而随意改变允许方法。

扩展路由时需要接受的取舍

子树兜底为接口扩展提供方便，但也改变未声明方法的表现。示例中的 POST 交给兜底处理器，并不会因为旁边注册了 GET 单件接口就自动得到 405。若不希望接收这些请求，应收窄兜底的业务职责或在其内部明确拒绝，而不要误以为方法路由替整个子树作了限制。

还要区分 /inventory/ 与 /inventory/{$}：前者覆盖子树，后者只匹配带尾斜杠的那个根路径。对省略尾斜杠的请求还可能涉及重定向；不要把它误认为“某个短模式抢走请求”。涉及主机限定时还有兼容性例外，本文的例子都没有主机前缀。

如果旧项目启用了 httpmuxgo121=1，不能按这里的新模式语义解释结果。评估新增路由时应确认项目所用 Go 版本与实际兼容配置。本文给出的结果来自规则与示例推导，没有发布后流量或线上效果数据。

几个常见匹配疑问

GET 模式会不会接收 HEAD？

会。需要 HEAD 专属处理时可以单独注册同路径 HEAD 模式，它覆盖的请求更少，因此更具体。

把 {sku} 改成 {name} 能消除冲突吗？

不能。变量名影响取值名称，不改变可匹配的请求范围。相同覆盖集合的重复模式不会因此变成可分辨路由。

为什么固定路径也不能保证优先？

固定路径只缩小路径维度。若另一模式缩小方法维度，仍可能形成有交集、互不包含的组合；先列出双方独有请求，比记一句“固定优先”更可靠。

资料：ServeMux 文档、Go 路由模式设计说明、模式比较实现。