Go / 系统课时
统一处理路由失败
统一处理路由失败
路由失败至少要区分两类:路径没有任何匹配时返回 404,路径形状存在但请求方法不受支持时返回 405。本篇用 Go 1.22+ http.ServeMux 建立统一 JSON 错误契约,并验证 405 的 Allow 响应头。
学习目标
- 区分路由级 404 Not Found 与 405 Method Not Allowed
- 使用 Go 1.22+
http.ServeMux统一输出 JSON 路由错误 - 正确设置并验证 405 响应的
Allow头
先分清 404 和 405
404 与 405 表示的不是同一件事。404 表示当前请求没有可处理它的路由;405 表示路径已经被识别,但该路径不接受当前 HTTP 方法。
| 请求情况 | 状态码 | 客户端应理解为 |
|---|---|---|
GET /missing,没有对应路由 |
404 | 请求的路由不存在 |
POST /users/42,该路径只允许 GET |
405 | 路由存在,但方法不被允许 |
405 响应还应携带 Allow 头,告诉客户端该资源允许哪些方法。Go 的 GET 方法模式也会匹配 HEAD,因此这个示例返回 Allow: GET, HEAD。

用兜底模式统一 JSON
Go 1.22 起,ServeMux 模式可以包含 HTTP 方法和路径通配符。标准库在只有方法模式、路径匹配但方法不匹配时会自动生成 405;如果 API 需要统一 JSON 错误体,可以为同一路径再注册一个不限定方法的兜底处理器,让具体方法模式优先匹配,兜底处理器专门负责自定义 405。最后用 / 接住真正未匹配的路径。
下面的程序不监听真实端口,而是把请求直接交给 Handler,并用一个最小 http.ResponseWriter 记录状态码、响应头和响应体,便于一次验证两类失败。
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
"strings"
)
type apiError struct {
Code string `json:"code"`
Message string `json:"message"`
}
type recorder struct {
header http.Header
status int
body bytes.Buffer
}
func newRecorder() *recorder {
return &recorder{
header: make(http.Header),
status: http.StatusOK,
}
}
func (r *recorder) Header() http.Header {
return r.header
}
func (r *recorder) WriteHeader(status int) {
r.status = status
}
func (r *recorder) Write(p []byte) (int, error) {
return r.body.Write(p)
}
func writeError(w http.ResponseWriter, status int, code, message string) {
w.Header().Set("Content-Type", "application/json; charset=utf-8")
w.WriteHeader(status)
_ = json.NewEncoder(w).Encode(apiError{Code: code, Message: message})
}
func routes() http.Handler {
mux := http.NewServeMux()
// 具体方法模式负责支持的请求,GET 模式也覆盖 HEAD。
mux.HandleFunc("GET /users/{id}", func(w http.ResponseWriter, r *http.Request) {
fmt.Fprintf(w, "user=%s", r.PathValue("id"))
})
// 无方法模式只在具体方法未匹配时接管该路径。
mux.HandleFunc("/users/{id}", func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Allow", "GET, HEAD")
writeError(
w,
http.StatusMethodNotAllowed,
"method_not_allowed",
fmt.Sprintf("method %s is not allowed", r.Method),
)
})
mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
writeError(w, http.StatusNotFound, "not_found", "route not found")
})
return mux
}
func main() {
handler := routes()
tests := []struct {
method string
target string
}{
{http.MethodPost, "/users/42"},
{http.MethodGet, "/missing"},
}
for _, tc := range tests {
req, err := http.NewRequest(tc.method, tc.target, nil)
if err != nil {
panic(err)
}
rec := newRecorder()
handler.ServeHTTP(rec, req)
fmt.Printf(
"%s %s -> %d allow=%q %s\n",
tc.method,
tc.target,
rec.status,
rec.Header().Get("Allow"),
strings.TrimSpace(rec.body.String()),
)
}
}预期输出
POST /users/42 -> 405 allow="GET, HEAD" {"code":"method_not_allowed","message":"method POST is not allowed"}
GET /missing -> 404 allow="" {"code":"not_found","message":"route not found"}保持错误契约稳定
统一错误响应的重点不是把所有错误都变成同一个状态码,而是让 HTTP 状态、业务错误代码和 JSON 结构各司其职。客户端可以先根据状态码处理错误大类,再依据 code 执行更精确的逻辑。
写响应时必须先设置 Content-Type、Allow 等响应头,再调用 WriteHeader。如果直接使用 http.Error,标准库会写入文本错误体,不适合已经约定 JSON 错误结构的 API。
同一路径支持多个方法时,应分别注册具体方法模式,并让方法兜底返回完整的 Allow 列表。不要把所有未知请求都直接处理成 404,否则客户端无法判断是 URL 写错,还是只用了错误的 HTTP 方法。
不要混淆路由失败与资源不存在
路由已经匹配后,业务处理器仍可能因为数据不存在而返回 404。例如 GET /users/42 已经命中用户查询处理器,但用户 42 不存在,这属于资源级 404,而不是路由级 404。
两者可以使用相同 HTTP 状态码,但建议采用不同错误代码,例如路由失败使用 not_found,具体资源不存在使用 user_not_found。这样既遵循 HTTP 语义,也能让日志、监控和客户端准确定位失败发生在哪一层。