Go http.ServeMux 方法模式如何同时限制路径和请求方法

如果一个接口只允许读取用户资料，旧式写法通常是注册 /users/，再在处理函数里手动判断 r.Method。这样很容易漏掉校验，让 POST 或 DELETE 也进入读取逻辑。Go 1.22 及以上版本可以直接把方法写进 http.ServeMux 模式：GET /users/{id} 同时限定了请求方法和路径形状。

想让同一个资源路径按方法分流，就使用“方法 + 空格 + 路径”的模式；GET 还会匹配 HEAD，其他方法按精确方法匹配。路径中的 {id} 是单段通配符，可用 r.PathValue("id") 读取。

把方法和路径写进同一个模式

模式的一般形式是 [METHOD ][HOST]/[PATH]。本例只需要方法和路径，因此在方法后放一个空格，再写资源路径。{id} 必须占据完整的一段，/users/42/profile 不会被 /users/{id} 当成同一个路径匹配。

package main

import (
	"fmt"
	"log"
	"net/http"
)

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

	// GET 模式只接收 GET 和 HEAD，并把用户编号限制为一个路径段。
	mux.HandleFunc("GET /users/{id}", func(w http.ResponseWriter, r *http.Request) {
		id := r.PathValue("id") // 读取 ServeMux 已捕获的 id，不再手动切分 URL。
		fmt.Fprintf(w, "read user %s", id)
	})

	// 写入和删除分别绑定方法，避免请求误入读取处理器。
	mux.HandleFunc("POST /users/{id}", updateUser)
	mux.HandleFunc("DELETE /users/{id}", deleteUser)

	// 启动失败时记录错误；正式服务通常还应配置超时和优雅退出。
	if err := http.ListenAndServe(":8080", mux); err != nil {
		log.Fatal(err)
	}
}

func updateUser(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintf(w, "updated user %s", r.PathValue("id"))
}

func deleteUser(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintf(w, "deleted user %s", r.PathValue("id"))
}

这段注册关系的重点不是处理器内部业务，而是模式本身：GET /users/{id}、POST /users/{id} 和 DELETE /users/{id} 共享路径形状，却各自拥有方法边界。路径参数从模式中捕获后，由 PathValue 按名称读取。

Go ServeMux 如何判断请求方法

ServeMux 会把方法也纳入匹配集合。没有方法的模式匹配所有方法；带方法的模式只匹配声明的方法，不过 GET 是特殊情况，它同时匹配 HEAD。因此下面这张表比“注册顺序”更重要：ServeMux 选择的是更具体的模式。

例如只注册 GET /users/{id} 后，POST /users/42 的路径形状虽然命中，但没有对应方法处理器，ServeMux 会将它视为方法不允许，并在响应中提供 Allow。如果同时注册了无方法的 /users/{id}，POST 就可能落到这个兜底处理器，严格的方法限制也就被自己放宽了。

路径通配符、尾斜杠和兼容边界

单段通配符适合用户编号、订单号这类稳定的路径字段：/users/{id} 可以读取 42，但不会吞掉后续路径。需要匹配剩余多段路径时，使用末尾的 {path...}，例如 /files/{path...}。这两种写法都要求通配符是完整路径段，不能把它嵌入普通文字中。

带尾斜杠的子树模式还有一个容易忽略的行为：注册 /users/ 时，请求 /users 可能被重定向到 /users/。如果必须只处理精确的尾斜杠路径，可以使用 /users/{$}。不要只看字符串是否“看起来相似”，要按 ServeMux 的路径集合判断。

方法模式来自 Go 1.22 的路由增强。运行在 Go 1.21 或更早版本的项目不能依赖这套语法；要么升级工具链，要么继续使用普通路径模式并在处理器中显式校验方法。httpmuxgo121=1 是兼容旧路由行为的开关，不会把旧版本变成支持新方法模式的版本。

上线前用一张清单检查注册关系

• 同一资源的读写删操作是否分别声明了方法，而不是全部挂在一个前缀处理器上？
• 是否确认 GET 会覆盖 HEAD，并为需要独立 HEAD 响应的场景单独设计？
• 通配符是否是完整路径段，是否误把多段路径当成单段参数？
• 是否检查了方法不匹配时的 405 和 Allow，以及无方法兜底是否过于宽泛？
• 是否分别验证了 /users、/users/、/users/42 和 /users/42/profile？

相关问题

GET 模式为什么也会进入 HEAD 请求？

这是 ServeMux 的明确特殊规则，GET 模式同时覆盖 HEAD。如果 HEAD 需要完全不同的处理方式，应把需求从通用 GET 处理器中拆出来重新设计。

同一路径注册多个方法会冲突吗？

仅方法不同通常可以共存，因为方法属于匹配集合的一部分。真正要留意的是两个模式互相覆盖、却没有谁更具体的情况，这类注册可能在启动时触发冲突。

为什么写了方法模式仍然没有得到 405？

优先检查是否注册了同路径的无方法模式，例如 /users/{id}。它匹配所有方法，会把原本应该暴露为方法不允许的请求接走。

官方资料：https://pkg.go.dev/net/http；路由增强说明：https://go.dev/blog/routing-enhancements。