Gin初心者JSON応答

Gin初心者のためのJSONレスポンス入門

Ginフレームワークを使い始めたばかりの方にとって、JSONレスポンスの返却は最初のハードルです。Ginでは c.JSON メソッドを呼び出すだけで、HTTPステータスコードとJSONデータを簡単に返すことができます。以下の例では、ステータスコード200とシンプルなJSONオブジェクトを返却しています。

func main() {
    r := gin.Default()
    r.GET("/ping", func(c *gin.Context) {
        c.JSON(200, gin.H{
            "message": "pong",
        })
    })
    r.Run()
}

このコードは、gin.H を使ってマップ構造でJSONを作成し、c.JSON で返却しています。Gin初心者はまずこのパターンを覚えておくと、API応答の基本が身につきます。

c.JSONとgin.Hを使ったレスポンス返却の実装

c.JSON は第1引数にステータスコード、第2引数に返却データを取ります。gin.H は map[string]interface{} のショートハンドで、JSONオブジェクトを簡潔に表現できます。以下はエラーハンドリングを含めた実装例です。

func getUser(c *gin.Context) {
    id := c.Param("id")
    user, err := service.FindUser(id)
    if err != nil {
        c.JSON(404, gin.H{
            "error": "User not found",
        })
        return
    }
    c.JSON(200, gin.H{
        "id":   user.ID,
        "name": user.Name,
    })
}

ステータスコードを適切に設定することで、クライアント側はレスポンスの意味を正しく解釈できます。成功時は200、リソース未見時は404、サーバー内部エラーは500などを使い分けましょう。

構造体バインドでデータ送信を簡潔に

JSONレスポンスを構造体で返却する場合、Ginは自動的に構造体をJSONに変換します。これにより、gin.H を使わずに型安全なコードを書けます。以下は構造体を使った例です。

type UserResponse struct {
    ID   string `json:"id"`
    Name string `json:"name"`
}

func getUser(c *gin.Context) {
    id := c.Param("id")
    user, err := service.FindUser(id)
    if err != nil {
        c.JSON(404, gin.H{"error": "User not found"})
        return
    }
    resp := UserResponse{
        ID:   user.ID,
        Name: user.Name,
    }
    c.JSON(200, resp)
}

構造体バインドを使うことで、JSONキーのミスや型の不一致をコンパイル時に検出でき、API応答の品質が向上します。

ステータスコードとAPI応答のベストプラクティス

APIを設計する際は、ステータスコードとレスポンス構造を統一することが重要です。以下のポイントを押さえておきましょう。

成功時は常に200系（200 OK, 201 Created など）を使用。
クライアント側の入力ミスは400系（400 Bad Request, 422 Unprocessable Entity）。
認証エラーは401、認可エラーは403。
サーバー内部エラーは500系。
エラーレスポンスは gin.H{"error": "message"} で統一。

これらを守ることで、データ送信とAPI応答の整合性が保たれ、クライアント開発者が扱いやすいインターフェースを提供できます。

なんでも技術ブログ

このブログを検索