在 ServeMux 中拆分路由、中间件与错误响应

ServeMux 适合承载一层清晰的 HTTP 边界：路由模式只描述“什么请求交给谁”，中间件处理日志、认证和超时等横切职责，业务 Handler 负责业务判断，错误响应则沿着一个明确出口返回。这样拆分后，新增接口不会把方法判断、路径解析和错误写入揉成一团。

先让路由模式表达请求约束

Go 1.22 起，标准库 ServeMux 的模式支持方法和路径通配符。一个用户详情接口可以直接写成 GET /users/{id}，处理函数再通过 r.PathValue("id") 取出路径段。GET 还会匹配 HEAD；其他方法按各自方法匹配。这样，Handler 不必先写一段“是不是 GET、路径是不是 /users/”的重复判断。

mux := http.NewServeMux()

// 路由声明请求边界，Handler 只处理已经匹配的用户详情请求。
mux.HandleFunc("GET /users/{id}", func(w http.ResponseWriter, r *http.Request) {
	id := r.PathValue("id")
	if id == "" {
		// 这是防御性分支，避免未来改动后把空 ID 当成有效输入。
		http.Error(w, "缺少用户 ID", http.StatusBadRequest)
		return
	}
	fmt.Fprintf(w, "user=%s", id)
})

// 同一路径的 POST 由另一个 Handler 负责，不把创建和读取混在一起。
mux.HandleFunc("POST /users", createUser)

匹配规则的关键不是注册顺序，而是模式的具体程度。字面路径通常比通配符更具体，带方法的模式也比同路径的无方法模式更具体。两个模式既重叠又无法判断谁更具体时，注册阶段会暴露冲突；这比请求已经上线后才出现偶发分流更容易排查。

把中间件放在路由之外

中间件的价值在于把所有路由都需要的动作集中起来，例如记录请求耗时、设置关联 ID、限制处理时间或恢复 panic。它接收一个 Handler 并返回另一个 Handler，ServeMux 仍只负责匹配，业务处理器也保持原本的 func(http.ResponseWriter, *http.Request) 形状。

func withRequestLog(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		started := time.Now()
		// 先调用下游 Handler，确保记录的是完整处理耗时。
		next.ServeHTTP(w, r)
		log.Printf("method=%s path=%s elapsed=%s", r.Method, r.URL.Path, time.Since(started))
	})
}

func withTimeout(next http.Handler) http.Handler {
	// 超时包装只负责时限，不把业务错误翻译逻辑塞进路由注册处。
	return http.TimeoutHandler(next, 3*time.Second, "请求处理超时")
}

handler := withRequestLog(withTimeout(mux))
server := &http.Server{
	Addr:    ":8080",
	Handler: handler,
}

组合顺序要按意图决定。如果日志在最外层，它能记录超时响应；如果认证中间件放在业务 Handler 前，它可以在请求进入数据库或远程依赖前拒绝请求。不要在多个路由里手写同一套包装，否则很快会出现某个接口漏日志、漏超时的分叉。

让错误响应只有一个出口

Handler 最容易出现的错误是：写完 http.Error 后没有返回，后面的代码又继续写成功响应。HTTP 头一旦写出，状态码就可能已经确定；因此每个失败分支都应该“写响应、记录必要信息、立即返回”。如果业务层需要携带错误原因，可以先返回一个普通 Go error，再由边界层统一映射状态码。

func getUser(w http.ResponseWriter, r *http.Request) {
	id := r.PathValue("id")
	user, err := loadUser(r.Context(), id)
	if err != nil {
		if errors.Is(err, errUserNotFound) {
			// 对外只暴露稳定的状态和消息，不泄露存储细节。
			http.Error(w, "用户不存在", http.StatusNotFound)
			return
		}
		// 未知错误统一按服务端错误处理，写完后必须停止。
		http.Error(w, "服务暂时不可用", http.StatusInternalServerError)
		return
	}

	// 只有成功分支才设置 JSON 响应头并编码数据。
	w.Header().Set("Content-Type", "application/json; charset=utf-8")
	if err := json.NewEncoder(w).Encode(user); err != nil {
		log.Printf("encode user response: %v", err)
	}
}

几个边界要先说清

• 方法不匹配：如果路径能匹配但方法没有对应 Handler，ServeMux 可以返回 405，并带上允许的方法信息；不要在每个业务函数里重复模拟这套判断。
• 尾斜杠：以斜杠结尾的子树模式可能触发规范化重定向；需要精确匹配带斜杠的路径时，应明确注册相应模式。
• 版本兼容：Go 1.22 改变了模式、通配符和路径解码行为。旧项目升级前，应查看 httpmuxgo121 的兼容说明，并针对带大括号、编码斜杠和冲突模式补回归用例。
• 响应写入：http.Error 会设置文本类型并清理 Content-Length；调用它后不要再写 JSON，也不要把内部错误字符串直接返回给客户端。

速查：三层职责怎么分

相关问题

ServeMux 能不能替代所有 Web 框架？它已经覆盖方法匹配和路径通配符等常见需求，但复杂参数约束、路由分组、插件生态仍可能需要第三方框架。选择标准应是项目需要的能力，而不是为了少一个依赖强行迁移。

为什么错误写入后一定要 return？因为写响应不是抛出异常；函数仍会继续执行。没有返回就可能再次写状态、头部或正文，导致客户端收到混合内容，也让日志中的真实故障更难判断。

官方参考地址：https://pkg.go.dev/net/http；https://go.dev/blog/routing-enhancements