Go 1.20で始める本格RESTful API構築ガイド

2026年4月22日

お得なお知らせ

スポンサードリンク

AI時代のキャリア構築

プログラミング学習、今日から動き出す

「何から始めるか」で止まっている人こそ、無料説明会や本で自分に合うルートを30分で確定できます。

Enjoy Tech!｜月額制でWeb系に強い▶ (Kindle本)ＩＴエンジニアの転職学｜後悔しないキャリア戦略▶

▶ AIコーディング環境なら実践Claude Code入門（Amazon）が実務で即使える入門書です。Amazonベストセラーにも選ばれていますよ。

Contents

1 1. 環境構築とプロジェクト初期化
2 2. API 実装とルーティング設計
3 3. データベース連携とテスト戦略
4 4. Lint 設定と CI/CD パイプライン
5 5. マルチステージ Docker と Cloud Run デプロイ
6 6. 補足：本番運用に向けた追加ベストプラクティス
7 7. まとめ

スポンサードリンク

1. 環境構築とプロジェクト初期化

1‑1. Go のインストール（最新版推奨）

公式サイト https://go.dev/dl/ から Go 1.20 系の最新パッチ を取得し、以下の手順で展開します。

# Linux (amd64) 用例
wget https://golang.org/dl/go1.20.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.20.linux-amd64.tar.gz

# パスを永続化（~/.profile などに追記）
echo 'export PATH=$PATH:/usr/local/go/bin' &gt;&gt; ~/.profile
source ~/.profile

go version   # =&gt; go version go1.20.x linux/amd64

# Linux (amd64) 用例

wget https://golang.org/dl/go1.20.linux-amd64.tar.gz

sudo tar -C /usr/local -xzf go1.20.linux-amd64.tar.gz

# パスを永続化（~/.profile などに追記）

echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.profile

source ~/.profile

go version # => go version go1.20.x linux/amd64

Tip
macOS は Homebrew (brew install go@1.20) でも簡単にインストールできます。

1‑2. プロジェクトディレクトリと `go.mod` の作成

mkdir -p myapi &amp;&amp; cd myapi
go mod init github.com/yourname/myapi   # モジュールパスはご自身のリポジトリに合わせてください

mkdir -p myapi && cd myapi

go mod init github.com/yourname/myapi # モジュールパスはご自身のリポジトリに合わせてください

推奨ディレクトリ構造（Clean Architecture にヒント）

myapi/
├─ cmd/
│   └─ server/          # main パッケージ（エントリポイント）
├─ internal/
│   ├─ api/             # HTTP ハンドラ・ルーティング
│   ├─ model/           # ドメイン構造体
│   ├─ repository/      # 永続化層（インターフェイス + 実装）
│   └─ service/         # ビジネスロジック
├─ configs/             # 設定ファイル（YAML / TOML 等）
├─ test/                # 統合テスト向けのテストコード
└─ go.mod

myapi/

├─ cmd/

│ └─ server/ # main パッケージ（エントリポイント）

├─ internal/

│ ├─ api/ # HTTP ハンドラ・ルーティング

│ ├─ model/ # ドメイン構造体

│ ├─ repository/ # 永続化層（インターフェイス + 実装）

│ └─ service/ # ビジネスロジック

├─ configs/ # 設定ファイル（YAML / TOML 等）

├─ test/ # 統合テスト向けのテストコード

└─ go.mod

1‑3. 必要なライブラリを取得（バージョンは `go.mod` に任せる）

機能	推奨パッケージ	説明
ルーティング	chi (`github.com/go-chi/chi/v5`) または gorilla/mux（どちらか一方）	本稿では chi を例に採用します。軽量でミドルウェアの組み込みがシンプルです。
MySQL ドライバ	`github.com/go-sql-driver/mysql`	標準的な DB ドライバ
テスト用モック	`github.com/DATA-DOG/go-sqlmock`	SQL の振る舞いをインメモリで再現
アサーション	`github.com/stretchr/testify`	テストコードの可読性向上
バリデーション	`github.com/go-playground/validator/v10`	struct タグベースのバリデータ

# 例：chi 系列を使用する場合
go get github.com/go-chi/chi/v5
go get github.com/go-sql-driver/mysql
go get github.com/DATA-DOG/go-sqlmock
go get github.com/stretchr/testify
go get github.com/go-playground/validator/v10

# 例：chi 系列を使用する場合

go get github.com/go-chi/chi/v5

go get github.com/go-sql-driver/mysql

go get github.com/DATA-DOG/go-sqlmock

go get github.com/stretchr/testify

go get github.com/go-playground/validator/v10

