一个只读接口在未登录时应该返回 401。上线后前端反馈:状态码确实是 401,但响应正文里同时带着订单列表。打开代码,鉴权中间件写的是「取不到 token 就写 401,然后 return」,看起来已经结束了,实际上只结束了中间件自己。Gin 继续执行后面的处理函数,订单查询照跑,c.JSON 又把数据追加到已经写出的响应里,于是出现了一个只有状态码是 401、内容却泄露了数据的响应。

另一个现象发生在跨域联调。浏览器的非简单请求会先发一次 OPTIONS 预检,后端没有注册这个方法,直接回 404,浏览器控制台显示跨域失败。业务接口其实一次都没被调用,前端却在查参数和鉴权。预检失败和接口失败看起来都是「请求红了」,定位方向完全不同。

这篇沿着一次请求的路径走:从进入 net/http 服务器,到路由匹配、分组中间件、参数绑定,再到处理函数写出响应。重点讲清 Use、Next、Abort 三个动作,因为它们决定了鉴权、日志、恢复这些横切逻辑是否可靠。Go 语法和框架安装不在这篇重复,默认服务已经能启动。

一次请求在 Gin 里经过哪几步

Gin 没有自己实现 TCP 服务器,它把 gin.Engine 当作一个 http.Handler 交给标准库。net/http 接受连接、解析 HTTP 报文,然后调用引擎的 ServeHTTP;引擎查找路由,把全局中间件、分组中间件和最终处理函数拼成一条链,依次执行。响应最后由 net/http 写回连接。

一次请求的执行路径
连接与报文解析
引擎匹配路由
全局中间件
分组中间件
处理函数
写回响应

这条链上的每一环都可能提前返回:路由没匹配到走 NoRoute,方法不对走 405 分支,中间件可以中断,处理函数可以 panic。理解生命周期,就是知道每种提前返回发生在哪一步、由谁负责写状态码。很多「状态码对了但内容不对」的问题,本质是两段代码都在写同一个响应。

还有一个容易忽略的事实:中间件不是「包在外面的一层函数」,而是和最终处理函数放在同一个切片里按顺序调用。所以中间件里写 return 只表示当前函数结束,不代表整条链结束;要真正截断,必须让链的索引跳过剩余处理函数,这就是 Abort 做的事。

路由树:静态、参数与通配符

Gin 的路由是一棵按路径段组织的树,匹配时优先看静态段,再看参数段,最后才看通配符。注册 /v1/orders/:id 时,:id 是一个参数段,能匹配 /v1/orders/1001,值通过 c.Param("id") 取;*filepath 是通配符,能吃掉剩余所有路径,通常只用于静态文件代理,不要拿它做业务路由。

静态段和参数段可以同时存在。本机用一个最小服务验证过:先注册 /v1/orders/:id,再注册 /v1/orders/summary,启动不会报错,请求 /v1/orders/summary 时命中的是静态路由,不会把 summary 当成 id。这个行为不依赖注册顺序,匹配规则本身优先静态。写接口时可以把固定动作放在同一前缀下,但要注意别让参数路由把预期之外的路径也吃掉。

参数段之间不能随意重叠。同一段位置注册两个不同名字的参数,比如 /v1/orders/:id 和 /v1/orders/:orderID,框架无法判断该用哪个,启动阶段就会 panic。好消息是这类错误在启动时暴露,不会等到线上才出现;坏消息是如果服务只在发布时启动,panic 会直接让新版本起不来,所以本地和 CI 都要跑一次「注册全部路由」的启动测试。

方法不匹配时的默认行为是 404,而不是 405。Gin 提供 r.HandleMethodNotAllowed = true,打开后方法不对会走 NoMethod,并带上 Allow 响应头。本机测试里,POST /health 返回 405 Method Not Allowed,头部是 Allow: GET;同一个服务里 OPTIONS /v1/orders 也返回 405,因为 OPTIONS 没有被注册。想让预检返回 204,必须由 CORS 中间件显式处理。

还有尾斜杠问题。/v1/orders 和 /v1/orders/ 在 Gin 的默认配置下会被重定向,客户端如果关闭了自动跟随重定向,就会看到一个 301 或 307,而不是预期的 JSON。对外 API 最好在文档里统一不带尾斜杠,网关层也做同样的规范化,别让客户端去猜。

分组与版本前缀

分组解决的是「同一批路由共享前缀和中间件」。v1 := r.Group("/v1") 之后,v1.GET("/orders", ...) 实际路径是 /v1/orders;v1.Use(auth) 注册的中间件只作用于这个组。分组可以嵌套,权限边界也能按组划开:公开接口、登录后接口、管理员接口各一个组,比在每个处理函数里重复判断角色清楚得多。

