概要
Go言語とGinフレームワークを活用して、RESTful APIを効率的に構築する方法を解説します。この記事では、新聞を管理するAPIを例に、コントローラー層の設計・実装を学びます。
この記事を読めば以下のことがわかります：
- Ginフレームワークの基本的な使い方
- RESTfulなエンドポイントの実装方法
- HTTPステータスコードやリクエスト/レスポンスの正しい扱い方
- ハンドラーにおけるエラー処理のポイント
コントローラーの役割とは？
コントローラーは、クライアントからのリクエストを受け取り、適切なレスポンスを返すためのロジックを記述する層です。以下の役割を果たします：
-
リクエストの検証
リクエストボディやURLパラメータの内容が正しいかをチェックします。 -
ビジネスロジックの呼び出し
モデル層やサービス層を呼び出して、データベース操作などの処理を委譲します。 -
レスポンスの整形
クライアントが期待する形式でデータを返します。
新聞管理APIのコントローラー実装
以下のコードは、新聞を管理するコントローラー層の実装例です。
全体の構造
package controllers
import (
"net/http"
"github.com/gin-gonic/gin"
"go-api-newspaper/api"
"go-api-newspaper/app/models"
"go-api-newspaper/pkg/logger"
)
// メソッドを関連付けることで、各エンドポイントの処理を実装。
type NewspaperHandler struct{}
NewspaperHandler は新聞に関連するエンドポイントの処理を集約した構造体です。この構造体にメソッドを定義し、各APIエンドポイントと紐付けます。
各エンドポイントの実装
新聞の作成（Create）
func (a *NewspaperHandler) CreateNewspaper(c *gin.Context) {
var requestBody api.CreateNewspaperJSONRequestBody // JSONリクエストボディを受け取る構造体
if err := c.ShouldBindJSON(&requestBody); err != nil {
logger.Warn(err.Error())
c.JSON(http.StatusBadRequest, api.ErrorResponse{Message: err.Error()})
return
}
createdNewspaper, err := models.CreateNewspaper(
requestBody.Title,
requestBody.ColumnName)
if err != nil {
logger.Error(err.Error())
c.JSON(http.StatusInternalServerError, api.ErrorResponse{Message: err.Error()})
return
}
c.JSON(http.StatusCreated, createdNewspaper) // 201ステータスで作成結果を返す
}
解説:
-
c.ShouldBindJSONを使って、リクエストボディを構造体にマッピングします。 - モデル層の
CreateNewspaperメソッドを呼び出してデータを保存します。 - 成功時は
http.StatusCreated（201ステータス）を返します。
新聞の取得（Read）
func (a *NewspaperHandler) GetNewspaperById(c *gin.Context, ID int) {
newspaper, err := models.GetNewspaper(ID)
if err != nil {
logger.Error(err.Error())
c.JSON(http.StatusInternalServerError, api.ErrorResponse{Message: err.Error()})
return
}
c.JSON(http.StatusOK, newspaper) // 200ステータスでデータを返す
}
解説:
-
models.GetNewspaperを呼び出し、指定されたIDの新聞データを取得します。 - データが正常に取得できた場合は、
http.StatusOK（200ステータス）を返します。 - エラーが発生した場合は、
http.StatusInternalServerErrorを返してエラー内容をレスポンスします。
新聞の更新（Update）
func (a *NewspaperHandler) UpdateNewspaperById(c *gin.Context, ID int) {
var requestBody api.UpdateNewspaperByIdJSONRequestBody
if err := c.ShouldBindJSON(&requestBody); err != nil {
logger.Warn(err.Error())
c.JSON(http.StatusBadRequest, api.ErrorResponse{Message: err.Error()})
return
}
newspaper, err := models.GetNewspaper(ID)
if err != nil {
logger.Error(err.Error())
c.JSON(http.StatusInternalServerError, api.ErrorResponse{Message: err.Error()})
return
}
if requestBody.Title != nil {
newspaper.Title = *requestBody.Title
}
if requestBody.ColumnName != nil {
newspaper.ColumnName = *requestBody.ColumnName
}
if err := newspaper.Save(); err != nil {
logger.Error(err.Error())
c.JSON(http.StatusInternalServerError, api.ErrorResponse{Message: err.Error()})
return
}
c.JSON(http.StatusOK, newspaper) // 200ステータスで更新結果を返す
}
解説:
-
c.ShouldBindJSONでリクエストボディをパースし、必要に応じてモデルのプロパティを更新します。 - モデルの
Saveメソッドを利用して変更を保存します。
新聞の削除（Delete）
func (a *NewspaperHandler) DeleteNewspaperById(c *gin.Context, ID int) {
newspaper := models.Newspaper{ID: ID}
if err := newspaper.Delete(); err != nil {
logger.Error(err.Error())
c.JSON(http.StatusInternalServerError, api.ErrorResponse{Message: err.Error()})
return
}
c.JSON(http.StatusNoContent, nil) // 204ステータスで成功を通知
}
解説:
- モデルの
Deleteメソッドを呼び出して対象データを削除します。 - 削除が成功した場合は、
http.StatusNoContent（204ステータス）を返します。
まとめ
この記事では、Ginを使ったRESTful APIのコントローラー実装について学びました。以下のポイントを押さえましょう：
- Ginの
Contextを使ったリクエスト・レスポンスの管理 - HTTPステータスコードを適切に使用してクライアントに状態を通知
- モデル層と連携し、ビジネスロジックをシンプルに実装
この記事のコードを活用して、あなたのプロジェクトで効率的なAPI設計を実現してください！