読者です 読者をやめる 読者になる 読者になる

ほげほげ

プログラミング、英会話、ヨガ、料理などの備忘録など。

Goフレームワーク Gin について

Ginを使うことにしました。 README.mdを通読したので、メモしておきます。

Ginを選んだ理由

困ったときにコード読みたかったので、リフレクションを使っているMartiniはコード追いにくいような気がしたからやめた。 お酒のマティーニが好きだったので、Martiniにしたかったけど。。 お酒つながりでGinにした。パフォーマンスもMartiniよりイイらしい。

Gin Web Framework(訳)

GinはGoで書かれたWebフレームワークです。Ginはマティーニと類似のAPIを提供し、httprouterのおかげでマティーニの40倍ほど高速です。もしあなたがパフォーマンスと生産性を必要としているのであれば、Ginを気に入るでしょう。

インストール&使い方

ダウンロードとインストール

$ go get github.com/gin-gonic/gin

プログラム(app.go)

package main
import (
    "github.com/gin-gonic/gin"
    "net/http"
)
func main() {
    r := gin.Default()
    r.GET("/", func(c *gin.Context) {
        c.String(http.StatusOK, "Hello World")
    })
    r.Run() // listen and server on 0.0.0.0:8080
}

ビルド&起動

$ go build app.go
$ ./app

http://localhost:8080/ にアクセスするとHello Worldと表示される。

APIサンプル集

ginのgithubにありますが、簡単に訳してメモしておきます。

GET,POST,PUT,PATCH,DELETE,OPTIONSの使い方

func main() {
    // デフォルトのミドルウェアとともにginルーターを作成
    // ミドルウェアはロガーとリカバリー(クラッシュフリー)
    router := gin.Default()

    router.GET("/someGet", getting)
    router.POST("/somePost", posting)
    router.PUT("/somePut", putting)
    router.DELETE("/someDelete", deleting)
    router.PATCH("/somePatch", patching)
    router.HEAD("/someHead", head)
    router.OPTIONS("/someOptions", options)

    // PORT環境変数が指定されていない場合は8080ポートで待受
    router.Run()
    // router.Run(":3000") // ポートをハードコーディングしたい場合
}

パス内のパラメタ

*:の違いに注目。

func main() {
    router := gin.Default()

    // このハンドラは /user/john にマッチするが、 /user/ や /user にはマッチしない
    router.GET("/user/:name", func(c *gin.Context) {
        name := c.Param("name")
        c.String(http.StatusOK, "Hello %s", name)
    })

    // でもこれは /user/john/ や /user/john/send にマッチする
    //  /user/john にマッチするルーターがなければ、/user/john/ にリダイレクトされる
    router.GET("/user/:name/*action", func(c *gin.Context) {
        name := c.Param("name")
        action := c.Param("action")
        message := name + " is " + action
        c.String(http.StatusOK, message)
    })

    router.Run(":8080")
}

クエリストリングパラメタ

GETの値の参照方法。

func main() {
    router := gin.Default()

    // クエリストリングパラメーターは既存のrequest objectの下でパースされる
    // このリクエストは /welcome?firstname=Jane&lastname=Doe へ返答する
    router.GET("/welcome", func(c *gin.Context) {
        firstname := c.DefaultQuery("firstname", "Guest") // Geustはデフォルト値?
        lastname := c.Query("lastname") // c.Request.URL.Query().Get("lastname") のショートカット

        c.String(http.StatusOK, "Hello %s %s", firstname, lastname)
    })
    router.Run(":8080")
}

Multipart/Urlencoded Form

POSTの値の参照方法。

func main() {
    router := gin.Default()

    router.POST("/form_post", func(c *gin.Context) {
        message := c.PostForm("message")
        nick := c.DefaultPostForm("nick", "anonymous") // anonymousはデフォルト値

        c.JSON(200, gin.H{
            "status":  "posted",
            "message": message,
            "nick":    nick,
        })
    })
    router.Run(":8080")
}

POST時にクエリストリングも参照する

func main() {
    router := gin.Default()

    router.POST("/post", func(c *gin.Context) {

        id := c.Query("id")
        page := c.DefaultQuery("page", "0")
        name := c.PostForm("name")
        message := c.PostForm("message")

        fmt.Printf("id: %s; page: %s; name: %s; message: %s", id, page, name, message)
    })
    router.Run(":8080")
}

ファイルのアップロード

