docs(engine): clarify Use() registration order

This commit is contained in:
Gavin Zhang 2026-04-04 17:02:46 +08:00
parent d3ffc99852
commit 700d4416aa
3 changed files with 38 additions and 2 deletions

View File

@ -459,6 +459,10 @@ func main() {
}
```
Attach global middleware before registering routes. Routes added before a `Use()` call are not
retroactively wrapped, while `404` and `405` handlers are rebuilt from the current global
middleware chain.
### Custom Middleware
```go

5
gin.go
View File

@ -334,8 +334,9 @@ func (engine *Engine) NoMethod(handlers ...HandlerFunc) {
engine.rebuild405Handlers()
}
// Use attaches a global middleware to the router. i.e. the middleware attached through Use() will be
// included in the handlers chain for every single request. Even 404, 405, static files...
// Use attaches a global middleware to the router. Middleware attached through Use() is included
// in the handlers chain for routes registered after the call. For 404 and 405 requests, Gin
// rebuilds the handler chain from the current middleware set.
// For example, this is the right place for a logger or error management middleware.
func (engine *Engine) Use(middleware ...HandlerFunc) IRoutes {
engine.RouterGroup.Use(middleware...)

View File

@ -570,6 +570,37 @@ func TestRebuild404Handlers(t *testing.T) {
compareFunc(t, router.allNoRoute[1], middleware0)
}
func TestUseOnlyAppliesToRoutesRegisteredAfterIt(t *testing.T) {
signature := ""
router := New()
router.GET("/before", func(c *Context) {
signature += "A"
c.Status(http.StatusNoContent)
})
router.Use(func(c *Context) {
signature += "M"
c.Next()
signature += "N"
})
router.GET("/after", func(c *Context) {
signature += "B"
c.Status(http.StatusNoContent)
})
w := PerformRequest(router, http.MethodGet, "/before")
assert.Equal(t, http.StatusNoContent, w.Code)
assert.Equal(t, "A", signature)
signature = ""
w = PerformRequest(router, http.MethodGet, "/after")
assert.Equal(t, http.StatusNoContent, w.Code)
assert.Equal(t, "MBN", signature)
}
func TestNoMethodWithGlobalHandlers(t *testing.T) {
var middleware0 HandlerFunc = func(c *Context) {}
var middleware1 HandlerFunc = func(c *Context) {}