選択ガイド
chi は標準 net/http と同様のハンドラインターフェイスを保ちつつ、ミドルウェアチェーンがシンプルです。
gorilla/mux はパス変数や正規表現マッチングに強みがありますが、依存関係が若干重くなる傾向があります。プロジェクトの要件（高度な URL パターンが必要か）で選択してください。

2. API 実装とルーティング設計

2‑1. エントリポイント (`cmd/server/main.go`)

package main

import (
    &quot;log&quot;
    &quot;net/http&quot;

    &quot;github.com/go-chi/chi/v5&quot;
    &quot;myapi/internal/api&quot;
)

func main() {
    r := chi.NewRouter()

    // 共通ミドルウェア（例：ログ出力、リクエストID付与など）
    r.Use(middleware.Logger) // 自前または go-chi の middleware

    // ルート登録
    api.RegisterRoutes(r)

    srv := &amp;http.Server{
        Handler: r,
        Addr:    &quot;:8080&quot;,
    }

    log.Println(&quot;&#x1f680; server listening on :8080&quot;)
    if err := srv.ListenAndServe(); err != nil &amp;&amp; err != http.ErrServerClosed {
        log.Fatalf(&quot;&#x2757; server failed: %v&quot;, err)
    }
}

package main

import (

"log"

"net/http"

"github.com/go-chi/chi/v5"

"myapi/internal/api"

)

func main() {

r := chi.NewRouter()

// 共通ミドルウェア（例：ログ出力、リクエストID付与など）

r.Use(middleware.Logger) // 自前または go-chi の middleware

// ルート登録

api.RegisterRoutes(r)

srv := &http.Server{

Handler: r,

Addr: ":8080",

}

log.Println("🚀 server listening on :8080")

if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {

log.Fatalf("❗ server failed: %v", err)

}

2‑2. ルーティング定義 (`internal/api/router.go`)

package api

import (
    &quot;net/http&quot;

    &quot;github.com/go-chi/chi/v5&quot;
)

// RegisterRoutes は外部から呼び出され、全ハンドラを登録します。
func RegisterRoutes(r chi.Router) {
    r.Post(&quot;/users&quot;, CreateUserHandler)
    r.Get(&quot;/users/{id}&quot;, GetUserHandler)

    // 例：ヘルスチェックエンドポイント
    r.Get(&quot;/healthz&quot;, func(w http.ResponseWriter, _ *http.Request) {
        w.WriteHeader(http.StatusOK)
    })
}

package api

import (

"net/http"

"github.com/go-chi/chi/v5"

)

// RegisterRoutes は外部から呼び出され、全ハンドラを登録します。

func RegisterRoutes(r chi.Router) {

r.Post("/users", CreateUserHandler)

r.Get("/users/{id}", GetUserHandler)

// 例：ヘルスチェックエンドポイント

r.Get("/healthz", func(w http.ResponseWriter, _ *http.Request) {

w.WriteHeader(http.StatusOK)

})

}

2‑3. データ構造体と JSON タグ (`internal/model/user.go`)

package model

// User は API の入出力で使用するドメインモデルです。
type User struct {
    ID        int64  `json:&quot;id,omitempty&quot;`                     // DB が生成した PK
    Name      string `json:&quot;name&quot; validate:&quot;required,min=2&quot;`   // バリデーションは validator/v10 に委譲
    Email     string `json:&quot;email&quot; validate:&quot;required,email&quot;` // 同上
    CreatedAt string `json:&quot;created_at,omitempty&quot;`             // ISO8601 文字列（例: 2023-01-02T15:04:05Z）
}

package model

// User は API の入出力で使用するドメインモデルです。

type User struct {

ID int64 `json:"id,omitempty"` // DB が生成した PK

Name string `json:"name" validate:"required,min=2"` // バリデーションは validator/v10 に委譲

Email string `json:"email" validate:"required,email"` // 同上

CreatedAt string `json:"created_at,omitempty"` // ISO8601 文字列（例: 2023-01-02T15:04:05Z）

}

2‑4. ハンドラ実装 (`internal/api/handler.go`)

package api

import (
    &quot;encoding/json&quot;
    &quot;net/http&quot;

    &quot;github.com/go-chi/chi/v5&quot;
    &quot;myapi/internal/model&quot;
    &quot;myapi/internal/service&quot;
)

// CreateUserHandler POST /users
func CreateUserHandler(w http.ResponseWriter, r *http.Request) {
    var req model.User
    if err := json.NewDecoder(r.Body).Decode(&amp;req); err != nil {
        writeError(w, http.StatusBadRequest, &quot;invalid JSON&quot;)
        return
    }
    defer r.Body.Close()

    // バリデーション（service 層に委譲）
    if err := service.ValidateUser(&amp;req); err != nil {
        writeError(w, http.StatusUnprocessableEntity, err.Error())
        return
    }

    created, err := service.CreateUser(r.Context(), &amp;req)
    if err != nil {
        writeError(w, http.StatusInternalServerError, &quot;failed to create user&quot;)
        return
    }
    respondJSON(w, http.StatusCreated, created)
}

// GetUserHandler GET /users/{id}
func GetUserHandler(w http.ResponseWriter, r *http.Request) {
    idParam := chi.URLParam(r, &quot;id&quot;)
    user, err := service.GetUserByID(r.Context(), idParam)
    if err != nil {
        writeError(w, http.StatusNotFound, &quot;user not found&quot;)
        return
    }
    respondJSON(w, http.StatusOK, user)
}

// ---------- ユーティリティ ----------
func writeError(w http.ResponseWriter, status int, msg string) {
    w.Header().Set(&quot;Content-Type&quot;, &quot;application/json&quot;)
    w.WriteHeader(status)
    _ = json.NewEncoder(w).Encode(map[string]string{&quot;error&quot;: msg})
}

func respondJSON(w http.ResponseWriter, status int, payload any) {
    w.Header().Set(&quot;Content-Type&quot;, &quot;application/json&quot;)
    w.WriteHeader(status)
    _ = json.NewEncoder(w).Encode(payload)
}

package api

import (

"encoding/json"

"net/http"

"github.com/go-chi/chi/v5"

"myapi/internal/model"

"myapi/internal/service"

)

// CreateUserHandler POST /users

func CreateUserHandler(w http.ResponseWriter, r *http.Request) {

var req model.User

if err := json.NewDecoder(r.Body).Decode(&req); err != nil {

writeError(w, http.StatusBadRequest, "invalid JSON")

return

}

defer r.Body.Close()

// バリデーション（service 層に委譲）

if err := service.ValidateUser(&req); err != nil {

writeError(w, http.StatusUnprocessableEntity, err.Error())

return

}

created, err := service.CreateUser(r.Context(), &req)

if err != nil {

writeError(w, http.StatusInternalServerError, "failed to create user")

return

}

respondJSON(w, http.StatusCreated, created)

}

// GetUserHandler GET /users/{id}

func GetUserHandler(w http.ResponseWriter, r *http.Request) {

idParam := chi.URLParam(r, "id")

user, err := service.GetUserByID(r.Context(), idParam)

if err != nil {

writeError(w, http.StatusNotFound, "user not found")

return

}

respondJSON(w, http.StatusOK, user)

}

// ---------- ユーティリティ ----------

func writeError(w http.ResponseWriter, status int, msg string) {

w.Header().Set("Content-Type", "application/json")

w.WriteHeader(status)

_ = json.NewEncoder(w).Encode(map[string]string{"error": msg})

}

func respondJSON(w http.ResponseWriter, status int, payload any) {

w.Header().Set("Content-Type", "application/json")

w.WriteHeader(status)

_ = json.NewEncoder(w).Encode(payload)

}

2‑5. バリデーションロジック (`internal/service/validation.go`)

package service

import (
    &quot;github.com/go-playground/validator/v10&quot;
    &quot;myapi/internal/model&quot;
)

var validatorInstance = validator.New()

// ValidateUser は構造体タグに基づき入力を検証します。
func ValidateUser(u *model.User) error {
    return validatorInstance.Struct(u)
}

package service

import (

"github.com/go-playground/validator/v10"

"myapi/internal/model"

)

var validatorInstance = validator.New()

// ValidateUser は構造体タグに基づき入力を検証します。

func ValidateUser(u *model.User) error {

return validatorInstance.Struct(u)

}

3. データベース連携とテスト戦略

3‑1. DB 接続ラッパー (`internal/repository/mysql.go`)

package repository

import (
    &quot;database/sql&quot;
    &quot;fmt&quot;

    _ &quot;github.com/go-sql-driver/mysql&quot;
)

// DB は sql.DB を埋め込んだラッパーです。
type DB struct {
    *sql.DB
}

// NewMySQL は接続プール設定付きの *DB を返します。
func NewMySQL(dsn string) (*DB, error) {
    db, err := sql.Open(&quot;mysql&quot;, dsn)
    if err != nil {
        return nil, fmt.Errorf(&quot;open mysql: %w&quot;, err)
    }
    // 推奨プール設定
    db.SetMaxOpenConns(25)
    db.SetMaxIdleConns(25)
    db.SetConnMaxLifetime(0)

    if err = db.Ping(); err != nil {
        return nil, fmt.Errorf(&quot;ping mysql: %w&quot;, err)
    }
    return &amp;DB{db}, nil
}

package repository

import (

"database/sql"

"fmt"

_ "github.com/go-sql-driver/mysql"

)

// DB は sql.DB を埋め込んだラッパーです。

type DB struct {

*sql.DB

}

// NewMySQL は接続プール設定付きの *DB を返します。

func NewMySQL(dsn string) (*DB, error) {

db, err := sql.Open("mysql", dsn)

if err != nil {

return nil, fmt.Errorf("open mysql: %w", err)

}

// 推奨プール設定

db.SetMaxOpenConns(25)

db.SetMaxIdleConns(25)

db.SetConnMaxLifetime(0)

if err = db.Ping(); err != nil {

return nil, fmt.Errorf("ping mysql: %w", err)

}

return &DB{db}, nil

}

3‑2. リポジトリインターフェイスと実装

package repository

import (
    &quot;context&quot;
    &quot;myapi/internal/model&quot;
)

// UserRepository は永続化層の抽象です。
type UserRepository interface {
    Create(ctx context.Context, u *model.User) (*model.User, error)
    GetByID(ctx context.Context, id int64) (*model.User, error)
}

// mysqlUserRepo は MySQL 実装です。
type mysqlUserRepo struct{ db *DB }

func NewUserRepository(db *DB) UserRepository {
    return &amp;mysqlUserRepo{db: db}
}

func (r *mysqlUserRepo) Create(ctx context.Context, u *model.User) (*model.User, error) {
    // 省略：INSERT 文と取得ロジック
    return nil, nil
}

func (r *mysqlUserRepo) GetByID(ctx context.Context, id int64) (*model.User, error) {
    // 省略：SELECT 文
    return nil, nil
}

package repository

import (

"context"

"myapi/internal/model"

)

// UserRepository は永続化層の抽象です。

type UserRepository interface {

Create(ctx context.Context, u *model.User) (*model.User, error)

GetByID(ctx context.Context, id int64) (*model.User, error)

}

// mysqlUserRepo は MySQL 実装です。

type mysqlUserRepo struct{ db *DB }

func NewUserRepository(db *DB) UserRepository {

return &mysqlUserRepo{db: db}

}

func (r *mysqlUserRepo) Create(ctx context.Context, u *model.User) (*model.User, error) {

// 省略：INSERT 文と取得ロジック

return nil, nil

}

func (r *mysqlUserRepo) GetByID(ctx context.Context, id int64) (*model.User, error) {

// 省略：SELECT 文

return nil, nil

}

3‑3. サービス層でリポジトリを利用

package service

import (
    &quot;context&quot;
    &quot;myapi/internal/model&quot;
    &quot;myapi/internal/repository&quot;
)

var userRepo repository.UserRepository // 実際は DI コンテナや init 時に注入

func CreateUser(ctx context.Context, u *model.User) (*model.User, error) {
    return userRepo.Create(ctx, u)
}

func GetUserByID(ctx context.Context, idStr string) (*model.User, error) {
    // 文字列 → int64 変換 + リポジトリ呼び出し
    return nil, nil
}

package service

import (

"context"

"myapi/internal/model"

"myapi/internal/repository"

)

var userRepo repository.UserRepository // 実際は DI コンテナや init 時に注入

func CreateUser(ctx context.Context, u *model.User) (*model.User, error) {

return userRepo.Create(ctx, u)

}

func GetUserByID(ctx context.Context, idStr string) (*model.User, error) {

// 文字列 → int64 変換 + リポジトリ呼び出し

return nil, nil

}

3‑4. ユニットテストのベストプラクティス

ハンドラ単体テスト (`internal/api/handler_test.go`)

package api_test

import (
    &quot;bytes&quot;
    &quot;net/http&quot;
    &quot;net/http/httptest&quot;
    &quot;testing&quot;

    &quot;github.com/DATA-DOG/go-sqlmock&quot;
    &quot;github.com/go-chi/chi/v5&quot;
    &quot;github.com/stretchr/testify/assert&quot;
    &quot;myapi/internal/api&quot;
    &quot;myapi/internal/repository&quot;
)

func TestCreateUserHandler(t *testing.T) {
    // ① sqlmock のセットアップ
    db, mock, err := sqlmock.New()
    assert.NoError(t, err)
    defer db.Close()

    mock.ExpectExec(`INSERT INTO users`).
        WithArgs(&quot;Alice&quot;, &quot;alice@example.com&quot;).
        WillReturnResult(sqlmock.NewResult(1, 1))

    userRepo := repository.NewUserRepository(&amp;repository.DB{DB: db})
    // テスト用にグローバル変数を書き換える（実装例として簡易的に示す）
    api.SetUserRepo(userRepo)

    // ② HTTP リクエスト作成
    payload := `{&quot;name&quot;:&quot;Alice&quot;,&quot;email&quot;:&quot;alice@example.com&quot;}`
    req := httptest.NewRequest(http.MethodPost, &quot;/users&quot;, bytes.NewBufferString(payload))
    rec := httptest.NewRecorder()

    // ③ chi Router にハンドラを登録して実行
    r := chi.NewRouter()
    api.RegisterRoutes(r)
    r.ServeHTTP(rec, req)

    assert.Equal(t, http.StatusCreated, rec.Code)
    // 必要なら JSON 内容の検証も追加
}

package api_test

import (

"bytes"

"net/http"

"net/http/httptest"

"testing"

"github.com/DATA-DOG/go-sqlmock"

"github.com/go-chi/chi/v5"

"github.com/stretchr/testify/assert"

"myapi/internal/api"

"myapi/internal/repository"

)

func TestCreateUserHandler(t *testing.T) {

// ① sqlmock のセットアップ

db, mock, err := sqlmock.New()

assert.NoError(t, err)

defer db.Close()

mock.ExpectExec(`INSERT INTO users`).

WithArgs("Alice", "alice@example.com").

WillReturnResult(sqlmock.NewResult(1, 1))

userRepo := repository.NewUserRepository(&repository.DB{DB: db})

// テスト用にグローバル変数を書き換える（実装例として簡易的に示す）

api.SetUserRepo(userRepo)

// ② HTTP リクエスト作成

payload := `{"name":"Alice","email":"alice@example.com"}`

req := httptest.NewRequest(http.MethodPost, "/users", bytes.NewBufferString(payload))

rec := httptest.NewRecorder()

// ③ chi Router にハンドラを登録して実行

r := chi.NewRouter()

api.RegisterRoutes(r)

r.ServeHTTP(rec, req)

assert.Equal(t, http.StatusCreated, rec.Code)

// 必要なら JSON 内容の検証も追加

}

リポジトリ層テスト（SQL モックだけで完結）

func TestUserRepository_Create(t *testing.T) {
    db, mock, _ := sqlmock.New()
    defer db.Close()

    mock.ExpectExec(`INSERT INTO users`).
        WithArgs(&quot;Bob&quot;, &quot;bob@example.com&quot;).
        WillReturnResult(sqlmock.NewResult(2, 1))

    repo := repository.NewUserRepository(&amp;repository.DB{DB: db})
    ctx := context.Background()
    u := &amp;model.User{Name: &quot;Bob&quot;, Email: &quot;bob@example.com&quot;}

    created, err := repo.Create(ctx, u)
    assert.NoError(t, err)
    assert.Equal(t, int64(2), created.ID)
}

func TestUserRepository_Create(t *testing.T) {

db, mock, _ := sqlmock.New()

defer db.Close()

mock.ExpectExec(`INSERT INTO users`).

WithArgs("Bob", "bob@example.com").

WillReturnResult(sqlmock.NewResult(2, 1))

repo := repository.NewUserRepository(&repository.DB{DB: db})

ctx := context.Background()

u := &model.User{Name: "Bob", Email: "bob@example.com"}

created, err := repo.Create(ctx, u)

assert.NoError(t, err)

assert.Equal(t, int64(2), created.ID)

}

ポイント
依存性注入（DI）を利用すれば、テスト時にモック実装だけ差し替えられます。
go-sqlmock はクエリ文字列の正規表現マッチングが可能なので、SQL の書き方が変わってもテストを柔軟に保てます。

4. Lint 設定と CI/CD パイプライン

4‑1. `golangci-lint` のインストール（バージョンは「最新版」）

# 最新リリースを自動取得する公式スクリプト
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $HOME/go/bin latest

# 最新リリースを自動取得する公式スクリプト

curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $HOME/go/bin latest

注意
固定バージョン（例：v1.57.2）は時間が経つと古くなるため、CI では latest タグや go.mod の toolchain セクションで管理することを推奨します。

4‑2. `.golangci.yml`（公式推奨リストをベースにカスタマイズ）

run:
  timeout: 5m
  modules-download-mode: readonly

linters:
  enable:
    - bodyclose
    - containedctx
    - cyclop
    - dupl
    - errname
    - errorlint
    - exportloopref
    - forcetypeassert
    - gci
    - gofmt
    - gosec
    - lll
    - nilerr
    - rowserrcheck
    - sqlclosecheck
    - tagliatelle
    - unconvert
    - whitespace

linters-settings:
  gci:
    sections:
      - standard
      - default
      - prefix(myapi)
  lll:
    line-length: 120

run:

timeout: 5m

modules-download-mode: readonly

linters:

enable:

- bodyclose

- containedctx

- cyclop

- dupl

- errname

- errorlint

- exportloopref

- forcetypeassert

- gci

- gofmt

- gosec

- lll

- nilerr

- rowserrcheck

- sqlclosecheck

- tagliatelle

- unconvert

- whitespace

linters-settings:

gci:

sections:

- standard

- default

- prefix(myapi)

lll:

line-length: 120

4‑3. GitHub Actions による自動化 (`.github/workflows/ci.yml`)

name: CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test-lint:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.20'

      - name: Cache modules
        uses: actions/cache@v3
        with:
          path: |
            ~/.cache/go-build
            ~/go/pkg/mod
          key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
          restore-keys: |
            ${{ runner.os }}-go-

      - name: Download dependencies
        run: go mod tidy

      - name: Run unit &amp; integration tests
        run: go test ./... -v -coverprofile=coverage.out

      - name: Install golangci-lint (latest)
        run: |
          curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh \
            | sh -s -- -b $HOME/go/bin latest
        env:
          GOLANGCI_LINT_VERSION: latest

      - name: Run golangci-lint
        run: $HOME/go/bin/golangci-lint run ./...

name: CI

on:

push:

branches: [ main ]

pull_request:

branches: [ main ]

jobs:

test-lint:

runs-on: ubuntu-latest

steps:

- name: Checkout repository

uses: actions/checkout@v4

- name: Set up Go

uses: actions/setup-go@v5

with:

go-version: '1.20'

- name: Cache modules

uses: actions/cache@v3

with:

path: |

~/.cache/go-build

~/go/pkg/mod

key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}

restore-keys: |

${{ runner.os }}-go-

- name: Download dependencies

run: go mod tidy

- name: Run unit & integration tests

run: go test ./... -v -coverprofile=coverage.out

- name: Install golangci-lint (latest)

run: |

curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh \

| sh -s -- -b $HOME/go/bin latest

env:

GOLANGCI_LINT_VERSION: latest

- name: Run golangci-lint

run: $HOME/go/bin/golangci-lint run ./...

ベストプラクティス
go test のカバレッジは Pull Request にコメントで自動報告すると、品質向上に役立ちます。
Linter とテストは同一ジョブで実行することで、CI 時間を短縮できます（ステップ間のキャッシュ共有）。

5. マルチステージ Docker と Cloud Run デプロイ

5‑1. Dockerfile（サイズ変動要因と目安）

# ---------- Build stage ----------
FROM golang:1.20-alpine AS builder

WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download

COPY . .
ENV CGO_ENABLED=0 GOOS=linux GOARCH=amd64
RUN go build -ldflags=&quot;-s -w&quot; -o /app/server ./cmd/server

# ---------- Runtime stage ----------
FROM alpine:3.19 AS runtime
WORKDIR /app

# ca-certificates は https 通信の必須パッケージだけをインストール
RUN apk add --no-cache ca-certificates

COPY --from=builder /app/server .
EXPOSE 8080
ENTRYPOINT [&quot;./server&quot;]

# ---------- Build stage ----------

FROM golang:1.20-alpine AS builder

WORKDIR /src

COPY go.mod go.sum ./

RUN go mod download

COPY . .

ENV CGO_ENABLED=0 GOOS=linux GOARCH=amd64

RUN go build -ldflags="-s -w" -o /app/server ./cmd/server

# ---------- Runtime stage ----------

FROM alpine:3.19 AS runtime

WORKDIR /app

# ca-certificates は https 通信の必須パッケージだけをインストール

RUN apk add --no-cache ca-certificates

COPY --from=builder /app/server .

EXPOSE 8080

ENTRYPOINT ["./server"]

イメージサイズに関する注意点

要因	影響例
ベースイメージ	`golang:1.20-alpine`（≈ 200 MB）→ ビルドステージのみで削除すれば、最終イメージは 10 ~ 30 MB 程度になることが多い
静的リンク (`CGO_ENABLED=0`)	`musl` 系のランタイムだけで動作でき、サイズが抑えられる
依存ライブラリの数	大量の C ライブラリや外部バイナリをインストールすると数十 MB 上乗せされる

結論
正確なサイズは docker build 後に docker images で確認してください。本文中の「数十 MB」はあくまで目安とし、実際のサイズはプロジェクト固有の依存関係に左右されます。

5‑2. ローカルビルド・テスト

docker build -t myapi:dev .
docker run --rm -p 8080:8080 myapi:dev

docker build -t myapi:dev .

docker run --rm -p 8080:8080 myapi:dev

ブラウザまたは curl http://localhost:8080/healthz が 200 OK を返せば成功です。

5‑3. Docker イメージの CI ビルド・プッシュ（GitHub Actions）

name: Release

on:
  push:
    tags:
      - 'v*'   # v1.0.0 等のタグが付いたときだけ実行

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
      id-token: write

    steps:
      - uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to GitHub Container Registry
        uses: docker/login-action@v2
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push Docker image
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ghcr.io/${{ github.repository }}:${{ github.ref_name }},ghcr.io/${{ github.repository }}:latest

name: Release

on:

push:

tags:

- 'v*' # v1.0.0 等のタグが付いたときだけ実行

jobs:

build-and-push:

runs-on: ubuntu-latest

permissions:

contents: read

packages: write

id-token: write

steps:

- uses: actions/checkout@v4

- name: Set up Docker Buildx

uses: docker/setup-buildx-action@v3

- name: Login to GitHub Container Registry

uses: docker/login-action@v2

with:

registry: ghcr.io

username: ${{ github.actor }}

password: ${{ secrets.GITHUB_TOKEN }}

- name: Build and push Docker image

uses: docker/build-push-action@v5

with:

context: .

push: true

tags: ghcr.io/${{ github.repository }}:${{ github.ref_name }},ghcr.io/${{ github.repository }}:latest

5‑4. Cloud Run へのデプロイ手順

Google Cloud SDK のインストール（ローカルでテストしたい場合）

bash curl https://sdk.cloud.google.com | bash exec -l $SHELL gcloud init

イメージを Artifact Registry へプッシュ（GitHub Actions が自動実行）
Cloud Run にデプロイ

bash PROJECT_ID=your-gcp-project REGION=us-central1 IMAGE=us-central1-docker.pkg.dev/$PROJECT_ID/myapi/myapi:latest

gcloud run deploy myapi \ --image $IMAGE \ --region $REGION \ --platform managed \ --allow-unauthenticated \ --set-env-vars DB_DSN="${DB_USER}:${DB_PASS}@tcp(${DB_HOST}:3306)/${DB_NAME}?parseTime=true"

シークレット管理（Secret Manager 推奨）

# Secret 作成例
gcloud secrets create db-dsn --replication-policy=&quot;automatic&quot;
echo -n &quot;user:pass@tcp(host:3306)/dbname?parseTime=true&quot; | \
  gcloud secrets versions add db-dsn --data-file=-

# デプロイ時にシークレットを環境変数として注入
gcloud run deploy myapi \
  ... \
  --update-secrets=db-dsn=DB_DSN:latest

# Secret 作成例

gcloud secrets create db-dsn --replication-policy="automatic"

echo -n "user:pass@tcp(host:3306)/dbname?parseTime=true" | \

gcloud secrets versions add db-dsn --data-file=-

# デプロイ時にシークレットを環境変数として注入

gcloud run deploy myapi \

... \

--update-secrets=db-dsn=DB_DSN:latest

セキュリティポイント
環境変数に平文で認証情報を書かない。Secret Manager 経由で注入するのが安全です。
Cloud Run の IAM でアクセス権限を最小化し、不要な公開は避けましょう。

6. 補足：本番運用に向けた追加ベストプラクティス

項目	内容
ロギング	`log/slog`（Go 1.21 以降）や `zap`、`zerolog` を導入し、JSON ログで構造化。
メトリクス	Prometheus 用エンドポイント (`/metrics`) と `go-metrics` ライブラリで CPU・GC 時間等を可視化。
ヘルスチェック	Cloud Run のヘルスチェックは `/healthz` が 200 を返すだけで OK。必要なら DB 接続確認も追加。
Graceful Shutdown	`http.Server.Shutdown` とシグナルハンドラで安全にプロセス終了。
依存関係の自動更新	Dependabot や Renovate Bot を有効化し、モジュールを常に最新に保つ。
コードレビューのチェックリスト	Lint, テストカバレッジ ≥ 80%、脆弱性スキャン（`go vet -tests`, `gosec`) が必須かどうかを CI に組み込む。

7. まとめ

フェーズ	主なポイント
環境構築	Go 1.20 の最新版インストール → `go.mod` 初期化、ディレクトリ設計
ルーティング選択	`chi`（軽量・ミドルウェアが簡単）か `gorilla/mux`（高度なパスマッチ）を要件で判断し、一貫した実装に統一
API 実装	`net/http` + ルータ → JSON エンコード/デコード、バリデーション (`validator/v10`)、統一エラーレスポンス
DB & テスト	MySQL ドライバ＋リポジトリインターフェイス抽象化 → `go-sqlmock` と `httptest` で高速テスト
Lint & CI	`golangci-lint`（最新版）と GitHub Actions による自動ビルド・テスト・Lint
Docker	マルチステージ Docker で最終イメージは 10 ~ 30 MB の目安（実際は依存により変動）
デプロイ	GitHub Actions → Artifact Registry → Cloud Run、Secret Manager で機密情報管理
運用拡張	ロギング・メトリクス・Graceful Shutdown・Dependabot による継続的改善

以上の手順とベストプラクティスを踏むことで、ローカル開発から本番環境への自動デプロイまで 一貫したフロー が実現できます。ぜひご自身のプロジェクトで試し、必要に応じてカスタマイズしてみてください！

スポンサードリンク

お得なお知らせ

スポンサードリンク

AI時代のキャリア構築

プログラミング学習、今日から動き出す

「何から始めるか」で止まっている人こそ、無料説明会や本で自分に合うルートを30分で確定できます。

Enjoy Tech!｜月額制でWeb系に強い▶ (Kindle本)ＩＴエンジニアの転職学｜後悔しないキャリア戦略▶

▶ AIコーディング環境なら実践Claude Code入門（Amazon）が実務で即使える入門書です。Amazonベストセラーにも選ばれていますよ。

-Go言語

comment コメントをキャンセル

: Go言語

Go 1.20での開発環境構築とTodo API実装完全ガイド

Go 1.20のインストールからDockerとGitHub Actionsを使った本番デプロイまで、一連の開発フローを具体例とコード付きで解説します。

: Go言語

Go言語学習ロードマップ2024：初心者から実務までの完全ガイド

本稿では、2024 年版の最新情報とツールを組み合わせた「Go 言語初心者学習ロードマップ 2024」を提示し、6 ヶ月で実務レベルに到達する手順を解説します。

: Go言語

2026年のGoエンジニア求人市場と年収・スキル徹底分析

国内で約1,500件以上のGoエンジニア求人があり、Webバックエンドやクラウドネイティブが主流。平均年収は600万円前後で、KubernetesやAWS経験が高く評価されます。

: Go言語

無料教材で始めるGo入門：インストールからWebサーバ・CLIまでのロードマップ

Go言語初心者が公式インストール手順と無料オンライン教材だけで、Hello WorldからWebサーバ・CLIツールまで実装できる学習ロードマップを提供します。

: Go言語

Go 1.22で始めるRESTful API開発ガイド：環境構築・プロジェクト設計・Router比較

Go 1.22環境でのAPI開発に必要なセットアップからコード設計、Router選択、テスト・デプロイまでを一括で学べる実践ガイドです。

2026年版 SIer 市場概況と最新トレンド｜AI・DX支援の費用相場とベスト10選定チェックリスト

2026年版在宅勤務を快適にするおすすめガジェット10選と価格帯

Go 1.20で始める本格RESTful API構築ガイド

1. 環境構築とプロジェクト初期化

1‑1. Go のインストール（最新版推奨）

1‑2. プロジェクトディレクトリと go.mod の作成

推奨ディレクトリ構造（Clean Architecture にヒント）

1‑3. 必要なライブラリを取得（バージョンは go.mod に任せる）

2. API 実装とルーティング設計

2‑1. エントリポイント (cmd/server/main.go)

2‑2. ルーティング定義 (internal/api/router.go)

2‑3. データ構造体と JSON タグ (internal/model/user.go)

2‑4. ハンドラ実装 (internal/api/handler.go)

2‑5. バリデーションロジック (internal/service/validation.go)

3. データベース連携とテスト戦略

3‑1. DB 接続ラッパー (internal/repository/mysql.go)

3‑2. リポジトリインターフェイスと実装

3‑3. サービス層でリポジトリを利用

3‑4. ユニットテストのベストプラクティス

ハンドラ単体テスト (internal/api/handler_test.go)

リポジトリ層テスト（SQL モックだけで完結）

4. Lint 設定と CI/CD パイプライン

4‑1. golangci-lint のインストール（バージョンは「最新版」）

4‑2. .golangci.yml（公式推奨リストをベースにカスタマイズ）

4‑3. GitHub Actions による自動化 (.github/workflows/ci.yml)

5. マルチステージ Docker と Cloud Run デプロイ

5‑1. Dockerfile（サイズ変動要因と目安）

イメージサイズに関する注意点

5‑2. ローカルビルド・テスト

5‑3. Docker イメージの CI ビルド・プッシュ（GitHub Actions）

5‑4. Cloud Run へのデプロイ手順

シークレット管理（Secret Manager 推奨）

6. 補足：本番運用に向けた追加ベストプラクティス

7. まとめ

1‑2. プロジェクトディレクトリと `go.mod` の作成

1‑3. 必要なライブラリを取得（バージョンは `go.mod` に任せる）

2‑1. エントリポイント (`cmd/server/main.go`)

2‑2. ルーティング定義 (`internal/api/router.go`)

2‑3. データ構造体と JSON タグ (`internal/model/user.go`)

2‑4. ハンドラ実装 (`internal/api/handler.go`)

2‑5. バリデーションロジック (`internal/service/validation.go`)

3‑1. DB 接続ラッパー (`internal/repository/mysql.go`)

ハンドラ単体テスト (`internal/api/handler_test.go`)

4‑1. `golangci-lint` のインストール（バージョンは「最新版」）

4‑2. `.golangci.yml`（公式推奨リストをベースにカスタマイズ）

4‑3. GitHub Actions による自動化 (`.github/workflows/ci.yml`)