ローカルデバッグガイド — Go

Last updated on July 14, 2026

注釈：本資料はAI技術を用いて翻訳されています。

このガイドでは、Go で作成された Extend Service Extension アプリに固有のデバッグ内容を説明します。環境セットアップ、VS Code のデバッグワークフロー、ログの読み方、一般的な問題といった共通のデバッグ概念については、以下を参照してください。

プロジェクト構造​

ファイル / パッケージ内容
main.goエントリーポイント — gRPC サーバー、gRPC-Gateway、メトリクス、トレーシング、認証を組み合わせます。
pkg/service/myService.goあなたのビジネスロジック — gRPC サービスのメソッドを実装します。
pkg/storage/storage.goAccelByte CloudSave と通信してデータを永続化・取得します。
pkg/common/authServerInterceptor.go受信するすべてのリクエストの IAM トークンと権限を検証します。
pkg/common/logging.gogRPC ミドルウェアのロガーを Go の slog に橋渡しします。
pkg/common/tracerProvider.goOpenTelemetry の分散トレーシング（Zipkin エクスポーター）を設定します。
pkg/proto/service.protogRPC API を定義します — エンドポイント、リクエスト/レスポンスの形式、必要な権限。
pkg/pb/.proto から自動生成された Go コードです。直接編集しないでください。

ポート番号（main.go 内の定数）:

ポート用途
6565gRPC サーバー（内部用 — gRPC-Gateway が使用）
8000gRPC-Gateway HTTP/REST — ブラウザ、Postman、または curl からこのポートを呼び出します
8080Prometheus メトリクスエンドポイント（/metrics）

サービスをローカルで実行する​

ターミナルから​

# Export all variables from your .env file
export $(grep -v '^#' .env | xargs)

go run main.go

VS Code から​

Terminal → Run Task → "Run: Service" を使用します。 このタスクは .vscode/tasks.json で定義されており、BASE_PATH が未設定の場合はその入力を求められます。

サービスが起動していることを確認する​

以下のようなログが表示されるはずです。

{"time":"...","level":"INFO","msg":"app server started","service":"extend-app-service-extension"}
{"time":"...","level":"INFO","msg":"starting gRPC-Gateway HTTP server","port":8000}
{"time":"...","level":"INFO","msg":"serving prometheus metrics","port":8080,"endpoint":"/metrics"}

ブラウザで http://localhost:8000<BASE_PATH>/apidocs/ を開き、Swagger UI が起動していることを確認してください。

デバッガーをアタッチする​

VS Code（推奨）​

このリポジトリには、.vscode/launch.json にすぐに使える起動構成が同梱されています。

{
  "name": "Debug: Service",
  "type": "go",
  "request": "launch",
  "mode": "auto",
  "program": "${workspaceFolder}",
  "envFile": "${workspaceFolder}/.env",
  "cwd": "${workspaceFolder}",
  "console": "integratedTerminal"
}

汎用ガイドのデバッガーをアタッチするの手順に従い、 ドロップダウンから "Debug: Service" を選択してください。

その他の IDE — Delve のヘッドレスモード​

IDE から接続できるように、Delve をヘッドレスモードで起動します。

dlv debug --headless --listen=:2345 --api-version=2 .

続いて、IDE を DAP（Debug Adapter Protocol）経由で localhost:2345 にアタッチするよう設定します。

ブレークポイントを設置する場所​

調査したい内容ファイルと場所
呼び出されている特定の REST エンドポイントpkg/service/myService.go — 該当メソッドの先頭
認証/トークン検証の失敗pkg/common/authServerInterceptor.go — NewUnaryAuthServerIntercept
データが正しく保存・読み込みされないpkg/storage/storage.go — SaveGuildProgress / GetGuildProgress
サービスがまったく起動しないmain.go — os.Exit(1) 呼び出しの直前

条件付きブレークポイントの構文については、 Go 言語ガイドを参照してください。

ログを読む​

jq によるログのフィルタリングについては、 Go 言語ガイドを参照してください。

エンドポイントを手動でテストする​

curl と grpcurl の使い方については、汎用ガイドの grpcurl を使ったテストを参照してください。

Swagger UI を使ったテスト（SE 特有）については、SE のメインガイドの エンドポイントを手動でテストするを参照してください。

Go 特有のトラブルシューティング​

Proto の変更が反映されない​

症状: pkg/proto/service.proto を編集したが、実行時に何も変わらない。

原因: pkg/pb/ にある生成済みスタブが再生成されていません。

解決方法: "Proto: Generate" の VS Code タスクを実行するか、次のコマンドを実行します。

./proto.sh

その後、サービスを再起動してください。

go run とデバッガーの起動構成の違い​

go run main.go はデバッグ情報を含めずにコンパイルします。デバッガーをアタッチする必要がある場合は、常に go run ではなく VS Code の起動構成（または dlv debug）を使用してください。

ポートの競合を確認する​

Go 言語ガイドのポートの競合を確認する を参照してください。

AI アシスタンス​

アプリテンプレートには、 .claude/skills/debugging-guide/SKILL.md にある Claude エージェントスキルが同梱されています。

AI プロンプトのヒントや MCP サーバーの詳細については、汎用ガイドの AI アシスタンスによるデバッグを参照してください。

参考資料​

に最終更新
On this page