顺序很关键。在 Group 创建之前用 r.Use 注册的是全局中间件,所有组都继承;组内 Use 的顺序就是执行顺序,先注册的先执行。如果把日志中间件放在鉴权之后,未登录的请求在鉴权处就被截断,日志根本不会记录,排查「谁在疯狂试探接口」时就会缺数据。反过来,把鉴权放在日志之前,日志能覆盖所有请求,但请求 ID 还没生成,鉴权失败日志里就没有关联标识。

版本前缀不要只靠字符串拼接。r.Group("/v1") 是清晰的,但如果在处理函数里再拼 /v1/,或者让前端自己带版本号,路由表会很快失去秩序。一个服务对外只暴露一个版本前缀,内部升级用新组,老组保留到客户端迁移完成,这是比「在 URL 里塞版本又随时改」更稳定的做法。

参数、查询与请求体绑定

路径参数用 c.Param,查询字符串用 c.Query 或 c.DefaultQuery,请求体用绑定方法。三者的区别不只是取值方式:路径参数是路由的一部分,取不到说明路由设计有问题;查询参数可选,缺失时要给默认值并校验范围;请求体必须先确认 Content-Type,再解析。

Gin 有两组绑定方法,名字很像,行为差别很大:

ShouldBind 系列

解析失败时返回错误,不自动写响应。你可以在 handler 里把错误转成统一的业务错误码,也能按语言或字段定制提示。业务接口应该用它。

Bind 系列

解析失败时直接写 400 并中断,handler 拿不到错误。适合原型和内部工具,不适合需要统一错误格式的对外 API。

绑定依赖结构体标签。字段名大小写、json 标签、binding:"required"、数字范围这些都要显式写;不写标签,空字符串和零值都可能通过,业务层再补救就很被动。校验失败的错误信息默认偏底层,包含结构体名和字段名,直接返回给前端会泄露内部命名,最好在中间件或统一的错误处理函数里做一次映射。

请求体只能读一次。中间件如果先读了 body 做签名校验,后面 handler 再绑定就会拿到空内容;需要同时做这两件事时,先把 body 读进内存,再用 c.Request.Body 的替代实现放回去,或者把校验结果通过上下文传给 handler。这个坑在做支付回调和 Webhook 签名时最常见,表现是「单独调接口正常,加上验签中间件后参数全空」。

路径参数要转换类型。URL 里的 id 永远是字符串,直接拼进 SQL 会留下注入风险,直接转整数要处理失败。转换失败应该返回 400 而不是 500,因为这是客户端输入问题;错误信息里不要回显原始 SQL 或数据库错误,只说明「id 格式不正确」即可。

中间件链:Use、Next 与 Abort

module demo/routerdemo

go 1.27.3

require github.com/gin-gonic/gin v1.10.1
go mod tidy
$env:ABORT="0"
go run .

把中间件想成一条队伍:请求从队首走到队尾,处理函数在最后。中间件调用 c.Next(),相当于「我去处理下一个,处理完再回来」;不调用 c.Next() 直接返回,队伍不会因此停下,外层调度会继续走到下一个。只有 c.Abort() 会把当前位置跳到队伍之外,后面的处理函数不再执行。

这就是开头那个故障的根因。下面这段鉴权中间件看起来「失败就返回」,实际只返回了函数:

auth := func(c *gin.Context) {
	if c.GetHeader("Authorization") == "" {
		c.JSON(http.StatusUnauthorized, gin.H{"error": "missing bearer token"})
		return
	}
	c.Next()
}

本机用 Gin v1.10.1 实际跑了一次,未带 token 请求 /v1/orders,返回的状态行是 401,正文却是两段 JSON 拼在一起:

curl -i http://127.0.0.1:18087/v1/orders
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Length: 64

{"error":"missing bearer token"}{"data":["ord_1001","ord_1002"]}

加上 c.Abort() 之后,同样的请求只返回鉴权错误,长度从 64 变成 32:

auth := func(c *gin.Context) {
	if c.GetHeader("Authorization") == "" {
		c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "missing bearer token"})
		return
	}
	c.Next()
}
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Length: 32

{"error":"missing bearer token"}

AbortWithStatusJSON 等于「写状态码和 JSON」加「Abort」,少写一行也少一个忘记的机会。带 token 的请求则正常返回 200 和订单列表,说明中间件在通过时仍要调用 c.Next(),否则处理函数不会执行。

