Starter guide

WARNING

This guide is not intended to teach you how to use GoStarter guide - 图1open 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:

  1. package main
  2. import "github.com/flamego/flamego"
  3. func main() {
  4. f := flamego.Classic()
  5. f.Get("/", func() string {
  6. return "Hello, Flamego!"
  7. })
  8. f.Run()
  9. }

On line 6, the function flamego.ClassicStarter guide - 图2open in new window creates and returns a classic Flame instance with a default list of middleware, including flamego.Logger, flamego.Recovery and flamego.Static.

On line 7, the method f.GetStarter guide - 图3open in new window registers the anonymous function (from line 7 to 9) to be the handler 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 Flame instance listens on the address 0.0.0.0:2830.

Alright, now save the file and initialize a Go moduleStarter guide - 图5open in new window:

  1. $ mkdir flamego-example
  2. $ cd flamego-example
  3. $ nano main.go
  4. $ go mod init flamego-example
  5. go: creating new go.mod: module flamego-example
  6. $ go mod tidy
  7. go: finding module for package github.com/flamego/flamego
  8. ...
  9. $ go run main.go
  10. [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 http://localhost:2830Starter guide - 图6open in new window (why 2830?) in your browser, or through the folllowing curl command:

  1. $ curl http://localhost:2830
  2. Hello, Flamego!

💡 小贴士

If you have used other Go web frameworks like GinStarter guide - 图7open in new window 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 return values is the magician behind the scene.

Unfolding hidden parts

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 (
  3. "log"
  4. "net/http"
  5. "github.com/flamego/flamego"
  6. )
  7. func main() {
  8. f := flamego.Classic()
  9. f.Get("/{*}", printRequestPath)
  10. log.Println("Server is running...")
  11. log.Println(http.ListenAndServe("0.0.0.0:2830", f))
  12. }
  13. func printRequestPath(c flamego.Context) string {
  14. return "The request path is: " + c.Request().RequestURI
  15. }

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

Take a look!

  • Run
  • Test
  1. $ go run main.go
  2. 2021/11/18 14:00:03 Server is running...
  1. $ curl http://localhost:2830
  2. The request path is: /
  3. $ curl http://localhost:2830/hello-world
  4. The request path is: /hello-world
  5. $curl http://localhost:2830/never-mind
  6. The request path is: /never-mind
  7. $ curl http://localhost:2830/bad-ass/who-am-i
  8. 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.

On line 12, insetad of using an anonymous function, function printRequestPath is registered as the handler for all of the HTTP GET requests under root path (“/“) using the notation {*}. The routing match stops at the slash (“/“) as you can tell from the last test request to “http://localhost:2830/bad-ass/who-am-i“ that gives us 404.

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 http.ListenAndServeStarter guide - 图9open in new window, 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 flaemgo.Context and returns a string. It then calls the Request method to retrieve the http.RequestStarter guide - 图11open 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 flamego.HandlerStarter guide - 图12open in new window, it is nothing but an empty interface (interface{})Starter guide - 图13open 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 service injection, and flamego.Context is one of the default services that are injected into every request.

Wrapping up

At this point, you should have some basic understanding of what is Flamego and how to start using it in your Go web applications.

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!