func main() {
    router := gin.Default()

    router.POST("/upload", func(c *gin.Context) {

            file, header , err := c.Request.FormFile("upload")
            filename := header.Filename
            fmt.Println(header.Filename)
            out, err := os.Create("./tmp/"+filename+".png")
            if err != nil {
                log.Fatal(err)
            }
            defer out.Close()
            _, err = io.Copy(out, file)
            if err != nil {
                log.Fatal(err)
            }   
    })
    router.Run(":8080")
}

グルーピング ルーティング

APIのバージョンとかに使えそう?

func main() {
    router := gin.Default()

    // Simple group: v1
    v1 := router.Group("/v1")
    {
        v1.POST("/login", loginEndpoint)
        v1.POST("/submit", submitEndpoint)
        v1.POST("/read", readEndpoint)
    }

    // Simple group: v2
    v2 := router.Group("/v2")
    {
        v2.POST("/login", loginEndpoint)
        v2.POST("/submit", submitEndpoint)
        v2.POST("/read", readEndpoint)
    }

    router.Run(":8080")
}

ミドルウェアを使用する

func main() {
    // デフォルトのミドルウェアなしのGinルーターを作成
    r := gin.New()

    // グローバルミドルウェア
    r.Use(gin.Logger())
    r.Use(gin.Recovery())

    // ルーターごとのミドルウェア, 使いたいだけ追加できます。
    r.GET("/benchmark", MyBenchLogger(), benchEndpoint)

    // 認証グループ
    // authorized := r.Group("/", AuthRequired())
    // これは以下のようにもかけます
    authorized := r.Group("/")
    // この場合authorizedグループだけにAuthRequired() ミドルウェアを使う。
    authorized.Use(AuthRequired())
    {
        authorized.POST("/login", loginEndpoint)
        authorized.POST("/submit", submitEndpoint)
        authorized.POST("/read", readEndpoint)

        // ネストされたグループ
        testing := authorized.Group("testing")
        testing.GET("/analytics", analyticsEndpoint)
    }

    // Listen and server on 0.0.0.0:8080
    r.Run(":8080")
}

モデルバインディングとバリデーション

リクエストボディを型にバインドするには、モデルバインディングを使用してください。 GinはJSON,XMLと標準的なフォームの値(foo=bar&hoge=fuga)をサポートしています。

// JSONからバインド
type Login struct {
    User     string `form:"user" json:"user" binding:"required"`
    Password string `form:"password" json:"password" binding:"required"`
}

func main() {
    router := gin.Default()


    // JSONをバインディングする例({"user": "manu", "password": "123"})
    router.POST("/loginJSON", func(c *gin.Context) {
        var json Login // Login型変数
        if c.BindJSON(&json) == nil { // c.BindJSON関数を使ってバインドする BindJSONの戻り値はerrorオブジェクトかな
            if json.User == "manu" && json.Password == "123" {
                c.JSON(http.StatusOK, gin.H{"status": "you are logged in"})
            } else {
                c.JSON(http.StatusUnauthorized, gin.H{"status": "unauthorized"})
            }
        }
    })

    // HTML formをバインドする例(user=manu&password=123)
    router.POST("/loginForm", func(c *gin.Context) {
        var form Login // Login型変数
    // content-typeにより元データの形式(JSON,XML,form)を予想してバインドする
        if c.Bind(&form) == nil {
            if form.User == "manu" && form.Password == "123" {
                c.JSON(http.StatusOK, gin.H{"status": "you are logged in"})
            } else {
                c.JSON(http.StatusUnauthorized, gin.H{"status": "unauthorized"})
            }
        }
    })

    // Listen and server on 0.0.0.0:8080
    router.Run(":8080")
}

Multipart/Urlencoded(ポスト) のバインディング

同様にできる

XML,JSON,YAMLの結果を返す

func main() {
    r := gin.Default()

    // gin.H は map[string]interface{} へのショートカット
    r.GET("/someJSON", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{"message": "hey", "status": http.StatusOK})
    })

    r.GET("/moreJSON", func(c *gin.Context) {
        // 構造体も使える
        var msg struct {
            Name    string `json:"user"`
            Message string
            Number  int
        }
        msg.Name = "Lena"
        msg.Message = "hey"
        msg.Number = 123
    // この msg.Name は JSONないでは "user"となる
    // 出力{"user": "Lena", "Message": "hey", "Number": 123}
        c.JSON(http.StatusOK, msg)
    })

    r.GET("/someXML", func(c *gin.Context) {
        c.XML(http.StatusOK, gin.H{"message": "hey", "status": http.StatusOK})
    })

    r.GET("/someYAML", func(c *gin.Context) {
        c.YAML(http.StatusOK, gin.H{"message": "hey", "status": http.StatusOK})
    })

    // Listen and server on 0.0.0.0:8080
    r.Run(":8080")
}

