Routing

Updated on May 20, 2025

The gFly router system provides a clean and flexible API for defining application routes. It supports standard HTTP methods, route grouping, middleware application, and path parameters. The design follows common patterns in modern web frameworks while maintaining a clean, Go-idiomatic API. Developers can quickly define both web and API routes, apply middleware globally or to specific routes, and organize routes into logical groups to maintain clean, maintainable code as applications grow in complexity.

The gFly framework implements a robust routing system that manages both API and Web routes. This document explores how the router works, specifically focusing on files like and , and details various routing methods and configurations api_routes.go (app/http/routes/api_routes.go) and web_routes.go (app/http/routes/web_routes.go)

Router Architecture Overview

The router in Gfly is built on a core interface which provides all routing functionality. This interface enables: core.IFly

Registration of route handlers for different HTTP methods
Route grouping
Middleware application
Path parameter handling

The gFly router only accept a URI and a implementation of IHandler interface

// IHandler Interface a handler request.
type IHandler interface {
    Validate(c *Ctx) error
    Handle(c *Ctx) error
}

Available Router Methods

f.GET("/users", user.NewGetUserAPI())
f.POST("/user", user.NewAddUserAPI())
f.PUT("/user", user.NewUpdateUserAPI())
f.DELETE("/users", user.NewDeleteUserAPI())
f.PATCH("/users", user.NewUpdatePartUserAPI())

Group and Middleware in Router

You can use router.Group() to create hierarchies for navigating and managing Routers. Or you can use router.Use() to use Middleware to increase efficiency in data filtering and delegate processing.

/* ============================ User Group ============================ */
apiRouter.Group("/users", func(userRouter *core.Group) {
    // Allow admin permission to access `/users/*` API
    userRouter.Use(middleware.CheckRolesMiddleware(
        []types.Role{types.RoleAdmin},
        prefixAPI+"/users/profile",
    ))

    userRouter.GET("", user.NewListUsersApi())
    userRouter.POST("", user.NewCreateUserApi())
    userRouter.PUT("/{id}/status", r.Apply(middleware.PreventUpdateYourSelf)(user.NewUpdateUserStatusApi()))
    userRouter.PUT("/{id}", r.Apply(middleware.PreventUpdateYourSelf)(user.NewUpdateUserApi()))
    userRouter.DELETE("/{id}", r.Apply(middleware.PreventUpdateYourSelf)(user.NewDeleteUserApi()))
    userRouter.GET("/{id}", user.NewGetUserByIdApi())
    userRouter.GET("/profile", user.NewGetUserProfileApi())
})

Route Parameters

Sometimes you will need to capture segments of the URI within your route. For example, you may need to capture a user’s ID from the URL. You may do so by defining route parameters

userRouter.GET("/{id}", user.NewGetUserByIdApi())

Get path parameter in controller

userIdStr := c.PathVal("id")

Pattern with suffix: `/user/{user}_admin`

/user/gordon_admin               match
/user/you_admin                  match
/user/you                        no match

Optional parameters

If you need define an optional parameters, add ? at the end of param name. {name?}

Regex validation

If you need define a validation, you could use a custom regex for the paramater value, add : after the name. For example: {name:[a-zA-Z]{5}}.

Optional parameters and regex validation are compatibles, only add ? between the name and the regex. For example: {name?:[a-zA-Z]{5}}.

Catch-All parameters

The second type are catch-all parameters and have the form {name:*}. Like the name suggests, they match everything. Therefore they must always be at the end of the pattern:

Pattern: /src/{filepath:*}

/src/                     match
/src/somefile.go          match
/src/subdir/somefile.go   match