[!info] related notes

• 所属 MOC：Go Web 与后端 · 学习路线
• 前置概念：net/http、HTTP 中间件
• 后续概念：分层、API 设计、认证
• 容易混淆：查询参数 vs 路径参数、尾部斜杠重定向、框架路由器语法

Go 路由模式

这个概念为什么会出现

HTTP 服务的第一道分发问题是：

给定 METHOD + path (+ 有时 host)，调用哪个处理函数？

若每个服务都手写 if r.URL.Path == ...，会迅速失去：

• REST 资源层次可读性
• 路径参数提取
• 方法级 405/404 语义
• 按子树挂载中间件的能力

因此需要路由器（router / ServeMux）：把「注册表」与「匹配算法」从业务 Handler 中拆出。Go 长期以标准库 http.ServeMux 为中心；Go 1.22 起增强 pattern，使多数中小 API 不必强依赖第三方路由。第三方库（chi、gorilla/mux、框架内置路由）则在分组、中间件子树、正则约束等处补强。

[!abstract] 一句话理解 路由 = 模式注册 + 请求匹配 + 参数提取；标准库 1.22+ 已支持 "GET /users/{id}" 与 PathValue，分组与子树中间件仍是组织大型 API 的关键工程手段。

最小可运行示例

先把示例放进业务场景，再看代码：

场景：用户资源 REST——按 ID 查询 + 创建

用户服务暴露：

• GET /users/{id} → 资料页按路径参数取用户
• POST /users → 注册创建

Go 1.22+ ServeMux 可直接写 "GET /users/{id}"，用 r.PathValue("id") 取段；
不必再手写一长串 if r.URL.Path。

本例会 listen；用 curl 分别打 GET/POST。
需要 Go 1.22+（PathValue / 方法 pattern）。

package main

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

// getUser 资料页：从路径取出用户 id 并回显（真实项目再查库）。
//
// 业务意图：/users/42 → id="42"；id 是字符串，数值解析/校验在业务侧做。
// 教学点：Go 1.22+ PathValue；{id} 只匹配单段。
func getUser(w http.ResponseWriter, r *http.Request) {
	id := r.PathValue("id")
	// 演示：生产会 Validate id 再调 service。
	fmt.Fprintf(w, "user=%s\n", id)
}

// createUser 注册：POST 成功返回 201（body 解析见 validation 篇）。
func createUser(w http.ResponseWriter, r *http.Request) {
	w.WriteHeader(http.StatusCreated)
	_, _ = w.Write([]byte("created\n"))
}

func main() {
	mux := http.NewServeMux()
	// pattern 含方法：GET 不会误进 create；POST 不会误进 get。
	mux.HandleFunc("GET /users/{id}", getUser)
	mux.HandleFunc("POST /users", createUser)

	log.Println("listen :8080")
	log.Fatal(http.ListenAndServe(":8080", mux))
}

建议运行：

go run .
# 另开终端：
curl -s localhost:8080/users/42
curl -s -o /dev/null -w '%{http_code}\n' -X POST localhost:8080/users

期望：

user=42
201

结合场景再看三个关注点

1. pattern 可含 HTTP 方法
   路由表同时表达资源与动词，减少 handler 内 r.Method 分支。

2. {id} 是单段路径参数
   /users/42/orders 不会被 /users/{id} 整段吃掉；多段用 {path...}。

3. 参数恒为 string
   资料页若要 int64 id，需 strconv + 校验；路由只负责匹配与提取。

核心概念与准确模型

匹配输入是什么

典型匹配键：

• 方法（GET/POST/…）
• 路径（规范化后的 URL path）
• （可选）host

查询字符串不参与路由匹配，用 r.URL.Query() 自行解析。

Go 1.22+ ServeMux pattern

官方行为见 net/http ServeMux 与 Go 1.22 release notes — Enhanced routing。

常见写法：

mux.HandleFunc("GET /items/{id}", getItem)
mux.HandleFunc("GET /files/{path...}", getFile) // 通配多段
mux.HandleFunc("/health", health)             // 此 pattern 匹配所有方法

语法	含义
GET /users/{id}	GET 与 HEAD，单段参数
{name...}	匹配剩余路径，可为空；只能放在 pattern 末尾
/users/{$}	精确匹配带尾斜杠的 /users/，不匹配其子路径
更具体 pattern	优先于更泛化 pattern

提取：

id := r.PathValue("id")

优先级与「更具体」

