REST APIレスポンスJSONからGo構造体への変換

GoでのREST APIレスポンスのモデリング

ほとんどのREST APIはデータをページネーション、ステータス、エラー詳細などのメタデータを含む標準的なエンベロープでラップします。これらのパターンをGo構造体に変換するには、慎重な型モデリングが必要です。

典型的なAPIレスポンス

{
  "status": "ok",
  "data": {
    "users": [
      { "id": 1, "name": "Alice", "email": "alice@example.com" },
      { "id": 2, "name": "Bob", "email": "bob@example.com" }
    ]
  },
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 152,
    "total_pages": 8
  }
}

生成されるGo構造体

type APIResponse struct {
    Status     string     `json:"status"`
    Data       Data       `json:"data"`
    Pagination Pagination `json:"pagination"`
}

type Data struct {
    Users []User `json:"users"`
}

type User struct {
    ID    int    `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
}

type Pagination struct {
    Page       int `json:"page"`
    PerPage    int `json:"per_page"`
    Total      int `json:"total"`
    TotalPages int `json:"total_pages"`
}

ジェネリックレスポンスラッパー

実際には、エンドポイント間で再利用するためにジェネリックラッパーを作成することが多いです：

type APIResponse[T any] struct {
    Status     string      `json:"status"`
    Data       T           `json:"data"`
    Pagination *Pagination `json:"pagination,omitempty"`
    Error      *APIError   `json:"error,omitempty"`
}

type APIError struct {
    Code    string `json:"code"`
    Message string `json:"message"`
}

使用法：ユーザーリストには APIResponse[UserListData]、注文には APIResponse[OrderData]。

エラー処理

APIはエラー時に異なる構造を返すことが多いです。ポインタフィールドと omitempty の使用、または別のエラー構造体により、両方のケースをきれいに処理できます。