Update RouteChain function (#3761)

* docs: clarify route helper diff

* Adjust Route docs to drop v2 mention and update Express links

* Harden route helpers and keep group context

* Clarify RouteChain diff in what's new guide

* docs: show RouteChain signature in migration notes

* Add coverage for Route helpers

* Clarify route chaining release wording

Author: ReneWerner87

app.go

@@ -905,15 +905,35 @@ func (app *App) Group(prefix string, handlers ...Handler) Router {
 	return grp
 }
 
-// Route is used to define routes with a common prefix inside the common function.
-// Uses Group method to define new sub-router.
-func (app *App) Route(path string) Register {
+// RouteChain creates a Registering instance that lets you declare a stack of
+// handlers for the same route. Handlers defined via the returned Register are
+// scoped to the provided path.
+func (app *App) RouteChain(path string) Register {
 	// Create new route
 	route := &Registering{app: app, path: path}
 
 	return route
 }
 
+// Route is used to define routes with a common prefix inside the supplied
+// function. It mirrors the legacy helper and reuses the Group method to create
+// a sub-router.
+func (app *App) Route(prefix string, fn func(router Router), name ...string) Router {
+	if fn == nil {
+		panic("route handler 'fn' cannot be nil")
+	}
+	// Create new group
+	group := app.Group(prefix)
+	if len(name) > 0 {
+		group.Name(name[0])
+	}
+
+	// Define routes
+	fn(group)
+
+	return group
+}
+
 // Error makes it compatible with the `error` interface.
 func (e *Error) Error() string {
 	return e.Message

app_test.go

@@ -1360,13 +1360,13 @@ func Test_App_Group(t *testing.T) {
 	require.Equal(t, 200, resp.StatusCode, "Status code")
 }
 
-func Test_App_Route(t *testing.T) {
+func Test_App_RouteChain(t *testing.T) {
 	t.Parallel()
 	dummyHandler := testEmptyHandler
 
 	app := New()
 
-	register := app.Route("/test").
+	register := app.RouteChain("/test").
 		Get(dummyHandler).
 		Head(dummyHandler).
 		Post(dummyHandler).
@@ -1387,7 +1387,7 @@ func Test_App_Route(t *testing.T) {
 	testStatus200(t, app, "/test", MethodTrace)
 	testStatus200(t, app, "/test", MethodPatch)
 
-	register.Route("/v1").Get(dummyHandler).Post(dummyHandler)
+	register.RouteChain("/v1").Get(dummyHandler).Post(dummyHandler)
 
 	resp, err := app.Test(httptest.NewRequest(MethodPost, "/test/v1", nil))
 	require.NoError(t, err, "app.Test(req)")
@@ -1397,7 +1397,7 @@ func Test_App_Route(t *testing.T) {
 	require.NoError(t, err, "app.Test(req)")
 	require.Equal(t, 200, resp.StatusCode, "Status code")
 
-	register.Route("/v1").Route("/v2").Route("/v3").Get(dummyHandler).Trace(dummyHandler)
+	register.RouteChain("/v1").RouteChain("/v2").RouteChain("/v3").Get(dummyHandler).Trace(dummyHandler)
 
 	resp, err = app.Test(httptest.NewRequest(MethodTrace, "/test/v1/v2/v3", nil))
 	require.NoError(t, err, "app.Test(req)")
@@ -1408,6 +1408,71 @@ func Test_App_Route(t *testing.T) {
 	require.Equal(t, 200, resp.StatusCode, "Status code")
 }
 
+func Test_App_Route(t *testing.T) {
+	t.Parallel()
+
+	app := New()
+
+	app.Route("/test", func(api Router) {
+		api.Get("/foo", testEmptyHandler).Name("foo")
+
+		api.Route("/bar", func(bar Router) {
+			bar.Get("/", testEmptyHandler).Name("index")
+		}, "bar.")
+	}, "test.")
+
+	testStatus200(t, app, "/test/foo", MethodGet)
+
+	resp, err := app.Test(httptest.NewRequest(MethodGet, "/test/bar/", nil))
+	require.NoError(t, err, "app.Test(req)")
+	require.Equal(t, http.StatusOK, resp.StatusCode, "Status code")
+
+	require.Equal(t, "/test/foo", app.GetRoute("test.foo").Path)
+	require.Equal(t, "/test/bar/", app.GetRoute("test.bar.index").Path)
+}
+
+func Test_App_Route_nilFuncPanics(t *testing.T) {
+	t.Parallel()
+
+	app := New()
+
+	require.PanicsWithValue(t, "route handler 'fn' cannot be nil", func() {
+		app.Route("/panic", nil)
+	})
+}
+
+func Test_Group_Route_nilFuncPanics(t *testing.T) {
+	t.Parallel()
+
+	app := New()
+	grp := app.Group("/api")
+
+	require.PanicsWithValue(t, "route handler 'fn' cannot be nil", func() {
+		grp.Route("/panic", nil)
+	})
+}
+
+func Test_Group_RouteChain_All(t *testing.T) {
+	t.Parallel()
+
+	app := New()
+	var calls []string
+	grp := app.Group("/api", func(c Ctx) error {
+		calls = append(calls, "group")
+		return c.Next()
+	})
+
+	grp.RouteChain("/users").All(func(c Ctx) error {
+		calls = append(calls, "routechain")
+		return c.SendStatus(http.StatusOK)
+	})
+
+	resp, err := app.Test(httptest.NewRequest(MethodGet, "/api/users", nil))
+	require.NoError(t, err, "app.Test(req)")
+	require.Equal(t, http.StatusOK, resp.StatusCode, "Status code")
+	require.Equal(t, []string{"group", "routechain"}, calls)
+}
+
 func Test_App_Deep_Group(t *testing.T) {
 	t.Parallel()
 	runThroughCount := 0

docs/api/app.md

@@ -138,14 +138,14 @@ func handler(c fiber.Ctx) error {
 }
 ```
 
-### Route
+### RouteChain
 
 Returns an instance of a single route, which you can then use to handle HTTP verbs with optional middleware.
 
-Similar to [`Express`](https://expressjs.com/de/api.html#app.route).
+Similar to [`Express`](https://expressjs.com/en/api.html#app.route).
 
 ```go title="Signature"
-func (app *App) Route(path string) Register
+func (app *App) RouteChain(path string) Register
 ```
 
 <details>
@@ -166,7 +166,7 @@ type Register interface {
 
     Add(methods []string, handler Handler, handlers ...Handler) Register
 
-    Route(path string) Register
+    RouteChain(path string) Register
 }
 ```
 
@@ -184,12 +184,12 @@ import (
 func main() {
     app := fiber.New()
 
-    // Use `Route` as a chainable route declaration method
-    app.Route("/test").Get(func(c fiber.Ctx) error {
+    // Use `RouteChain` as a chainable route declaration method
+    app.RouteChain("/test").Get(func(c fiber.Ctx) error {
         return c.SendString("GET /test")
     })
 
-    app.Route("/events").All(func(c fiber.Ctx) error {
+    app.RouteChain("/events").All(func(c fiber.Ctx) error {
         // Runs for all HTTP verbs first
         // Think of it as route-specific middleware!
     }).
@@ -202,12 +202,12 @@ func main() {
     })
 
     // Combine multiple routes
-    app.Route("/v2").Route("/user").Get(func(c fiber.Ctx) error {
-        return c.SendString("GET /v2/user")
+    app.RouteChain("/reports").RouteChain("/daily").Get(func(c fiber.Ctx) error {
+        return c.SendString("GET /reports/daily")
     })
 
     // Use multiple methods
-    app.Route("/api").Get(func(c fiber.Ctx) error {
+    app.RouteChain("/api").Get(func(c fiber.Ctx) error {
         return c.SendString("GET /api")
     }).Post(func(c fiber.Ctx) error {
         return c.SendString("POST /api")
@@ -217,6 +217,21 @@ func main() {
 }
 ```
 
+### Route
+
+Defines routes with a common prefix inside the supplied function. Internally it uses [`Group`](#group) to create a sub-router and accepts an optional name prefix.
+
+```go title="Signature"
+func (app *App) Route(prefix string, fn func(router Router), name ...string) Router
+```
+
+```go title="Example"
+app.Route("/test", func(api fiber.Router) {
+    api.Get("/foo", handler).Name("foo") // /test/foo (name: test.foo)
+    api.Get("/bar", handler).Name("bar") // /test/bar (name: test.bar)
+}, "test.")
+```
+
 ### HandlersCount
 
 Returns the number of registered handlers.

docs/whats_new.md

@@ -328,18 +328,17 @@ In `v2` one handler was already mandatory when the route has been registered, bu
 
 ### Route chaining
 
-The route method is now like [`Express`](https://expressjs.com/de/api.html#app.route) which gives you the option of a different notation and allows you to concatenate the route declaration.
+This release introduces a dedicated `RouteChain` helper, inspired by [`Express`](https://expressjs.com/en/api.html#app.route), for declaring a stack of handlers on the same path. The original `Route` helper for prefix encapsulation also remains available.
 
-```diff
--    Route(prefix string, fn func(router Router), name ...string) Router
-+    Route(path string) Register
+```go
+RouteChain(path string) Register
 ```
 
 <details>
 <summary>Example</summary>
 
 ```go
-app.Route("/api").Route("/user/:id?")
+app.RouteChain("/api").RouteChain("/user/:id?")
     .Get(func(c fiber.Ctx) error {
         // Get user
         return c.JSON(fiber.Map{"message": "Get user", "id": c.Params("id")})
@@ -360,11 +359,11 @@ app.Route("/api").Route("/user/:id?")
 
 </details>
 
-You can find more information about `app.Route` in the [API documentation](./api/app#route).
+You can find more information about `app.RouteChain` and `app.Route` in the API documentation ([RouteChain](./api/app#routechain), [Route](./api/app#route)).
 
 ### Middleware registration
 
-We have aligned our method for middlewares closer to [`Express`](https://expressjs.com/de/api.html#app.use) and now also support the [`Use`](./api/app#use) of multiple prefixes.
+We have aligned our method for middlewares closer to [`Express`](https://expressjs.com/en/api.html#app.use) and now also support the [`Use`](./api/app#use) of multiple prefixes.
 
 Prefix matching is now stricter: partial matches must end at a slash boundary (or be an exact match). This keeps `/api` middleware from running on `/apiv1` while still allowing `/api/:version` style patterns that leverage route parameters, optional segments, or wildcards.
 
@@ -1653,7 +1652,7 @@ app.Add([]string{fiber.MethodPost}, "/api", myHandler)
 
 #### Mounting
 
-In Fiber v3, the `Mount` method has been removed. Instead, you can use the `Use` method to achieve similar functionality.
+In this release, the `Mount` method has been removed. Instead, you can use the `Use` method to achieve similar functionality.
 
 ```go
 // Before
@@ -1667,7 +1666,7 @@ app.Use("/api", apiApp)
 
 #### Route Chaining
 
-Refer to the [route chaining](#route-chaining) section for details on migrating `Route`.
+Refer to the [route chaining](#route-chaining) section for details on the new `RouteChain` helper. The `Route` function now matches its v2 behavior for prefix encapsulation.
 
 ```go
 // Before
@@ -1687,7 +1686,7 @@ app.Route("/api", func(apiGrp Router) {
 
 ```go
 // After
-app.Route("/api").Route("/user/:id?")
+app.RouteChain("/api").RouteChain("/user/:id?")
     .Get(func(c fiber.Ctx) error {
         // Get user
         return c.JSON(fiber.Map{"message": "Get user", "id": c.Params("id")})

group.go

@@ -196,11 +196,30 @@ func (grp *Group) Group(prefix string, handlers ...Handler) Router {
 	return newGrp
 }
 
-// Route is used to define routes with a common prefix inside the common function.
-// Uses Group method to define new sub-router.
-func (grp *Group) Route(path string) Register {
+// RouteChain creates a Registering instance scoped to the group's prefix,
+// allowing chained route declarations for the same path.
+func (grp *Group) RouteChain(path string) Register {
 	// Create new group
-	register := &Registering{app: grp.app, path: getGroupPath(grp.Prefix, path)}
+	register := &Registering{app: grp.app, group: grp, path: getGroupPath(grp.Prefix, path)}
 
 	return register
 }
+
+// Route is used to define routes with a common prefix inside the supplied
+// function. It mirrors the legacy helper and reuses the Group method to create
+// a sub-router.
+func (grp *Group) Route(prefix string, fn func(router Router), name ...string) Router {
+	if fn == nil {
+		panic("route handler 'fn' cannot be nil")
+	}
+	// Create new group
+	group := grp.Group(prefix)
+	if len(name) > 0 {
+		group.Name(name[0])
+	}
+
+	// Define routes
+	fn(group)
+
+	return group
+}

middleware/cache/cache_test.go

@@ -875,7 +875,7 @@ func Test_Cache_WithHead(t *testing.T) {
 		return c.SendString(strconv.Itoa(count))
 	}
 
-	app.Route("/").Get(handler).Head(handler)
+	app.RouteChain("/").Get(handler).Head(handler)
 
 	req := httptest.NewRequest(fiber.MethodHead, "/", nil)
 	resp, err := app.Test(req)
@@ -904,7 +904,7 @@ func Test_Cache_WithHeadThenGet(t *testing.T) {
 	handler := func(c fiber.Ctx) error {
 		return c.SendString(fiber.Query[string](c, "cache"))
 	}
-	app.Route("/").Get(handler).Head(handler)
+	app.RouteChain("/").Get(handler).Head(handler)
 
 	headResp, err := app.Test(httptest.NewRequest(fiber.MethodHead, "/?cache=123", nil))
 	require.NoError(t, err)