13.2 Customizing routers

HTTP routing

The HTTP routing component is responsible for mapping HTTP requests to a corresponding function or struct method. The router takes two key pieces of information from incoming requests:

-The user requested path (for example, /user/123,/article/123), and any query strings or parameters that come with it (for example, ?id=11)-The HTTP request method (GET, POST, PUT, and DELETE, PATCH, etc.)

The router then forwards the request to the handler function (controller layer) that has been registered with that particular HTTP method and path.

Default routing implementation

In section 3.4, we introduced Go’s http package in detail, which included how to design and implement routing. Here, we take another look at an example that illustrates the routing process:

  1. func fooHandler(w http.ResponseWriter, r *http.Request) {
  2.     fmt.Fprintf(w, "Hello, %q", html.EscapeString(r.URL.Path))
  3. }
  5. http.Handle("/foo", fooHandler)
  7. http.HandleFunc("/bar", func(w http.ResponseWriter, r *http.Request) {
  8.     fmt.Fprintf(w, "Hello, %q", html.EscapeString(r.URL.Path))
  9. })
  11. log.Fatal(http.ListenAndServe(":8080", nil))

The example above calls http‘s default mux called DefaultServeMux, implicitly specified by the nil parameter in the call to http.ListenAndServe. The http.Handle function takes two parameters: the first parameter is the resource you want users to access, specified by its URL path (which is stored in r.URL.Path) and the second argument binds a handler function with this path. The Router has two main jobs:

  • To add and store routing information
  • To forward requests to a handler function for processing

By default, Go routes are handled with http.Handle and http.HandleFunc types, registered by default through the underlying DefaultServeMux.Handle(pattern string, handler Handler) function. This function maps resource paths to handlers and stores them in a map[string]muxEntry map. This is the first job that we mentioned above.

When the application is running, the Go server listens to a port. When it receives a tcp connection, it uses a Handler to process it. As aforementioned, since the Handler in the example above is nil, the default router http.DefaultServeMux is used. Using the map of previously stored routes, DefaultServeMux.ServeHTTP will dispatch the request to the first handler with a matching path. This is the router’s second job. 

  1. for k, v := range mux.m {
  2.     if !pathMatch(k, path) {
  3.         continue
  4.     }
  5.     if h == nil || len(k) > n {
  6.         n = len(k)
  7.         h = v.h
  8.     }
  9. }

Routing with Beego

At present, most Go web applications base their routing on http‘s default router, however this has several limitations:

  • Does not support dynamic routes with parameters, such as the/user/:UID
  • Does not have good support for REST. The access methods cannot be restricted; for instance in the above example, when users access /foo, they can use the GET, POST, DELETE, and HEAD HTTP methods, among others.
  • In large apps, routing rules can become repetitive and cumbersome. Personally, I’ve developed simple web APIs composed of nearly thirty routing rules when in fact, these rules could have been further simplified using method structs.

The Beego framework’s router is designed to overcome these limitations, taking the REST paradigm into consideration and simplifying the storing and forwarding of routes and requests.

Storing routes

To address the first limitation of the default router, we need to be able to support dynamic URL parameters. For the second and third points, we adopt an alternative approach,mapping REST methods to struct methods and routing requests to this struct instead of to handler functions. This way, a forwarded request can be handled according to it’s HTTP method.

Based on the above ideas, we’ve designed two data types: controllerInfo, which saves the path and the corresponding controllerType struct as a reflect.Type type, and ControllerRegistor, which saves routing information for the specified Beego application. 

  1. type controllerInfo struct {
  2.     regex          *regexp.Regexp
  3.     params         map[int]string
  4.     controllerType reflect.Type
  5. }
  7. type ControllerRegistor struct {
  8.     routers     []*controllerInfo
  9.     Application *App
  10. }

ControllerRegistor’s external interface contains the following method: 

  1. func(p *ControllerRegistor) Add(pattern string, c ControllerInterface)

Its detailed implementation is as follows:

  1. func (p *ControllerRegistor) Add(pattern string, c ControllerInterface) {
  2.     parts := strings.Split(pattern, "/")
  4.     j := 0
  5.     params := make(map[int]string)
  6.     for i, part := range parts {
  7.         if strings.HasPrefix(part, ":") {
  8.             expr := "([^/]+)"
  10.             //a user may choose to override the default expression
  11.             // similar to expressjs: ‘/user/:id([0-9]+)’
  13.             if index := strings.Index(part, "("); index != -1 {
  14.                 expr = part[index:]
  15.                 part = part[:index]
  16.             }
  17.             params[j] = part
  18.             parts[i] = expr
  19.             j++
  20.         }
  21.     }
  23.     //recreate the url pattern, with parameters replaced
  24.     //by regular expressions. Then compile the regex.
  26.     pattern = strings.Join(parts, "/")
  27.     regex, regexErr := regexp.Compile(pattern)
  28.     if regexErr != nil {
  30.         //TODO add error handling here to avoid panic
  31.         panic(regexErr)
  32.         return
  33.     }
  35.     //now create the Route
  36.     t := reflect.Indirect(reflect.ValueOf(c)).Type()
  37.     route := &controllerInfo{}
  38.     route.regex = regex
  39.     route.params = params
  40.     route.controllerType = t
  42.     p.routers = append(p.routers, route)
  44. }

