Go ServeMux 怎样按方法注册路由

如果一个接口既要处理 GET /users，又要处理 POST /users，在 Go 1.22 以前通常要先注册路径，再在处理函数里自己判断 r.Method。现在可以把方法直接写进 ServeMux 的模式字符串：mux.HandleFunc("GET /users", listUsers)。这样路由表本身就表达了方法边界，处理函数可以少一层分支。

按方法注册路由的最小写法是把 HTTP 方法放在路径前面，例如 GET /users 和 POST /users。其中 GET 会特别匹配 HEAD；路径能匹配但方法没有对应注册时，ServeMux 会返回 405。

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

方法写进模式字符串后，路由匹配发生了什么

ServeMux 的新模式可以理解成 [METHOD ][HOST]/[PATH]。本文只用方法和路径两部分：请求进入后，匹配器同时看 r.Method 与 r.URL.Path，再把请求交给更具体的处理函数。方法不再是处理函数内部才知道的条件。

因此，同一路径可以自然拆成两条规则：

mux.HandleFunc("GET /users", listUsers)
mux.HandleFunc("POST /users", createUser)

第一条只描述读取用户列表，第二条只描述创建用户。匹配规则变成路由声明的一部分，后续新增 PATCH 或 DELETE 时，也能直接看到它们是否已经被注册。

最小注册写法：同一路径分别处理 GET 和 POST

下面的例子使用一个独立的 ServeMux。两个处理函数故意返回不同的文字，方便读者在自己的环境中用请求方法观察分发结果。

package main

import (
    "fmt"
    "net/http"
)

func listUsers(w http.ResponseWriter, r *http.Request) {
    // GET 只负责读取资源，避免把写入逻辑混到查询处理函数里。
    fmt.Fprintln(w, "user list")
}

func createUser(w http.ResponseWriter, r *http.Request) {
    // POST 只负责创建动作，真实项目中可在这里解析请求体。
    w.WriteHeader(http.StatusCreated)
    fmt.Fprintln(w, "user created")
}

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("GET /users", listUsers)
    mux.HandleFunc("POST /users", createUser)

    // 显式传入 mux，确保服务使用本例的路由表。
    if err := http.ListenAndServe(":8080", mux); err != nil {
        // 服务退出时保留原因，便于区分端口占用等启动问题。
        panic(err)
    }
}

运行服务后，GET /users 会进入 listUsers，POST /users 会进入 createUser。这里的重点不是返回内容，而是每条模式已经把方法约束写清楚。

GET、HEAD、POST 和 405 怎么区分

方法匹配有一个容易漏掉的特殊规则：注册 GET 时，HEAD 也会被视为匹配。其他方法则需要精确注册。也就是说，下面四个请求的结果不能简单理解成“路径相同就都进入同一个函数”。

405 和 404 的区别在于：404 更像是没有找到这个路径；405 表示路径有对应路由，但当前 HTTP 方法不被允许。把方法写进模式后，ServeMux 能根据已有的路径和方法信息做出这个区分。

更具体的模式会优先匹配

ServeMux 不是简单按注册顺序选择处理函数，而是让更具体的模式优先。比如通用模式 /users 可以作为兜底，GET /users 只匹配 GET 和 HEAD，因此对这两种请求更具体。

mux.HandleFunc("/users", fallback)
mux.HandleFunc("GET /users", listUsers)

// GET /users 优先进入 listUsers；其他方法仍可落到 fallback。
// 若不希望 fallback 接收写入方法，就不要额外注册这个通用模式。

实际设计时要谨慎使用这种兜底：它会让没有单独注册的方法仍然有处理函数，不再触发 405。若接口需要明确拒绝未开放的方法，通常只注册允许的方法模式，让 ServeMux 保留 405 语义更清楚。

路径通配符和版本兼容要一起考虑

Go 1.22 的模式还支持路径通配符，例如 GET /users/{id}。在处理函数中可以通过 r.PathValue("id") 读取路径段，但这不改变方法匹配规则：方法仍然位于路径前面。

mux.HandleFunc("GET /users/{id}", func(w http.ResponseWriter, r *http.Request) {
    // PathValue 读取模式中的单段通配符，不要再手动切分 URL 字符串。
    id := r.PathValue("id")
    fmt.Fprintf(w, "user id=%s\n", id)
})

这套方法模式和通配符语法从 Go 1.22 开始增强。如果项目仍要运行在 Go 1.21 或更早版本，不能只把模式字符串改成新写法；旧运行时不会按同样规则解释它。升级前至少确认构建环境、部署镜像和本地开发版本一致，避免“本机能注册，线上启动就异常”的差异。

一段可直接改造的完整路由表

如果接口已经包含查询、创建和详情读取，可以把路由表集中写在初始化位置，让方法、路径和处理函数形成一张速查表：

func newMux() *http.ServeMux {
    mux := http.NewServeMux()

    // 同一路径的读写动作分开声明，路由表直接体现接口职责。
    mux.HandleFunc("GET /users", listUsers)
    mux.HandleFunc("POST /users", createUser)
    mux.HandleFunc("GET /users/{id}", getUser)

    return mux
}

func getUser(w http.ResponseWriter, r *http.Request) {
    // 通配符由 ServeMux 提取，处理函数只关心业务参数。
    fmt.Fprintf(w, "user id=%s\n", r.PathValue("id"))
}

改造旧代码时，可以按这三个动作推进：先把原来处理函数里的方法判断拆成独立函数，再把方法前缀写入模式，最后删除已经不会执行的重复判断。若某个路径需要继续接受多个方法，先确认这是有意的公共入口，而不是遗漏了方法约束。

最小排查清单

1. 确认运行时是 Go 1.22 或更高版本，并检查部署环境没有使用旧镜像。
2. 确认模式中的方法和路径之间只有一个空格，例如 POST /users。
3. 确认 GET 对 HEAD 的匹配是预期行为，不要为了 HEAD 再注册一条冲突规则。
4. 遇到 405 时，先看路径是否已注册，再看当前方法是否有对应模式；遇到 404 则优先检查路径本身。
5. 检查是否额外注册了无方法的通用路径，因为它可能把本来想要的 405 变成兜底处理。

相关问题

ServeMux 能不能把 GET 和 POST 注册到同一个处理函数？ 可以，分别注册相同函数即可；但如果两种方法的参数、响应或权限不同，拆开函数更容易维护。

为什么 HEAD 没有单独注册也能匹配 GET？ 这是 ServeMux 对 GET 的特殊规则，GET 模式同时覆盖 HEAD；其他方法仍需精确匹配。

为什么注册了 /users 后 DELETE 不再返回 405？ 因为无方法模式匹配所有方法。要让未开放方法自然得到 405，删除不必要的通用兜底模式，只保留允许的方法模式。