APIの実装

任意の場所に notes-gin フォルダを作成し、Visual Studio Codeの「ファイル」→「フォルダーを開く」から作成した notes-gin フォルダを開きます。以降の操作は、Visual Studio Codeのターミナルから行います。

1. プロジェクトの準備

任意の場所に notes-gin フォルダを作成し、Visual Studio Codeの「ファイル」→「フォルダーを開く」から作成した notes-gin フォルダを開きます。以降の操作は、Visual Studio Codeのターミナルから行います。

notes-gin/  ← このフォルダを作成

モジュールを初期化します。

go mod init notes-gin

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

go: creating new go.mod: module notes-gin

続いて、Gin本体を導入します。

go get github.com/gin-gonic/gin

以下のような実行結果が表示されます(バージョンは環境により変わります)。

go: added github.com/gin-gonic/gin v1.10.0

GORM本体を導入します。

go get gorm.io/gorm

以下のような実行結果が表示されます(バージョンは環境により変わります)。

go: added gorm.io/gorm v1.25.12

続いて、GORMのMySQL用ドライバを導入します。

go get gorm.io/driver/mysql

以下のような実行結果が表示されます(バージョンは環境により変わります)。

go: added gorm.io/driver/mysql v1.5.7

最後に、.env ファイルから接続情報を読み込むための godotenv パッケージを導入します。DB接続用のユーザ名やパスワードといった秘匿情報をコードに直接書かず、.env ファイルから環境変数として読み込むために使います。

go get github.com/joho/godotenv

以下のような実行結果が表示されます(バージョンは環境により変わります)。

go: added github.com/joho/godotenv v1.5.1

go.mod に4つの依存関係が並び、go.sum が生成されていれば準備完了です。中身を確認すると、require ディレクティブに導入した4つのパッケージと、それらが内部で使う間接的な依存パッケージが並んでいます。

module notes-gin

go 1.x

require (
    github.com/gin-gonic/gin v1.x.x // indirect
    github.com/joho/godotenv v1.x.x // indirect
    gorm.io/driver/mysql v1.x.x // indirect
    gorm.io/gorm v1.x.x // indirect
    // ... 上記に加えて、Gin と GORM が内部で使う複数の間接依存パッケージも並びます
)

この時点ではまだ main.go を書いていないため、go get で導入したパッケージも含めて全て // indirect(間接的な依存関係)としてマークされています。次のステップで main.go に import を書くと、直接使うパッケージからは // indirect が外れます。

2. モデルの定義

最初に、ノートを表す Note モデルを定義します。この後に作る main.go(db.AutoMigrate(&Note{}) でテーブルを自動作成)や handler.go(各ハンドラ関数)が Note 構造体を参照するため、参照される側の型を先に用意しておく必要があります。DBの notes テーブルの1行が、Goの Note 構造体1つに対応します。

本章で扱う notes テーブルは、以下のカラム構成で作ります。

カラム名 型 制約 説明
id bigint unsigned PRIMARY KEY / AUTO_INCREMENT ノートを一意に識別するID
title varchar(200) NOT NULL ノートのタイトル
body text - ノート本文
created_at datetime - ノートを作成した日時(GORMが自動で書き込む)

このテーブル定義は、次に定義する Note 構造体の gorm タグから GORM の AutoMigrate によって自動生成されます。

Visual Studio Codeのエクスプローラーで notes-gin フォルダを右クリックし、「新しいファイル」を選択して model.go を作成します。

notes-gin/
├── go.mod
├── go.sum
└── model.go  ← このファイルを作成

ノートの型を宣言するため、作成した model.go に以下の内容を記述して保存します。

package main

import "time"

type Note struct {
    ID        uint      `gorm:"primaryKey" json:"id"`
    Title     string    `gorm:"size:200;not null" json:"title" binding:"required"`
    Body      string    `gorm:"type:text" json:"body"`
    CreatedAt time.Time `json:"created_at"`
}

コードを解説します。