标准库比较 pattern 匹配的请求集合：严格子集更具体。相同路径上，带方法的模式比不带方法的更具体；相同方法下，静态段可比变量段更具体。/ 是路径兜底。

若两个模式重叠却互不包含，注册会 panic，例如 GET / 与 /index.html。兼容性例外是带 host 的模式可优先于与之冲突的不带 host 模式。注册顺序不会解决冲突。

尾部斜杠

/users 是精确路径，/users/ 注册的是整棵子树。仅注册后者时，请求 /users 会被重定向到 /users/；单独注册 /users 可覆盖该行为。/users/{$} 可用于只匹配子树根。重定向状态需按目标 Go 版本核对：Go 1.22 使用 301，本次 Go 1.26.8 实测为 307。301 可能使客户端改变方法，307 要求保留方法；写操作仍应直接使用约定 URL，并测试客户端的请求体重放能力。

路径参数 vs 查询参数

	路径参数	查询参数
例子	/users/42	/users?page=2
路由	参与匹配	不参与
语义	资源身份/层级	过滤、分页、排序、可选开关
校验	解析 id、uuid	默认值与范围检查

第三方：chi（轻量、贴近标准库）

r := chi.NewRouter()
r.Use(middleware.RequestID, middleware.Recoverer)

r.Route("/api", func(r chi.Router) {
	r.Use(AuthMiddleware)
	r.Route("/users", func(r chi.Router) {
		r.Get("/", listUsers)
		r.Post("/", createUser)
		r.Get("/{id}", getUser)
	})
})

• Use：子树中间件
• Route：前缀分组
• 参数：chi.URLParam(r, "id")；示例中的 getUser 需按此取值，不能假定第三方路由自动填充标准库 PathValue

适合：标准库 Handler 生态 + 需要清晰分组时。

gorilla/mux（正则与丰富匹配条件）

r := mux.NewRouter()
r.HandleFunc("/users/{id:[0-9]+}", getUser).Methods(http.MethodGet)

截至 2026-10-06，gorilla/mux 仓库 的 GitHub 状态为未归档；不能沿用旧归档状态判断当前项目。示例参数需用 mux.Vars(r)["id"] 获取，不直接复用依赖 r.PathValue 的 handler。选型与迁移应核对正则、匹配顺序和中间件差异。

框架内置路由（Gin / Echo 等）

提供 r.GET、组 Group、参数 :id 等语法糖，底层仍是「注册 + 匹配 + 中间件链」。理解标准库后，框架路由是同一问题的另一套 API，不是全新理论。

方法不允许与 404

良好路由层应区分：

• 404：路径无任何匹配
• 405：路径存在但方法不支持，响应必须带 Allow 头；Go 1.22+ ServeMux 会生成该头

不同实现完善程度不同；若标准库行为不满足产品语义，可在外层统一包装。

与中间件组合

api := http.NewServeMux()
api.HandleFunc("GET /api/me", me)

root := http.NewServeMux()
root.Handle("/api/", auth(api)) // 不剥离前缀，子 mux 仍收到 /api/me
root.HandleFunc("GET /healthz", healthz)

生产中更常见：

1. 全局：chain(mux, recover, requestID, accessLog)
2. 子树：仅 API 组套 Auth
3. 特例：webhook 验签单独挂载

详见 go-http-middleware。

设计动机

1. 稳定的资源 URL 作为 API 合同
2. 把分发从业务代码挪走，Handler 只处理「已命中的用例」
3. 让中间件按子树挂载，避免全局 Auth 误伤 /healthz
4. 在标准库足够时减少依赖（运维、审计、供应链更简单）

边界情况与反直觉行为

1. {id} 匹配一个 URL 段，但逐段解码后可含 /：/users/a%2Fb 的 id 为 a/b。不能把参数未经校验就当作安全文件名；多段通配用 {path...}。
2. PathValue 返回 string；未设置参数会返回空串，{path...} 也可捕获空串。单段 {id} 不匹配空段。
3. Host 模式（若使用）让同一 path 按域名分发，本地测试易漏。
4. 注册冲突 panic 发生在初始化，CI 必须真正执行到注册代码。
5. 代理与前缀：反代剥离 /api 前缀时，应用内 pattern 要匹配剥离后的路径；对外文档保留外部 URL。
6. 大小写与清理：path 清理规则以 net/http 为准，不要假设与前端路由器完全一致。
7. HEAD/GET：标准库 GET pattern 匹配 HEAD，显式 HEAD pattern 更具体；其他路由库需单独核对。GODEBUG=httpmuxgo121=1 会恢复旧 ServeMux 行为。

