Dev Docs

Appearance

開発ガイド ​

Blog Service のローカル開発環境構築とマイグレーション手順を説明します。

前提条件 ​

必要なソフトウェア ​

ソフトウェアバージョン用途
Go1.21+アプリケーション実行
Docker20.0+データベース、開発環境
Docker Compose2.0+複数コンテナ管理
Make-ビルド・テスト自動化

推奨ツール ​

ツール説明
golangci-lintGoコード品質チェック
atlasデータベースマイグレーション
wire依存性注入コード生成

環境構築 ​

1. リポジトリのクローン ​

bash
git clone <repository-url>
cd portfolio/apps/blog-service

2. 依存関係のインストール ​

bash
# Goモジュールの依存関係をダウンロード
go mod download

# 開発ツールのインストール
go install github.com/google/wire/cmd/wire@latest
go install ariga.io/atlas/cmd/atlas@latest

3. 環境変数の設定 ​

環境変数ファイルを作成：

bash
# .env.local ファイルを作成（例）
cat <<EOF > .env.local
DB_HOST=localhost
DB_PORT=3306
DB_NAME=dev
DB_USER=root
DB_PASSWORD=password
JWT_SECRET=your-jwt-secret-key
LOG_LEVEL=debug
EOF

ローカル開発 ​

開発環境の起動 ​

bash
# データベースとサービスを起動
make run

# または個別に起動
docker compose up -d
make atlas-apply-dev

このコマンドにより以下が実行されます：

  1. MySQL 8.0 コンテナの起動
  2. データベースマイグレーションの実行
  3. アプリケーションの起動（開発モード）

アプリケーションの起動確認 ​

bash
# ヘルスチェック
curl http://localhost:8080/blog-service/v1/health

# 期待するレスポンス
# {"apiVersion":"1.0.0"}

ホットリロード開発 ​

bash
# air などのホットリロードツールを使用
go install github.com/cosmtrek/air@latest
air

データベース管理 ​

マイグレーション ​

新しいマイグレーションの作成 ​

bash
# 新しいマイグレーションファイルを生成
make atlas-diff name=add_new_table

マイグレーション状態の確認 ​

bash
# 現在のマイグレーション状態を確認
make atlas-status-dev

マイグレーションの適用 ​

bash
# 最新のマイグレーションを適用
make atlas-apply-dev

マイグレーションのロールバック ​

bash
# 一つ前のマイグレーションに戻す
make atlas-down-dev

データベーススキーマの確認 ​

bash
# 現在のスキーマ構造を表示
make atlas-inspect

コード生成 ​

ent ORM コード生成 ​

bash
# entスキーマファイルの確認
make ent-describe

# entコードの生成
make ent-generate

新しいエンティティの追加 ​

bash
# 新しいentスキーマを作成
make ent-new name=Comment

# 生成されたファイルを編集後、コード生成
make ent-generate

Wire 依存性注入コード生成 ​

bash
# Wire設定からDIコードを生成
make wire-gen

OpenAPI クライアント生成 ​

bash
# OpenAPI定義からGoクライアントコードを生成
make api-gen

モックコード生成 ​

bash
# テスト用のモックコードを生成
make mock-gen

テスト ​

テストの実行 ​

bash
# 全テストの実行
make check

# または個別に実行
go test ./...

# カバレッジ付きでテスト実行
go test -cover ./...

# 特定のパッケージのテスト
go test ./internal/usecase/article/...

テストファイルの構成 ​

internal/
├── usecase/
│   └── article/
│       ├── create.go
│       ├── create_test.go      # ユニットテスト
│       └── list_test.go
└── infrastructure/
    └── mysql/
        └── repository/
            ├── article.go
            └── article_test.go   # 統合テスト

テストデータベース ​

統合テストでは専用のテストDBを使用：

bash
# テスト用DBの起動
docker compose -f docker-compose.test.yml up -d

# テスト実行（環境変数でテストDB指定）
TEST_DB_URL="mysql://root:password@localhost:3307/test" go test ./...

コード品質 ​

静的解析 ​

bash
# golangci-lint による静的解析
golangci-lint run ./...

# フォーマット
go fmt ./...

# vet チェック
go vet ./...

推奨する開発フロー ​

  1. 機能ブランチの作成

    bash
    git checkout -b feature/add-comment-api

  2. コード変更と自動生成

    bash
    # コード変更後、必要に応じて自動生成
make ent-generate
make wire-gen
make mock-gen

  3. テスト実行

    bash
    make check

  4. プルリクエスト作成前チェック

    bash
    # 全チェックを実行
make check
git add .
git commit -m "feat: add comment API"

よく使うMakeコマンド一覧 ​

コマンド説明
make run開発環境の起動（DB + Migration）
make checkコード品質チェック（fmt, vet, test, lint）
make ent-generateent ORM コード生成
make wire-genWire DI コード生成
make mock-genモックコード生成
make api-genOpenAPI クライアントコード生成
make atlas-apply-devマイグレーション適用
make atlas-status-devマイグレーション状態確認
make atlas-diff name=<name>新規マイグレーション作成

開発Tips ​

VS Code 設定 ​

.vscode/settings.json の推奨設定：

json
{
  "go.lintTool": "golangci-lint",
  "go.lintFlags": ["--fast"],
  "go.testFlags": ["-v"],
  "go.buildFlags": ["-v"],
  "files.watcherExclude": {
    "**/vendor/**": true
  }
}

デバッグ設定 ​

.vscode/launch.json:

json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Launch Blog Service",
      "type": "go",
      "request": "launch",
      "mode": "auto",
      "program": "${workspaceFolder}/cmd/server",
      "env": {
        "DB_URL": "mysql://root:password@localhost:3306/dev"
      }
    }
  ]
}

パフォーマンス計測 ​

bash
# プロファイリング
go tool pprof http://localhost:8080/debug/pprof/profile

# メモリ使用量
go tool pprof http://localhost:8080/debug/pprof/heap

トラブルシューティング ​

一般的な問題は トラブルシューティング を参照してください。