type Note struct {
    ID        uint      `gorm:"primaryKey" json:"id"`
    Title     string    `gorm:"size:200;not null" json:"title" binding:"required"`
    Body      string    `gorm:"type:text" json:"body"`
    CreatedAt time.Time `json:"created_at"`
}

gorm タグはGORMが notes テーブルを作成する際の制約を、json タグはJSONレスポンスに含めるキー名を指定します。Title の binding:"required" は、後で扱う c.ShouldBindJSON で必須フィールドとして扱うためのタグです。CreatedAt はGORMがレコード作成時刻を自動で書き込む特別なフィールド名です。

3. .env ファイルの作成

main.go の中にDB接続用のユーザ名・パスワードを直接書くと、コードを変更するたびに書き換える必要があり、うっかりGitに含めてしまうリスクもあります。ここでは、接続情報を .env ファイルにまとめて、Goのコードからは環境変数として読み込む形にします。

Visual Studio Codeのエクスプローラーで notes-gin フォルダを右クリックし、「新しいファイル」を選択して .env ファイルを作成します。

notes-gin/
├── .env  ← このファイルを作成
├── go.mod
├── go.sum
└── model.go

作成した .env ファイルに以下の内容を記述して保存します。各項目の意味は下記のとおりです。

変数名 説明
MYSQL_USER 接続先MySQLのユーザ名を指定する。ここでは root を使う
MYSQL_PASSWORD 上記ユーザのパスワードを指定する。先ほど mysql -u root -p で入力した自分のMySQLパスワードに書き換える
MYSQL_HOST 接続先MySQLのホスト名またはIPアドレスを指定する。ローカルで動作しているMySQLに接続するため 127.0.0.1 を使う
MYSQL_PORT 接続先MySQLの待ち受けポートを指定する。MySQLのデフォルトである 3306 を使う
MYSQL_DATABASE 接続先のデータベース名を指定する。先ほど作成した notes_api を指定する
MYSQL_USER=root
MYSQL_PASSWORD=あなたのパスワード
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_DATABASE=notes_api

4. main.go の初期実装

続いて、エントリポイントとなる main.go を作成します。まずはデータベース接続と Note テーブルの自動作成、サーバ起動までを実装します。エンドポイントは以降の節で少しずつ追加していきます。

4.1 main.go の作成

notes-gin フォルダに main.go を作成します。

notes-gin/
├── .env
├── go.mod
├── go.sum
├── main.go   ← このファイルを作成
└── model.go

DB接続とサーバ起動をまとめて実装するため、作成した main.go に以下の内容を記述して保存します。

package main

import (
    "fmt"
    "os"

    "github.com/gin-gonic/gin"
    "github.com/joho/godotenv"
    "gorm.io/driver/mysql"
    "gorm.io/gorm"
)

var db *gorm.DB

func main() {
    if err := godotenv.Load(); err != nil {
        fmt.Println(".envファイル読み込み失敗:", err)
        return
    }

    dsn := fmt.Sprintf(
        "%s:%s@tcp(%s:%s)/%s?charset=utf8mb4&parseTime=True&loc=Local",
        os.Getenv("MYSQL_USER"),
        os.Getenv("MYSQL_PASSWORD"),
        os.Getenv("MYSQL_HOST"),
        os.Getenv("MYSQL_PORT"),
        os.Getenv("MYSQL_DATABASE"),
    )

    var err error
    db, err = gorm.Open(mysql.Open(dsn), &gorm.Config{})
    if err != nil {
        panic(err)
    }
    db.AutoMigrate(&Note{})

    r := gin.Default()

    r.Run(":8080")
}

4.2 サーバの起動確認

以下のコマンドでサーバを起動します。go run . は、カレントディレクトリのGoパッケージ全体(main.go と model.go)をまとめてコンパイルして実行します。go run main.go のようにファイル名を指定してしまうと model.go の Note 型が読み込まれず、コンパイルエラーになります。

go run .

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

[GIN-debug] Listening and serving HTTP on :8080