常见误区

[!warning] 常见误区：Go 1.22 之前的经验直接套用 错误：认为标准库永远不能方法匹配、不能 path 参数。
正确：升级到 1.22+ 后重新评估是否还需要第三方路由器。

[!warning] 常见误区：在路由器里做业务校验 错误：路由层写满「用户是否拥有该订单」等领域规则。
正确：路由只分发；授权与领域规则在中间件/Service。

[!warning] 常见误区：查询参数当路径设计核心 资源路径与 query 应按 API 合同分工；/users/1 适合表达资源层级，但带 query 的 URL 也可以缓存，不能把路径样式当作缓存能力保证。

[!warning] 常见误区：忽略尾部斜杠与重定向 错误：客户端 POST 被 301 成 GET 丢 body。
正确：统一 URL 规范，测试 POST/PUT 不依赖隐式重定向。

工程实践

1. 模块化注册：func MountUsers(mux *http.ServeMux, h *UserHandler)，避免所有路由堆在 main。
2. 探针避免强制用户登录，但需限定可达范围；指标与详细诊断按暴露面单独控权，见 go-health-check-endpoint。
3. API 版本：/v1/... 前缀或 host 策略写进路由约定。
4. 参数校验：strconv/uuid.Parse 失败返回 400，不进 Service。
5. 表驱动测试：方法 × 路径 × 期望状态码。
6. 文档：OpenAPI 路径应与 pattern 同源生成或同源维护。
7. 权限：认证全局或 /api 组；授权按资源在 Service/can(user, action, resource)。
8. 性能：路由通常不是第一瓶颈；先保证正确性与清晰分组。极端动态路由再评估专用库。

RESTful 注册示例（标准库）

func mountArticles(mux *http.ServeMux, h ArticleHandler) {
	mux.HandleFunc("GET /articles", h.List)
	mux.HandleFunc("POST /articles", h.Create)
	mux.HandleFunc("GET /articles/{slug}", h.Get)
	mux.HandleFunc("PUT /articles/{slug}", h.Update)
	mux.HandleFunc("DELETE /articles/{slug}", h.Delete)
	mux.HandleFunc("GET /articles/{slug}/comments", h.ListComments)
}

本节总结

• 路由负责方法+路径到 Handler 的映射与参数提取。
• Go 1.22+ ServeMux 覆盖多数 REST 需求。
• 查询参数、鉴权业务、尾斜杠是边界高发区。
• 分组 + 中间件子树是大型 API 的组织结构，不是语法糖玩具。
• 下一步：中间件链落地；Handler 变薄，接入 go-http-handler-service-repository。

自测题

概念题

1. 为什么 /users?id=1 的 id 不能靠 PathValue 取出？
2. {path} 与 {path...} 差别是什么？
3. 为何 /healthz 通常不要挂在强制 JWT 的子树上？

代码推理题

mux.HandleFunc("/users/{id}", anyMethod)
mux.HandleFunc("GET /users/{id}", getOnly)

在 Go 1.22+ 新 ServeMux 语义下，GET /users/1 与 DELETE /users/1 分别命中谁？

工程思考题

对外 URL 为 /api/v1/users/{id}，反代会去掉 /api 再转发。应用内 pattern 应怎么写？测试策略是什么？

参考答案

展开

1. 查询参数不在路由 path 匹配里，用 r.URL.Query()。
2. 单段 vs 剩余多段通配。
3. 编排探针通常不携带用户凭证；readiness 失败会影响接流量，liveness/startup 达失败阈值才触发容器重启处理。 代码：GET 命中 getOnly，DELETE 命中 anyMethod；这两个模式可以同时注册，前者的请求集合是后者的严格子集。 工程：与反代约定「剥离后 path」；集成测试打真实前缀或模拟剥离后的 path；文档写对外 URL。

延伸阅读与资料来源

资料	类型	支撑
Package net/http — ServeMux	标准库	pattern 与匹配
Go 1.22 Release Notes — Routing	发布说明	方法与通配符
Package net/http	标准库	Handler 模型
Go 1.22 server.go / Go 1.26.8 server.go	源码	尾斜杠重定向状态的版本差异
chi documentation	社区库	分组与中间件子树（第三方）

---

笔记元信息

• 建议文件名：go-routing-patterns.md
• 所属阶段：阶段七（Web 后端）
• 本篇状态：已深化
• 建议下一篇：HTTP 中间件 或 分层