Static routing

We’ve implemented dynamic routing in our example above. By default, Go’s http package supports serving static files with http.FileServer, which returns a Handler. Since we have implemented a custom router, we will also need a way of handling static files. Beego’s static folder path is saved in a global variable called StaticDir, which maps the URL to corresponding paths. The SetStaticPath‘s implementation can be seen below: 

  1. func (app *App) SetStaticPath(url string, path string) *App {
  2.     StaticDir[url] = path
  3.     return app
  4. }

The application’s static routes can be set like so:

  1. beego.SetStaticPath("/img", "/static/img")

Forwarding routes

We can forward routes based on the forwarding information contained within ControllerRegistor. The detailed implementation can be seen in the following code snippet:

  1. // AutoRoute
  2. func (p *ControllerRegistor) ServeHTTP(w http.ResponseWriter, r *http.Request) {
  3.     defer func() {
  4.         if err := recover(); err != nil {
  5.             if !RecoverPanic {
  6.                 // go back to panic
  7.                 panic(err)
  8.             } else {
  9.                 Critical("Handler crashed with error", err)
  10.                 for i := 1; ; i += 1 {
  11.                     _, file, line, ok := runtime.Caller(i)
  12.                     if !ok {
  13.                         break
  14.                     }
  15.                     Critical(file, line)
  16.                 }
  17.             }
  18.         }
  19.     }()
  20.     var started bool
  21.     for prefix, staticDir := range StaticDir {
  22.         if strings.HasPrefix(r.URL.Path, prefix) {
  23.             file := staticDir + r.URL.Path[len(prefix):]
  24.             http.ServeFile(w, r, file)
  25.             started = true
  26.             return
  27.         }
  28.     }
  29.     requestPath := r.URL.Path
  31.     //find a matching Route
  32.     for _, route := range p.routers {
  34.         //check if Route pattern matches url
  35.         if !route.regex.MatchString(requestPath) {
  36.             continue
  37.         }
  39.         //get submatches (params)
  40.         matches := route.regex.FindStringSubmatch(requestPath)
  42.         //double check that the Route matches the URL pattern.
  43.         if len(matches[0]) != len(requestPath) {
  44.             continue
  45.         }
  47.         params := make(map[string]string)
  48.         if len(route.params) > 0 {
  49.             //add url parameters to the query param map
  50.             values := r.URL.Query()
  51.             for i, match := range matches[1:] {
  52.                 values.Add(route.params[i], match)
  53.                 params[route.params[i]] = match
  54.             }
  56.             //reassemble query params and add to RawQuery
  57.             r.URL.RawQuery = url.Values(values).Encode() + "&" + r.URL.RawQuery
  58.             //r.URL.RawQuery = url.Values(values).Encode()
  59.         }
  60.         //Invoke the request handler
  61.         vc := reflect.New(route.controllerType)
  62.         init := vc.MethodByName("Init")
  63.         in := make([]reflect.Value, 2)
  64.         ct := &Context{ResponseWriter: w, Request: r, Params: params}
  65.         in[0] = reflect.ValueOf(ct)
  66.         in[1] = reflect.ValueOf(route.controllerType.Name())
  67.         init.Call(in)
  68.         in = make([]reflect.Value, 0)
  69.         method := vc.MethodByName("Prepare")
  70.         method.Call(in)
  71.         if r.Method == "GET" {
  72.             method = vc.MethodByName("Get")
  73.             method.Call(in)
  74.         } else if r.Method == "POST" {
  75.             method = vc.MethodByName("Post")
  76.             method.Call(in)
  77.         } else if r.Method == "HEAD" {
  78.             method = vc.MethodByName("Head")
  79.             method.Call(in)
  80.         } else if r.Method == "DELETE" {
  81.             method = vc.MethodByName("Delete")
  82.             method.Call(in)
  83.         } else if r.Method == "PUT" {
  84.             method = vc.MethodByName("Put")
  85.             method.Call(in)
  86.         } else if r.Method == "PATCH" {
  87.             method = vc.MethodByName("Patch")
  88.             method.Call(in)
  89.         } else if r.Method == "OPTIONS" {
  90.             method = vc.MethodByName("Options")
  91.             method.Call(in)
  92.         }
  93.         if AutoRender {
  94.             method = vc.MethodByName("Render")
  95.             method.Call(in)
  96.         }
  97.         method = vc.MethodByName("Finish")
  98.         method.Call(in)
  99.         started = true
  100.         break
  101.     }
  103.     //if no matches to url, throw a not found exception
  104.     if started == false {
  105.         http.NotFound(w, r)
  106.     }
  107. }

Getting started

Using our router design, we can solve the three limitations mentioned earlier. The three main use-cases are:

Registering route handlers: 

  1. beego.BeeApp.RegisterController("/", &controllers.MainController{})

Handling dynamic parameters:

  1. beego.BeeApp.RegisterController("/:param", &controllers.UserController{})

Regex matching:

  1. beego.BeeApp.RegisterController("/users/:uid([0-9]+)", &controllers.UserController{})