Gin独自のdebugログとともにポート 8080 で待ち受け状態になれば、DB接続と notes テーブルの自動作成、サーバ起動が正しく動いています。エンドポイントはまだ登録していないため、curl を叩いても 404 が返りますが、以降の節で1つずつルートを追加していきます。

⚠️ 「./main.go:XX:XX: undefined: Note」というエラーが出る場合
go run main.go のようにファイル名を指定して実行している可能性が高いです。本章はマルチファイル構成(main.go と model.go)で、main.go から model.go の Note 型を参照しているため、単一ファイル指定ではコンパイルが通りません。go run . としてカレントディレクトリのGoパッケージ全体をまとめてコンパイル・実行してください。
⚠️ 「panic: Error 1045 (28000): Access denied for user 'root'@...」というエラーが出る場合
.env の MYSQL_PASSWORD が実際のMySQLパスワードと一致していない可能性が高いです。.env を、mysql -u root -p でログインできたパスワードに書き換えてから、再度 go run . を実行してください。

4.3 作成されたテーブルの確認

AutoMigrate(&Note{}) によって、この起動のタイミングで notes テーブルが自動作成されています。MySQL CLIから実際にテーブルが作られていることを確認します。別のターミナルを開き、root ユーザでMySQLにログインします。

mysql -u root -p

ログイン後、notes_api データベースを使用します。

USE notes_api;

続いて、テーブル一覧を表示します。

SHOW TABLES;

以下のように、notes テーブルが一覧に表示されます。

+---------------------+
| Tables_in_notes_api |
+---------------------+
| notes               |
+---------------------+

続いて、notes テーブルの構造を確認します。

DESCRIBE notes;

以下のように、Note 構造体で定義したフィールドがそのままカラムとして作られています。

+------------+-----------------+------+-----+---------+----------------+
| Field      | Type            | Null | Key | Default | Extra          |
+------------+-----------------+------+-----+---------+----------------+
| id         | bigint unsigned | NO   | PRI | NULL    | auto_increment |
| title      | varchar(200)    | NO   |     | NULL    |                |
| body       | text            | YES  |     | NULL    |                |
| created_at | datetime(3)     | YES  |     | NULL    |                |
+------------+-----------------+------+-----+---------+----------------+

Goで書いた Note 構造体の定義が、MySQL側のテーブル構造にそのまま反映されていることが確認できました。確認できたら、exit; でMySQLのプロンプトを抜けます。

exit;

4.4 コードの解説

コードを解説します。

var db *gorm.DB

db をパッケージレベルの変数として宣言します。この後の節で追加するハンドラ関数からも同じDB接続を参照できるようにします。

if err := godotenv.Load(); err != nil {
    fmt.Println(".envファイル読み込み失敗:", err)
    return
}

godotenv.Load() で、カレントディレクトリの .env を読み込んで環境変数として登録します。以降の os.Getenv("MYSQL_USER") などで各値を取り出せるようになります。

dsn := fmt.Sprintf(
    "%s:%s@tcp(%s:%s)/%s?charset=utf8mb4&parseTime=True&loc=Local",
    os.Getenv("MYSQL_USER"),
    os.Getenv("MYSQL_PASSWORD"),
    os.Getenv("MYSQL_HOST"),
    os.Getenv("MYSQL_PORT"),
    os.Getenv("MYSQL_DATABASE"),
)

.env から読み込んだ環境変数を組み合わせて、MySQLへの接続文字列(DSN)を作ります。パスワードなどの秘匿情報を直接コードに書かないため、Gitに含めるファイル(main.go)と含めないファイル(.env)を分けて管理できます。

db, err = gorm.Open(mysql.Open(dsn), &gorm.Config{})
...
db.AutoMigrate(&Note{})

gorm.Open でMySQLへ接続し、AutoMigrate で Note モデルから notes テーブルを自動生成します。テーブルが既に存在する場合は不足カラムだけを追加します。

r := gin.Default()
...
r.Run(":8080")

Ginのルータを初期化し、ポート 8080 で待ち受けを開始します。この段階では r.GET / r.POST などのルート登録はまだありません。