はじめに
APIサーバーを構築する際、Go（Golang）とGinフレームワークを使うのは非常に効率的です。この記事では、コードを細かく分解し、初めての方でもわかりやすいように徹底的に解説します。また、Dockerで立ち上げたMySQLと接続する部分も含めて、環境構築から動作確認までを網羅します。
前提条件
- Goの基本的な知識（簡単な構文を理解しているレベルでOK）
- Docker環境のセットアップ済み
- MySQLをDockerで動かしている
実装するコードの全体像
以下は、APIサーバーを実装するコード全体です。詳細な説明は後述します。
package main
import (
"context" // コンテキスト処理を提供する標準パッケージ
"encoding/json" // JSON処理をサポート
"errors" // エラー処理の標準パッケージ
"fmt" // フォーマットされたI/Oを提供
"go-api-newspaper/pkg/logger" // ロガー（ログ出力用のパッケージ）
"log" // ログ出力用の標準パッケージ
"net/http" // HTTPサーバーの実装に必要な標準パッケージ
"os" // OS操作用（環境変数やシグナル処理）
"os/signal" // OSシグナル処理を提供
"syscall" // システムコールシグナルを提供
"time" // 時間操作をサポートする標準パッケージ
"github.com/gin-gonic/gin" // Gin Webフレームワーク
middleware "github.com/oapi-codegen/gin-middleware" // OpenAPIリクエストバリデータ
swaggerfiles "github.com/swaggo/files" // Swagger UIファイル
ginSwagger "github.com/swaggo/gin-swagger" // Swagger UIをGinでラップ
"github.com/swaggo/swag" // Swaggerの機能を提供
"go-api-newspaper/api" // 自作APIパッケージ
"go-api-newspaper/app/controllers" // 自作コントローラパッケージ
"go-api-newspaper/app/models" // 自作モデルパッケージ
"go-api-newspaper/configs" // 自作設定パッケージ
)
func main() {
// データベースの初期化
if err := models.SetDatabase(models.InstanceMySQL); err != nil {
// 初期化に失敗した場合、ログにエラーを記録してプログラムを終了
logger.Fatal(err.Error())
}
// Ginのデフォルト設定を使用してルーターを作成
router := gin.Default()
// OpenAPI仕様を取得（API仕様のバリデーション用）
swagger, err := api.GetSwagger()
if err != nil {
// 取得に失敗した場合、プログラムを終了
panic(err)
}
// 開発環境の場合、Swagger UIを有効化
if configs.Config.IsDevelopment() {
swaggerJson, _ := json.Marshal(swagger) // OpenAPI仕様をJSON形式に変換
var SwaggerInfo = &swag.Spec{
InfoInstanceName: "swagger",
SwaggerTemplate: string(swaggerJson),
}
swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo) // Swagger情報を登録
router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler)) // Swagger UIエンドポイントを追加
}
// APIのエンドポイントを設定
apiGroup := router.Group("/api") // ベースURLを`/api`に設定
{
v1 := apiGroup.Group("/v1") // バージョン1のAPIをグループ化
{
// OpenAPI仕様に基づくリクエストバリデーションをミドルウェアとして追加
v1.Use(middleware.OapiRequestValidator(swagger))
newspaperHandler := &controllers.NewspaperHandler{} // コントローラをインスタンス化
api.RegisterHandlers(v1, newspaperHandler) // ハンドラをエンドポイントに登録
}
}
// HTTPサーバーの設定
srv := &http.Server{
Addr: "0.0.0.0:8080", // サーバーをポート8080で待機
Handler: router, // Ginルーターをハンドラとして設定
}
// サーバーをバックグラウンドで起動
go func() {
if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
// サーバーが予期せず停止した場合、エラーログを出力
logger.Fatal(err.Error())
}
}()
// OSシグナルを受け取るためのチャネルを作成
quit := make(chan os.Signal, 1)
// シグナルをキャッチ（SIGINT: Ctrl+C, SIGTERM: 終了要求）
signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
<-quit // シグナルを受け取るまでブロック
// サーバーのシャットダウン処理
log.Println("Shutdown Server ...")
defer logger.Sync() // ログのバッファをフラッシュ
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second) // 2秒のタイムアウト付きコンテキスト
defer cancel()
if err := srv.Shutdown(ctx); err != nil {
// シャットダウンに失敗した場合、エラーログを出力
logger.Error(fmt.Sprintf("Server Shutdown: %s", err.Error()))
}
<-ctx.Done() // コンテキストの完了を待つ
logger.Info("Shutdown") // シャットダウン完了をログ出力
}
詳細解説
データベースの初期化
if err := models.SetDatabase(models.InstanceMySQL); err != nil {
// 初期化に失敗した場合、ログにエラーを記録してプログラムを終了
logger.Fatal(err.Error())
}
models.SetDatabase(models.InstanceMySQL)を呼び出してデータベース接続を設定します。 Dockerで立ち上げたMySQLコンテナと接続するための設定が行われます。
Ginのデフォルト設定を使用してルーターを作成
router := gin.Default()
-
Ginとは？
Golangで人気のあるWebフレームワークで、高速なAPIの構築に利用されます。 -
gin.Default()とは？
Ginのデフォルト設定を使ってルーターを作成します。この設定には以下が含まれます：
・Loggerミドルウェア: リクエストをログに記録する。
・Recoveryミドルウェア: パニックをキャッチしてサーバーを落とさずにエラーレスポンスを返す。 -
カスタム設定にしたい場合はどうする？
gin.New()を使用して、必要なミドルウェアを自分で追加することができます。
Swaggerのセットアップ
// OpenAPI仕様を取得（API仕様のバリデーション用）
swagger, err := api.GetSwagger()
if err != nil {
panic(err)
}
// 開発環境の場合、Swagger UIを有効化
if configs.Config.IsDevelopment() {
swaggerJson, _ := json.Marshal(swagger) // OpenAPI仕様をJSON形式に変換
var SwaggerInfo = &swag.Spec{
InfoInstanceName: "swagger",
SwaggerTemplate: string(swaggerJson),
}
swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo) // Swagger情報を登録
router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler)) // Swagger UIエンドポイントを追加
}
-
Swaggerとは？
API仕様を記述するためのフォーマット（OpenAPI Specification）です。Swaggerを使うと、以下が可能になります：
・APIドキュメントの自動生成。
・Swagger UIを使ったAPIのインタラクティブなテスト。 -
swag.Spec とは？
swag.SpecはSwagger仕様を表現する構造体です。
InfoInstanceNameは登録するSwaggerの名前を指定し、SwaggerTemplateはAPI仕様をJSON形式で指定します。 -
swag.Registerとは？
Swagger仕様を内部に登録します。この後、Ginのルート設定などでSwagger UIやAPI仕様を利用可能にします。 -
ginSwagger.WrapHandlerとは？
Swagger UIを提供するためのハンドラを作成します。これにより、/swagger/*anyにアクセスするとSwagger UIが表示されます。
エンドポイントの登録
apiGroup := router.Group("/api")
{
v1 := apiGroup.Group("/v1")
{
// OpenAPI仕様に基づくリクエストバリデーションをミドルウェアとして追加
v1.Use(middleware.OapiRequestValidator(swagger)) // 変数swaggerのAPI仕様に基づくバリデーション
newspaperHandler := &controllers.NewspaperHandler{}
api.RegisterHandlers(v1, newspaperHandler) // ルーターに登録
}
}
Ginフレームワークを使い、/api/v1にエンドポイントを設定。
OpenAPI仕様に基づきリクエストをバリデーションします。
v1.Use(middleware.OapiRequestValidator(swagger))
-
OapiRequestValidatorとは？
OpenAPI仕様に基づいてリクエストをバリデーションするミドルウェアです。 -
何をバリデーションするのか？
・リクエストのパスやメソッドが仕様と一致しているか。
・リクエストのパラメータやボディが仕様に準拠しているか。
これにより、不正なリクエストがAPIサーバーに到達するのを防ぎます。
api.RegisterHandlers(v1, newspaperHandler)とは？
OpenAPIで定義したエンドポイントとハンドラをルーターに登録します。これにより、指定されたエンドポイントにリクエストが来たときに、対応するハンドラが実行されます。
サーバーの起動
srv := &http.Server{
Addr: "0.0.0.0:8080",
Handler: router,
}
-
http.Serverとは？
Goの標準ライブラリで提供されるHTTPサーバーの設定構造体です。
go func() { // ListenAndServe サーバーを起動しリクエストをまつ
if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
logger.Fatal(err.Error())
}
}()
-
srv.ListenAndServe()とは？
サーバーを指定したアドレスとポートで起動します。 -
errors.Isとは？
エラーが特定の型や内容に一致しているかを判定します。 -
http.ErrServerClosedとは？
サーバーが正常にシャットダウンされたことを示すエラーです。このエラー以外の場合に致命的なログを出力します。
別ゴルーチンで実行され、メインの実行フローに影響を与えません。
チャンネルでシグナルをキャッチ
quit := make(chan os.Signal, 1)
signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
<-quit
log.Println("Shutdown Server ...")
-
チャンネルとは？
Goの並行処理で、ゴルーチン間の通信を行うためのデータ構造です。 -
なぜこれをするのか？
システムのシグナル（例：Ctrl+C）をキャッチしてサーバーを優雅にシャットダウンします。
サーバーのシャットダウン開始
log.Println("Shutdown Server ...")
defer logger.Sync() // ログのバッファをフラッシュする
- シグナルを受信してサーバーのシャットダウン処理を開始したことをログに出力します。これはすぐに実行されます。
-
logger.Sync()は、バッファ内に溜まったログを出力するための処理です。
タイムアウト付きのコンテキストを作成
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second) // ２秒のタイムアウトを持つコンテキスト
defer cancel()
-
context.WithTimeout(context.Background(), 2*time.Second)とは?
2秒のタイムアウトを持つコンテキストを作成します。
サーバーのシャットダウン処理が完了しない場合でも、2秒後には強制的に処理を終了させる仕組みを提供します。 -
defer cancel()とは？
コンテキストのキャンセル関数を登録し、プログラム終了時にリソースを解放します。この時点では実行されません。
サーバーのシャットダウン
if err := srv.Shutdown(ctx); err != nil {
logger.Error(fmt.Sprintf("Server Shutdown: %s", err.Error()))
}
-
srv.Shutdown(ctx)とは？
サーバーを優雅にシャットダウンします。
未処理のリクエストを完了させる時間を確保します。
タイムアウト（2秒）が経過した場合、未完了のリクエストを切り捨てて終了します。 -
エラーチェック
シャットダウン中にエラーが発生した場合、ログにエラーメッセージを出力します。
コンテキストの終了を待つ
<-ctx.Done()
logger.Info("Shutdown")
- コンテキストが終了（タイムアウトまたは処理完了）するまで待機します。
srv.Shutdown(ctx)が成功すると、ctx.Done()が閉じられます。
タイムアウトが発生した場合も同様に閉じられます。
まとめ
このコードは、APIサーバー構築の基本をしっかりと押さえています。
DockerでのMySQL連携やSwaggerによるAPI仕様の可視化、シグナル対応による優雅なシャットダウンなど、実用的な要素が含まれています。
ぜひ、このコードをコピーして、実際に動かしてみてください！
APIサーバーの作成がぐっと身近になります。