静的ファイル

静的コンテンツは以下のようにディレクトリやファイルごとにマッピングしておける。

func main() {
    router := gin.Default()
    router.Static("/assets", "./assets")
    router.StaticFS("/more_static", http.Dir("my_file_system"))
    router.StaticFile("/favicon.ico", "./resources/favicon.ico")

    // Listen and server on 0.0.0.0:8080
    router.Run(":8080")
}

HTMLを返却する

LoadHTMLTemplates()関数を使う。

func main() {
    router := gin.Default()
    router.LoadHTMLGlob("templates/*") // 事前にテンプレートをロード
    //router.LoadHTMLFiles("templates/template1.html", "templates/template2.html") // ファイル指定でロード
    router.GET("/index", func(c *gin.Context) {
        // テンプレートを使って、値を置き換えてHTMLレスポンスを応答
        c.HTML(http.StatusOK, "index.tmpl", gin.H{
            "title": "Main website",
        })
    })
    router.Run(":8080")
}

templates/index.html

<html>
    <h1>
        {{ .title }}
    </h1>
</html>

同じ名前でディレクトリが異なるテンプレートの使い方

func main() {
    router := gin.Default()
    router.LoadHTMLGlob("templates/**/*")
    router.GET("/posts/index", func(c *gin.Context) {
        c.HTML(http.StatusOK, "posts/index.tmpl", gin.H{
            "title": "Posts",
        })
    })
    router.GET("/users/index", func(c *gin.Context) {
        c.HTML(http.StatusOK, "users/index.tmpl", gin.H{
            "title": "Users",
        })
    })
    router.Run(":8080")
}

リダイレクト

r.GET("/test", func(c *gin.Context) {
    c.Redirect(http.StatusMovedPermanently, "http://www.google.com/")
})

独自ミドルウェアの使い方

func Logger() gin.HandlerFunc {
    return func(c *gin.Context) {
        t := time.Now()

        // Set example variable
        c.Set("example", "12345")

        // リクエスト前

        c.Next()

        // リクエスト後
        latency := time.Since(t)
        log.Print(latency)

        // 送信したリクエストにアクセスできる
        status := c.Writer.Status()
        log.Println(status)
    }
}

func main() {
    r := gin.New()
    r.Use(Logger())

    r.GET("/test", func(c *gin.Context) {
        example := c.MustGet("example").(string)

        // it would print: "12345"
        log.Println(example)
    })

    // Listen and server on 0.0.0.0:8080
    r.Run(":8080")
}

ミドルウェア内でのゴルーチン

ミドルウェアやハンドラー内でゴルーチンを使う場合、オリジナルのcontextは使うべきでない。リードオンリーコピーを使うようにしなさい。

func main() {
    r := gin.Default()

    r.GET("/long_async", func(c *gin.Context) {
        // create copy to be used inside the goroutine
        cCp := c.Copy()
        go func() {
            // simulate a long task with time.Sleep(). 5 seconds
            time.Sleep(5 * time.Second)

            // note that you are using the copied context "cCp", IMPORTANT
            log.Println("Done! in path " + cCp.Request.URL.Path)
        }()
    })

    r.GET("/long_sync", func(c *gin.Context) {
        // simulate a long task with time.Sleep(). 5 seconds
        time.Sleep(5 * time.Second)

        // since we are NOT using a goroutine, we do not have to copy the context
        log.Println("Done! in path " + c.Request.URL.Path)
    })

    // Listen and server on 0.0.0.0:8080
    r.Run(":8080")
}

独自のHTTPの設定

http.ListenAndServe()を以下のように直接使う

func main() {
    router := gin.Default()
    http.ListenAndServe(":8080", router)
}

または

func main() {
    router := gin.Default()

    s := &http.Server{
        Addr:           ":8080",
        Handler:        router,
        ReadTimeout:    10 * time.Second,
        WriteTimeout:   10 * time.Second,
        MaxHeaderBytes: 1 << 20,
    }
    s.ListenAndServe()
}

グレースフルリスタート

グレースフルリスタートしたいですか?いくつかの方法があります。 fvbock/endlessでデフォルトのListenAndServeを置換できます。

router := gin.Default()
router.GET("/", handler)
// [...]
endless.ListenAndServe(":4242", router)

endlessの代わりにmannersというものもあります。

Ginを使ったプロジェクトの例

  • drone Goで書かれたDockerで動くデリバリシステム
  • goruch Goで書かれたプッシュ通知サーバー