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。

404 与 405 路由失败判断流程

用兜底模式统一 JSON

Go 1.22 起,ServeMux 模式可以包含 HTTP 方法和路径通配符。标准库在只有方法模式、路径匹配但方法不匹配时会自动生成 405;如果 API 需要统一 JSON 错误体,可以为同一路径再注册一个不限定方法的兜底处理器,让具体方法模式优先匹配,兜底处理器专门负责自定义 405。最后用 / 接住真正未匹配的路径。

下面的程序不监听真实端口,而是把请求直接交给 Handler,并用一个最小 http.ResponseWriter 记录状态码、响应头和响应体,便于一次验证两类失败。

go
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()),
        )
    }
}

预期输出

text
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 语义,也能让日志、监控和客户端准确定位失败发生在哪一层。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

统一处理路由失败

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通