执行顺序可以用一个日志中间件观察。它在 c.Next() 之前记录开始时间,之后记录耗时:请求先经过它,再经过鉴权,再进入处理函数;处理函数返回后,代码沿着链反向回到日志中间件,最后写出耗时。这里用 defer 也能达到类似效果,但要明白 defer 在函数返回时执行,而 c.Next() 之后的代码在后续处理完成时执行,两者在 panic 场景下行为不同。

中间件的进入与返回
日志:记录开始
鉴权:校验 token
处理函数:查数据
鉴权:返回
日志:记录耗时

中间件顺序就是契约。恢复中间件应该在最外层,才能接住后面所有中间件和处理函数的 panic;请求 ID 应该尽早生成,后面的日志才能带上;CORS 要在鉴权之前处理预检,否则预检请求没有 token,会被鉴权直接拒绝。把顺序写进代码注释或测试,比靠记忆可靠。

四个值得默认带上的中间件

第一个是请求 ID。它让一次请求的所有日志能串起来,也方便让客户端在报错时提供编号。实现很简单:优先读客户端传来的 X-Request-ID,没有就生成一个随机值,写进上下文和响应头。生成值用 crypto/rand,不要用时间戳加自增,多实例下会重复。

func RequestID() gin.HandlerFunc {
	return func(c *gin.Context) {
		id := c.GetHeader("X-Request-ID")
		if id == "" {
			b := make([]byte, 8)
			rand.Read(b)
			id = hex.EncodeToString(b)
		}
		c.Set("request_id", id)
		c.Header("X-Request-ID", id)
		c.Next()
	}
}

第二个是访问日志。用标准库的 log/slog 输出结构化字段,至少包含方法、路径、状态码、耗时、请求 ID 和客户端地址。c.Writer.Status() 要在 c.Next() 之后读,才能拿到处理函数实际写入的状态码。日志里不要记录请求体和 Authorization 头,里面有密码和令牌。

第三个是 gin.Recovery()。它接住 panic,记录堆栈并返回 500,避免一个处理函数的空指针把整个连接拖死。默认实现把堆栈打到标准错误,格式和 slog 不一致;团队统一日志时,可以自己写恢复中间件,用 defer recover() 加 slog.Error 记录请求 ID 和路径,再返回统一的错误 JSON。

第四个是 CORS。它不是一个安全机制,而是浏览器强制执行的一套响应头规则。中间件要根据白名单回写 Access-Control-Allow-Origin,不要无条件回 *,尤其不能和携带 Cookie 的请求一起用。收到 OPTIONS 时直接返回 204 并 Abort,不要再往下走鉴权。本机验证时,如果不注册 CORS,OPTIONS /v1/orders 在开启 405 的情况下返回 405,未开启则返回 404,两种都不是浏览器想要的预检响应。

func CORS(allowOrigin string) gin.HandlerFunc {
	return func(c *gin.Context) {
		if origin := c.GetHeader("Origin"); origin == allowOrigin {
			c.Header("Access-Control-Allow-Origin", origin)
			c.Header("Vary", "Origin")
			c.Header("Access-Control-Allow-Headers", "Authorization,Content-Type,X-Request-ID")
			c.Header("Access-Control-Allow-Methods", "GET,POST,PUT,PATCH,DELETE,OPTIONS")
		}
		if c.Request.Method == http.MethodOptions {
			c.AbortWithStatus(http.StatusNoContent)
			return
		}
		c.Next()
	}
}

和 net/http 中间件对照

标准库没有 gin.Context,中间件就是「接收一个 http.Handler,返回一个新的 http.Handler」的函数。数据通过 context.Context 传递,路径参数用 r.PathValue 取。Go 1.22 之后,ServeMux 的模式支持方法和 {id} 占位符,简单服务不一定需要框架。

func WithRequestID(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		id := r.Header.Get("X-Request-ID")
		if id == "" {
			id = "generated-id"
		}
		ctx := context.WithValue(r.Context(), requestIDKey{}, id)
		w.Header().Set("X-Request-ID", id)
		next.ServeHTTP(w, r.WithContext(ctx))
	})
}

mux := http.NewServeMux()
mux.HandleFunc("GET /v1/orders/{id}", func(w http.ResponseWriter, r *http.Request) {
	id := r.PathValue("id")
	_ = id
})

