[!info] 关联笔记

• 所属 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)             // 所有方法（视注册方式）

语法	含义
GET /users/{id}	仅 GET，单段参数
{name...}	匹配剩余多段（通配）
更具体 pattern	优先于更泛化 pattern

提取：

id := r.PathValue("id")

优先级与「更具体」

标准库按模式具体性选择胜者，而不是「先注册先赢」的简单模型（具体规则以当前 Go 版本文档为准）。工程直觉：

• 带方法的 pattern 比不带方法的更具体
• 静态段通常比变量段更具体
• / 常作最泛兜底

冲突注册在启动时可能直接 panic，有利于早发现，而非运行期随机命中。

尾部斜杠

/users 与 /users/ 是不同 path。ServeMux 可能对「有无尾斜杠」的注册做重定向（行为与版本/注册方式相关）。API 设计应统一约定（通常 REST 资源不用强依赖重定向），并在测试中锁定。

路径参数 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")

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

gorilla/mux（历史广泛，已归档）

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

正则约束曾是卖点。新项目更建议标准库 1.22+ 或 chi；维护期项目迁移时注意正则与中间件差异。

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

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

方法不允许与 404

良好路由层应区分：

• 404：路径无任何匹配
• 405：路径存在但方法不支持（并宜带 Allow 头）

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

与中间件组合

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

root := http.NewServeMux()
root.Handle("/api/", auth(api)) // 示意：注意尾缀与剥离 path 的细节
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} 不含 /；文件路径要用 {path...}。
2. PathValue 总是 string，空字符串可能是「无此参数」或「参数为空段」，需结合是否命中 pattern。
3. Host 模式（若使用）让同一 path 按域名分发，本地测试易漏。
4. 注册冲突 panic 发生在初始化，CI 必须真正执行到注册代码。
5. 代理与前缀：反代剥离 /api 前缀时，应用内 pattern 要与对外 URL 一致。
6. 大小写与清理：path 清理规则以 net/http 为准，不要假设与前端路由器完全一致。
7. HEAD/GET：部分 mux 对 HEAD 有特殊处理；不要假设所有库自动镜像 GET。

常见误区

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

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

[!warning] 常见误区：查询参数当路径设计核心 错误：/getUser?id=1 却期望 REST 缓存与资源层级清晰。
正确：资源用路径；过滤分页用 query。

[!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)

对 GET /users/1 与 DELETE /users/1，更可能命中谁？（按「更具体优先」直觉作答，并强调以当前 Go 文档为准。）

工程思考题

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

参考答案

展开

1. 查询参数不在路由 path 匹配里，用 r.URL.Query()。
2. 单段 vs 剩余多段通配。
3. 编排/探针需在未带用户凭证时访问；鉴权失败会导致误杀实例。
   代码：GET 更可能命中带方法的更具体 pattern；DELETE 命中不带方法的 pattern（若注册合法且未冲突）。以实际 Go 版本规则与实验为准。
   工程：与反代约定「剥离后 path」；集成测试打真实前缀或模拟剥离后的 path；文档写对外 URL。

延伸阅读与资料来源

资料	类型	支撑
Package net/http — ServeMux	标准库	pattern 与匹配
Go 1.22 Release Notes — Routing	发布说明	方法与通配符
Package net/http	标准库	Handler 模型
chi documentation	社区库	分组与中间件子树（第三方）

---

笔记元信息

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