ルーティングとリクエスト処理

ここからは、各節ごとに main.go を書き換えながら、Ginの主要なリクエスト処理を扱います。

1. パスパラメータ

パスパラメータは、URLのパスの一部をパラメータとして受け取る仕組みです。例えば /users/123 というURLの 123 の部分(ユーザID)をハンドラで受け取りたい場合、URLに埋め込まれた 123 をパラメータとして扱えるようにします。

Ginでは、パスの中に :パラメータ名 を含めることでパスパラメータを宣言し、c.Param("パラメータ名") で値を取り出します。書き方は以下のとおりです。

r.GET("/パス/:パラメータ名", func(c *gin.Context) {
    値 := c.Param("パラメータ名")   // パスパラメータの値を取得
})

main.go を以下の内容で置き換えて保存します。これは、/hello/:name にアクセスすると、パス内の :name を取り出して挨拶メッセージを返すコードです。

package main

import (
    "net/http"

    "github.com/gin-gonic/gin"
)

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

    r.GET("/hello/:name", func(c *gin.Context) {
        name := c.Param("name")
        c.JSON(http.StatusOK, gin.H{"message": "こんにちは、" + name + "さん!"})
    })

    r.Run(":8080")
}
💡 ポイント
Ginで立ち上げたWebサーバは --reload のような自動再起動機能を標準では持たないため、コードを変更したら Ctrl+C でサーバを停止してから go run main.go で再起動する必要があります。以降の節でも同じ手順で再起動します。

既存のサーバは Ctrl+C で停止し、以下のコマンドで再起動します。

go run main.go

別のターミナルで以下のコマンドを実行します。

curl http://localhost:8080/hello/Taro

以下のような実行結果が表示されます。

{"message":"こんにちは、Taroさん!"}

URLの Taro の部分がパスパラメータとして関数に渡され、{"message": "こんにちは、Taroさん!"} としてレスポンスに反映されています。

コードを解説します。

r.GET("/hello/:name", func(c *gin.Context) {
    name := c.Param("name")
    ...
})

パスパターン /hello/:name の :name がパスパラメータの宣言です。c.Param("name") で対応する値を文字列として取り出します。net/http の Go 1.22 では /hello/{name} と書き r.PathValue("name") で取り出していましたが、Gin では : プレフィックスと c.Param を使います。

2. クエリパラメータ

クエリパラメータは、URLの ? 以降に キー=値 の形式で指定するパラメータです。例えば /search?q=cat&limit=5 というURLでは q=cat と limit=5 の2つがクエリパラメータで、検索条件やオプションのように可変のデータを渡すのによく使われます。

Ginでは、指定したキーの値を取得するには c.Query を使います。書き方は以下のとおりです(キーが存在しない場合は空文字列が返ります)。

値 := c.Query("キー名")

キーが未指定のときにデフォルト値を返したい場合は c.DefaultQuery を使います。

値 := c.DefaultQuery("キー名", "デフォルト値")

main.go を以下の内容で置き換えて保存します。これは、/search にアクセスすると、クエリパラメータ q(未指定時は空文字列)と limit(未指定時はデフォルト値 10)を取り出してJSONで返すコードです。

package main

import (
    "net/http"

    "github.com/gin-gonic/gin"
)

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

    r.GET("/search", func(c *gin.Context) {
        q := c.Query("q")
        limit := c.DefaultQuery("limit", "10")
        c.JSON(http.StatusOK, gin.H{"query": q, "limit": limit})
    })

    r.Run(":8080")
}

既存のサーバが動いている場合は Ctrl+C で停止し、以下のコマンドで再起動します。

go run main.go

別のターミナルで、両方のパラメータを指定して確認します。

curl "http://localhost:8080/search?q=cat&limit=5"

以下のような実行結果が表示されます。

{"limit":"5","query":"cat"}

limit を省略した場合は DefaultQuery に指定した 10 が使用されます。

curl "http://localhost:8080/search?q=cat"

以下のような実行結果が表示されます。

{"limit":"10","query":"cat"}

コードを解説します。

q := c.Query("q")
limit := c.DefaultQuery("limit", "10")

c.Query("q") は URL のクエリ文字列から q の値を取り出します。キーが存在しない場合は空文字列を返します。c.DefaultQuery("limit", "10") は同様にクエリを取り出しつつ、未指定時に "10" を返す動きです。

