Go net/http ServeMux 路由冲突怎么判断：方法模式与注册顺序的边界

服务启动阶段突然因为路由注册 panic，通常不是“注册顺序写错了”这么简单。Go 1.22 之后，net/http.ServeMux 会把方法和通配符也纳入模式语义：重叠模式优先选择匹配集合更小的那一个；只有双方谁都不更具体时，注册才会冲突。理解这条规则，才能判断是应该保留两条路由，还是把模式改成不重叠。

ServeMux 的冲突判断与注册先后无关：先比较两个模式匹配的请求集合，能严格包含另一个的模式优先；互不包含时才会在注册阶段触发 panic。

先看服务为什么在注册阶段停住

下面这组模式都放进同一个 mux，用来观察“重叠”和“冲突”不是一回事：

mux := http.NewServeMux()
mux.HandleFunc("/posts/{id}", postByID)
mux.HandleFunc("/posts/latest", latestPost)
mux.HandleFunc("/{resource}/latest", resourceLatest)

前两条可以共存，因为 /posts/latest 只匹配一个固定路径，是 /posts/{id} 匹配集合的严格子集。第三条和第二条都能接住 /posts/latest，但一条在第一段更具体，另一条在第二段更具体，双方没有包含关系，因此在注册第二个相冲的模式时会 panic。

图：ServeMux 先在注册阶段比较模式关系，只有互不更具体的模式才进入冲突分支。

把“更具体”理解成请求集合

不要按字符串长度或通配符名字猜优先级。/posts/latest 只覆盖一个路径，而 /posts/{id} 可以覆盖 /posts/1、/posts/42 等多个路径，所以固定段模式更具体。{id} 和 {postID} 的名字不会参与比较，它们表达的是同一种单段通配。

子树模式也遵循同样的关系。/images/thumbnails/ 覆盖的路径集合小于 /images/，两条可以同时注册；请求落在 thumbnails 子树时，前者被选中，其余 images 子树再交给后者。

mux.HandleFunc("/images/", images)
mux.HandleFunc("/images/thumbnails/", thumbnails)

图：固定段、单段通配和子树前缀对应不同大小的请求集合，具体模式覆盖范围更窄。

方法模式会改变覆盖范围

方法是模式的一部分。GET /posts/{id} 只接收 GET 和 HEAD，而没有方法的 /posts/{id} 接收更宽的请求集合，因此前者更具体。代码可以这样写：

mux.HandleFunc("/posts/{id}", anyMethod)
mux.HandleFunc("GET /posts/{id}", readPost)

这两条不会因为同一路径而冲突。客户端发 GET 时命中 readPost，其他方法仍可落到 anyMethod。需要特别记住的是，ServeMux 会把 GET 的匹配范围包含 HEAD；不能把 HEAD 当成完全独立的第三种情况。

为什么“谁先注册”不是修复方案

有些路由器采用最后注册优先，但 ServeMux 的设计目标是注册顺序无关。下面两种写法都不能解决真正的冲突：

mux.HandleFunc("/posts/{id}", postByID)
mux.HandleFunc("/{resource}/latest", resourceLatest)

// 交换两条 HandleFunc 的顺序，结果仍然是冲突

如果启动时看到冲突 panic，先把两条模式放在纸上比较：它们是否覆盖相同请求？若相同，是否其中一个覆盖范围严格更小？如果两边都各有一个对方没有的具体段，就不是“顺序问题”，而是模式没有唯一胜者。更明确的路径，例如把资源名固定成 /posts/latest 或把通配段改成不同的静态前缀，通常比依赖隐式优先级更易维护。

主机模式是一个兼容性例外

大多数比较都同时看方法和路径；主机模式有一个兼容旧行为的例外。如果两个模式在其他维度上冲突，但其中一个带主机、另一个不带主机，带主机的模式可以优先：

mux.HandleFunc("example.com /posts/{id}", hostedPost)
mux.HandleFunc("/posts/{id}", fallbackPost)

这个例外只解决“有主机”和“无主机”的组合，不意味着任意两个不同主机都能互相覆盖。实际排查时还要确认请求的 Host 是否真的匹配；不要只因为程序成功启动，就把所有域名流量都当成了 hostedPost。

用最小测试确认最终 handler

把冲突判断和运行时选择分开测试会更清楚。注册一组合法的重叠模式后，用 httptest.NewRequest 构造实际请求，再观察响应是谁写出的：

req := httptest.NewRequest(http.MethodGet, "http://example.com/posts/latest", nil)
rr := httptest.NewRecorder()
mux.ServeHTTP(rr, req)

测试断言应覆盖固定路径、通配路径、GET、HEAD 和其他方法，而不是只断言 mux 能启动。若模式本身互不更具体，测试还没运行到请求阶段，注册动作就会 panic；这类问题应在路由表构建测试里尽早暴露。

常见问题

ServeMux 会按注册顺序选择 handler 吗？

不会。它按模式匹配的请求集合判断具体程度，注册顺序不应改变合法模式的选择结果。

通配符名字不同会改变优先级吗？

不会。{id} 和 {postID} 都是单段通配符，名字只影响代码读取路径值时的语义，不参与具体程度比较。

两个模式都能匹配时一定会 panic 吗？

不一定。若一个模式严格更具体，例如固定路径优于单段通配，二者可以共存；只有互相重叠且谁都不更具体时，注册才会 panic。

如何快速定位启动时的路由冲突？

记录触发 panic 的两条模式，分别列出它们能匹配的请求集合，再检查方法、路径段和主机。不要只交换 HandleFunc 的调用顺序。

把路由表验收收束成三问

每新增一条 ServeMux 模式，可以固定问三遍：它和现有模式是否重叠？如果重叠，哪一个覆盖范围更窄？若双方都不更具体，是否能用静态前缀、明确方法或独立主机把边界写出来？这三问能把启动时的 panic 转成可解释的路由设计决策，也让后续测试直接对应真实请求范围。