对照下来,Gin 省掉的是「链式注册、上下文取值、参数绑定、分组」这些重复代码;标准库省掉的是「框架依赖和学习成本」。两者的中间件语义其实相同:调用下一个处理者之前可以做前置逻辑,调用之后可以做后置逻辑;提前写响应就不再调用下一个。理解了这一点,换框架不会重新学一遍概念。

现象、原因与第一步

现象真实原因第一步查什么
401 响应里仍带业务数据鉴权中间件只 return,没有 Abort看中间件失败分支是否调用 c.Abort 或 AbortWithStatusJSON
跨域请求全部失败OPTIONS 预检没有处理,被路由或鉴权拦截看浏览器网络面板里的预检状态码和 Allow 头
方法写错却返回 404没有开启 HandleMethodNotAllowed打开该配置并注册 NoMethod,对比是否变成 405
服务启动直接 panic路由参数段冲突或通配符位置非法看 panic 里的新旧路径,整理同一前缀下的参数命名
c.Param 取到空字符串路由声明是静态段,或参数名拼写不一致对照路由注册与取值名称,确认冒号后的单词
绑定总是报 400Content-Type 不对,或字段类型、标签不匹配用 curl -i 看请求头,打印结构体标签
验签中间件加上后参数全空请求体已被读取,handler 再读拿不到内容确认中间件是否消费了 c.Request.Body
panic 后连接直接断开没有恢复中间件,或恢复中间件不在最外层检查 r.Use 顺序,确认 Recovery 最先注册
日志缺少请求 ID日志中间件早于请求 ID 中间件执行调整 Use 顺序,让请求 ID 先执行

边界与代价

gin.Context 不能跨 goroutine 直接使用。它是请求级的对象,请求结束后会被复用;在异步任务里拿着它写日志,可能读到下一个请求的路径,甚至写坏已经被回收的状态。需要异步时用 c.Copy(),并且只复制值,不要把整个上下文传进长期存活的 goroutine。请求级的数据也可以放进 c.Request.Context(),但同样要遵守生命周期。

中间件顺序是隐式契约,改一次顺序可能影响所有接口。加入新中间件前,先写清它依赖什么、会中断哪些请求、在什么位置执行。团队里最好有一条固定的顺序:恢复、请求 ID、日志、CORS、鉴权、限流、业务。顺序本身没有唯一正确答案,但必须稳定,并且有测试覆盖关键组合。

CORS 不是访问控制。它只约束浏览器里的脚本,命令行、爬虫、服务端调用都可以完全忽略这些响应头。真正的权限必须在服务端每个入口校验,不能因为「前端已经限制了」就省掉。预检通过也不代表业务接口安全,预检只说明浏览器允许发这个请求。

全局中间件不是免费的。每个请求都要走一遍链,日志、限流、鉴权都会增加延迟;在高并发服务里,把重逻辑放在全局中间件上,会让所有接口一起变慢。按组挂载、按需挂载是更实际的做法:公开的健康检查不需要鉴权,也不需要用户级限流,就不要让它走整条链。

最后,框架帮你处理的是「调用顺序」,不是「业务正确性」。鉴权通过只代表令牌有效,不代表这个用户有权访问这条订单;资源归属、角色、租户隔离仍然要在服务层判断。把权限判断只写在中间件里,是下一篇要展开的一个典型漏洞。

当天能自己验证的练习

  1. 复制本文的鉴权中间件,先保留「写 401 后直接 return」的版本,用 curl -i 请求受保护接口,观察正文是不是两段 JSON 拼在一起。
  2. 把失败分支改成 c.AbortWithStatusJSON,重跑同一条命令,对比 Content-Length 和正文长度的变化。
  3. 开启 HandleMethodNotAllowed 并注册 NoMethod,用 POST 请求一个只支持 GET 的路径,确认状态码和 Allow 头。
  4. 注册 /v1/orders/:id 和 /v1/orders/summary,请求 summary,观察命中静态路由还是参数路由;再把参数名改成另一个名字,看启动是否 panic。
  5. 写两个中间件,分别在 c.Next() 前后打印一行日志,发起一次请求,按输出顺序画出一条进入和返回的路径。

小结

三句话:中间件失败分支必须 Abort,return 只结束当前函数;路由匹配优先静态段,参数段和通配符各有适用边界;中间件顺序就是契约,请求 ID 和恢复要放在最外层。

请求能正确路由、正确中断之后,下一步就是处理函数里真正要做的事:读写数据库。下一篇从「每个请求都 sql.Open 一次,连接数瞬间打满」开始,讲连接池、查询、事务和迁移;路由和中间件只决定请求怎么进来,数据访问决定请求能不能稳定地完成。