📝 パスパラメータとクエリパラメータの違い
パスパラメータはURLのパスの一部(/hello/Taro)、クエリパラメータはURLの ? 以降(/search?q=cat)で値を指定します。リソースを特定する場合はパスパラメータ、検索条件やオプションを指定する場合はクエリパラメータが使われるのが一般的です。

3. リクエストボディとバリデーション

POST や PUT などでJSONボディを受け取る場合、Ginでは構造体と c.ShouldBindJSON を組み合わせて扱います。書き方は以下のとおりです。

type 構造体名 struct {
    フィールド名 型 `json:"キー名" binding:"required"`   // binding:"required" で必須指定
}

var input 構造体名
if err := c.ShouldBindJSON(&input); err != nil {
    c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
    return
}

c.ShouldBindJSON はリクエストボディのJSONを構造体にデコードし、同時に binding タグに基づくバリデーションを実行します。バリデーションに失敗した場合はエラーが返るため、400 Bad Request を返して処理を打ち切るのが一般的です。

main.go を以下の内容で置き換えて保存します。これは、/items にPOSTで送られたJSON({"name":"...", "price":...} 形式)を Item 構造体にデコードし、binding:"required" によるバリデーションを通したうえで受け取った内容をJSONで返すコードです。

package main

import (
    "net/http"

    "github.com/gin-gonic/gin"
)

type Item struct {
    Name  string  `json:"name" binding:"required"`
    Price float64 `json:"price" binding:"required"`
}

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

    r.POST("/items", func(c *gin.Context) {
        var input Item
        if err := c.ShouldBindJSON(&input); err != nil {
            c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
            return
        }
        c.JSON(http.StatusCreated, gin.H{
            "message": "アイテムを作成しました",
            "item":    input,
        })
    })

    r.Run(":8080")
}

既存のサーバが動いている場合は Ctrl+C で停止し、以下のコマンドで再起動します。

go run main.go

別のターミナルで、-d オプションでJSONボディをPOSTします。

curl -X POST http://localhost:8080/items -H "Content-Type: application/json" -d '{"name":"ノート","price":250}'

以下のような実行結果が表示されます。

{"item":{"name":"ノート","price":250},"message":"アイテムを作成しました"}

送信したJSONの name と price が Item 構造体にデコードされ、そのままレスポンスに反映されています。

必須フィールドの name を省略した場合の挙動も確認します。

curl -X POST http://localhost:8080/items -H "Content-Type: application/json" -d '{"price":250}'

以下のような実行結果が表示されます。

{"error":"Key: 'Item.Name' Error:Field validation for 'Name' failed on the 'required' tag"}

binding:"required" に基づくバリデーションが自動的に行われ、Name フィールドが必須であることを示すエラーが返されました。

コードを解説します。

type Item struct {
    Name  string  `json:"name" binding:"required"`
    Price float64 `json:"price" binding:"required"`
}

json:"name" のタグでJSONキーとGoのフィールドを対応付け、binding:"required" で必須フィールドを宣言します。binding タグには required 以外にも email(メールアドレス形式)や min・max(数値の範囲)など、多数のバリデーションルールがあります(詳しくは go-playground/validator に記載があります)。

var input Item
if err := c.ShouldBindJSON(&input); err != nil {
    c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
    return
}

c.ShouldBindJSON(&input) はリクエストボディのJSONを input にデコードし、binding タグに基づくバリデーションを同時に実行します。デコード失敗・バリデーション失敗のいずれもエラーとして返るため、400 Bad Request を返して早期リターンする形が定型パターンです。

c.JSON(http.StatusCreated, gin.H{
    "message": "アイテムを作成しました",
    "item":    input,
})

http.StatusCreated(201)を返しています。リソース作成が成功した場合の慣例的なステータスコードで、net/http の w.WriteHeader(http.StatusCreated) に相当します。

💡 ポイント
c.ShouldBindJSON と似た関数に c.BindJSON がありますが、BindJSON はバリデーション失敗時に自動で 400 を返してしまうため、独自のエラー整形をしたい場面では扱いにくくなります。エラーレスポンスの形式を自分で決めたい場合は ShouldBindJSON を使い、err に応じてレスポンスを作る書き方が一般的です。