Go net/http使用ServeMux注册方法和路径的路由结构

如果标准库路由仍然只注册 /orders/，再把 GET、POST 和订单编号都塞进同一个处理函数，代码很快会变成一串方法判断和字符串切割。Go 1.22 起，net/http.ServeMux 可以直接在模式中声明方法、路径和通配符：路由表负责匹配，处理函数只负责业务。

推荐把一条路由看成“方法 + 资源路径 + 处理函数”。例如 GET /orders/{id} 只接受读取订单的请求，POST /orders 只负责创建订单；路径参数通过 Request.PathValue 读取。

先把方法和路径写成路由契约

注册前先确定三件事：资源的集合路径是什么、单个资源如何表示、每个动作允许什么 HTTP 方法。集合通常用 /orders，单个订单用 /orders/{id}，不要先注册一个宽泛的 /orders/ 再让 handler 自己猜请求意图。

这样的拆分让调用方和维护者都能从路由表看懂接口边界，也把错误方法尽早交给 ServeMux 处理。图 1 用一张静态结构图展示方法、路径模式与处理函数的对应关系。

用 ServeMux 注册方法与路径

Go 1.22 及以上可以把方法前缀直接写进 HandleFunc 的 pattern。下面的例子同时展示集合资源、单资源和通配路径；代码中的注释只说明关键决策，不把业务实现伪装成完整服务。

package main

import (
    "fmt"
    "net/http"
)

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

    // 集合资源只允许创建，避免把 POST 分支混进读取处理器。
    mux.HandleFunc("POST /orders", createOrder)
    // GET 会同时覆盖 HEAD，适合只返回资源表示的读取接口。
    mux.HandleFunc("GET /orders/{id}", getOrder)
    // 通配符必须位于路径段中，文件型剩余路径放在模式末尾。
    mux.HandleFunc("GET /assets/{path...}", serveAsset)

    // 生产代码应配置超时；这里关注路由表本身的结构。
    _ = http.ListenAndServe(":8080", mux)
}

func createOrder(w http.ResponseWriter, r *http.Request) {
    // 业务层只接收已经通过方法和路径匹配的请求。
    fmt.Fprintln(w, "created")
}

func getOrder(w http.ResponseWriter, r *http.Request) {
    // PathValue 读取命名通配符，不需要手工切割 URL.Path。
    id := r.PathValue("id")
    fmt.Fprintln(w, "order:", id)
}

func serveAsset(w http.ResponseWriter, r *http.Request) {
    // 剩余路径可能包含多个段，先做业务层的安全与存在性检查。
    fmt.Fprintln(w, "asset:", r.PathValue("path"))
}

模式中的方法和路径之间用空格分隔。命名通配符 {id} 匹配一个路径段，{path...} 匹配末尾的多个路径段。GET 还有一个特殊行为：它也匹配 HEAD，因此不必为普通只读接口重复注册 HEAD。

用 PathValue 取参数并保持处理器单一职责

路径参数是路由匹配结果，不是业务输入校验的替代品。r.PathValue("id") 取到的是字符串，仍需在 handler 或服务层验证格式、权限和资源是否存在。对整数订单号，可以先解析，再把解析错误转换成 400，而不是让异常值进入查询层。

func getOrder(w http.ResponseWriter, r *http.Request) {
    idText := r.PathValue("id")
    if idText == "" {
        // 通配符缺失时不应继续访问存储层。
        http.Error(w, "missing order id", http.StatusBadRequest)
        return
    }

    // 这里可继续 strconv.Atoi，并对越界或非法字符返回 400。
    fmt.Fprintf(w, "lookup order %s", idText)
}

图 2 以“请求路径—命名通配符—处理器参数”的关系说明这条数据边界。它是文章配套的原创结构说明图，不是浏览器、终端或真实服务截图。

处理优先级、冲突和旧版本兼容

ServeMux 采用“更具体的模式优先”原则。例如 GET /orders/{id} 比没有方法限制的 /orders/{id} 更具体，字面路径 /orders/latest 又比通配符路径更具体。不要依赖注册先后顺序来修复重叠路由。

如果两个模式互相都不比对方具体，注册阶段可能直接因为冲突而 panic。把路由表集中在初始化位置，并在测试中覆盖重叠模式，能让问题在服务启动前暴露。Go 1.22 以前，ServeMux 不支持方法前缀和命名通配符；迁移时应把方法判断暂留在旧 handler 中，确认构建环境升级后再切换模式语法，不要把新语法直接投放到旧版本编译链。

用请求矩阵验收路由结构

测试时优先用 httptest.NewRequest 和 httptest.NewRecorder 构造请求，验证状态码、命中的处理器和参数值。最终目标不是让模式写得更复杂，而是让错误方法、错误路径和业务参数分别在正确的层处理。

常见延伸问题

ServeMux 可以同时注册同一路径的 GET 和 POST 吗？ 可以，方法前缀使它们成为不同模式；但要避免再添加语义重叠且无法比较具体性的模式。

为什么 PathValue 取不到值？ 只有通过 ServeMux 模式匹配的请求才会自动填充命名通配符；直接调用处理器或使用旧式手工路由时，需要自己传递或解析参数。

旧项目必须立刻改成新写法吗？ 不必。先确认 go.mod、CI 和部署环境都使用支持新模式的 Go 版本，再按请求矩阵逐条迁移。

参考：Go 官方 net/http 文档与《Routing Enhancements for Go 1.22》对方法匹配、通配符、优先级和兼容行为的说明。