Starter guide

    This guide is not intended to teach you how to use Goopen in new window, and would assume you already have basic knowledge about HTTP, web applications development and programming in Go.

    Let’s start with the minimal example you may have seen on the front page:

    On line 6, the function creates and returns a classic Flame instance with a default list of middleware, including , flamego.Recovery and .

    On line 7, the method f.Getopen in new window registers the anonymous function (from line 7 to 9) to be the of the root path (“/“) when a HTTP GET request comes in. In this case, the handler simply reponds a “Hello, Flamego!” string to the client.

    On line 10, we start the web server by calling f.RunStarter guide - 图4open in new window. By default, the listens on the address 0.0.0.0:2830.

    Alright, now save the file and initialize a Go moduleopen in new window:

    1. $ mkdir flamego-example
    2. $ cd flamego-example
    3. $ nano main.go
    5. $ go mod init flamego-example
    6. go: creating new go.mod: module flamego-example
    7. $ go mod tidy
    8. go: finding module for package github.com/flamego/flamego
    9. ...
    11. $ go run main.go
    12. [Flamego] Listening on 0.0.0.0:2830 (development)

    Once you see the last line from your terminal, you’re good to go!

    You may verify the result by either visiting (why 2830?) in your browser, or through the folllowing curl command:

    If you have used other Go web frameworks like or EchoStarter guide - 图8open in new window, you may be surpised that you can directly return a string in Flamego handlers as the response body to the client.

    That is exactly right! Of course, this won’t be the only way to make a response body (which would be a very unfriendly design!). If you’re interested in reading more, the is the magician behind the scene.

    The minimal example aims for the least lines of code for a functioning example, but it inevitably hides some interesting details. Therefore, we’re going to unfold those hidden parts to understand more about how things are assembled.

    Let’s first modify our main.go file as follows:

    1. package main
    2. import (
    4.     "net/http"
    6.     "github.com/flamego/flamego"
    7. )
    9. func main() {
    10.     f := flamego.Classic()
    11.     f.Get("/{*}", printRequestPath)
    13.     log.Println("Server is running...")
    14.     log.Println(http.ListenAndServe("0.0.0.0:2830", f))
    15. }
    17.     return "The request path is: " + c.Request().RequestURI
    18. }

    As you may have guessed, this program responds back the request path that the client is requesting.

    Take a look!

    • Run
    • Test
    1. $ curl http://localhost:2830
    2. The request path is: /
    4. $ curl http://localhost:2830/hello-world
    7. $curl http://localhost:2830/never-mind
    8. The request path is: /never-mind
    10. $ curl http://localhost:2830/bad-ass/who-am-i
    11. 404 page not found

    So what are different now?

    On line 11, we’re still using the flamego.Classic to give us a classic Flame instance.

    TIP

    Try using the notation {**}, then redo all test requests and see what changes. If you’re interested in reading more, the routing has the best resources you would want.

    On line 15, the call of f.Run is replaced by the , which is the most common way to start a web server in Go, and maybe more familiar to you if you have used other Go web frameworks. This is possible with Flamego because Flame instances implement the http.HandlerStarter guide - 图10open in new window interface. Therefore, a Flame instance can be plugged into anywhere that accepts a http.Handler, and is particularly useful when you want to progressively migrate an existing Go web application to use Flamego.

    On line 18 to 20, we define the signature and the body of the printRequestPath. It accepts one argument with the type and returns a string. It then calls the Request method to retrieve the http.Requestopen in new window which contains the request path from the client.

    💡 小贴士

    You may start wondering that we did not tell the Flame instance what arguments it should pass to the printRequestPath when the function is being invoked, and if you look up the definition of , it is nothing but an empty interface (interface{})open in new window.

    So how does the Flame instance determine what to pass down to its handlers at runtime?

    This is the beauty (or confusion? 😅) of the , and flamego.Context is one of the default services that are injected into every request.

    Wrapping up

    Starting a new journey is never easy, especially when there are a lot of new concepts and content to learn. Please don’t be hesitate reaching out for help and have a nice day!