Local Debugging Guide for Extend Override — Go

Last updated on July 14, 2026

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

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

このガイドの例では、matchmaking の使用例（matchmaking-function-grpc-plugin-server-go）を使用しています。プロジェクト構造とデバッグ手順は、他のすべての Override 使用例でも同じです。異なるのはサービスファイルと proto のみです。このガイドの最後にある サービスファイル参照テーブルを参照してください。

プロジェクト構造​

matchmaking-function-grpc-plugin-server-go/
├── main.go                              # エントリポイント — gRPC サーバー、認証、メトリクス、トレーシング
├── proto.sh                             # protobuf バインディングを再生成
├── .env.template                        # 環境変数テンプレート
├── .vscode/
│   ├── launch.json                      # VS Code デバッグ設定
│   └── tasks.json                       # VS Code タスク（Run、Proto: Generate など）
├── pkg/
│   ├── server/
│   │   ├── matchFunctionService.go      # MatchFunctionServer — Override ロジック
│   │   ├── matchmaker.go               # MatchMaker — コアのマッチロジック
│   │   ├── gameRules.go                # ルールの解析と検証
│   │   └── interfaces.go               # MatchLogic インターフェース
│   ├── common/
│   │   ├── authServerInterceptor.go    # IAM トークン検証インターセプター
│   │   ├── logging.go                  # gRPC ミドルウェア → slog ブリッジ
│   │   └── tracerProvider.go           # OpenTelemetry トレーシング設定
│   ├── pb/
│   │   ├── matchFunction.pb.go         # 生成された protobuf 型（編集しないこと）
│   │   └── matchFunction_grpc.pb.go    # 生成された gRPC サービスコード（編集しないこと）
│   └── proto/
│       └── matchFunction.proto         # protobuf 定義
└── demo/
    └── *.postman_collection.json        # 手動テスト用の Postman コレクション

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

ポート用途
6565gRPC サーバー — AGS からの呼び出しを受信
8080Prometheus メトリクスエンドポイント（/metrics）

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

ターミナルから​

# .env ファイルからすべての変数をエクスポート
export $(grep -v '^#' .env | xargs)

go run main.go

VS Code から​

Terminal → Run Task → "Run: Service" を使用します。このタスクは .vscode/tasks.json で定義されています。

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

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

{"time":"...","level":"INFO","msg":"starting app server"}
{"time":"...","level":"INFO","msg":"gRPC reflection enabled"}
{"time":"...","level":"INFO","msg":"gRPC server listening","address":"[::]:6565"}
{"time":"...","level":"INFO","msg":"prometheus metrics served at :8080/metrics"}

gRPC reflection に到達可能であることを確認します。

grpcurl -plaintext localhost:6565 list

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

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 にアタッチするように設定します。

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

調査したい内容ファイルと場所
呼び出されている特定の gRPC メソッドpkg/server/matchFunctionService.go — 該当メソッドの先頭
マッチロジックの結果pkg/server/matchmaker.go — MakeMatches チャネルループ
ルールの解析pkg/server/gameRules.go — RulesFromJSON
認証／トークン検証の失敗pkg/common/authServerInterceptor.go — インターセプターの入口
サービスが全く起動しないmain.go — os.Exit(1) 呼び出しの直前

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

ログを読む​

このサービスは Go の slog を使用して構造化 JSON ログを出力します。jq によるログフィルタリングについては、 Go 言語ガイドを参照してください。

サービス実行中にエラーのみをストリーミングするには、次のようにします。

go run main.go 2>&1 | jq 'select(.level == "ERROR")'

Override を手動でテストする​

grpcurl の使用方法については、Override メインガイドの Override を手動でテストするを参照してください。

demo/ ディレクトリには、事前に構築されたリクエストを含む Postman コレクション（*.postman_collection.json）があります。これを Postman にインポートし、ローカル環境用に baseUrl と token を更新してください。

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

Proto を変更しても反映されない​

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

原因: pkg/pb/ 内の生成されたスタブが再生成されていません。

対処法: "Proto: Generate" の VS Code タスクを実行するか、次を実行します。

./proto.sh

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

go run とデバッガー起動設定の違い​

go run main.go はデバッグ情報なしでコンパイルされます。ブレークポイントを発火させたい場合は、常に go run ではなく VS Code の起動設定（または dlv debug）を使用してください。

PLUGIN_GRPC_SERVER_AUTH_ENABLED — 認証がすべての呼び出しを拒否する​

症状: ローカルでテストすると、すべての gRPC 呼び出しが unauthenticated を返す。

対処法: .env ファイルに PLUGIN_GRPC_SERVER_AUTH_ENABLED=false を追加します。これにより IAM インターセプターが無効になり、有効なトークンなしでテストできるようになります。デプロイ前に必ず再度有効にすることを忘れないでください。

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

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

AI アシスタンス​

アプリテンプレートには、.claude/skills/debugging-guide/SKILL.md に Claude エージェントスキルが同梱されています。 このスキルは、各 Override 使用例のテンプレートリポジトリで利用できます（リポジトリを参照）。

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

使用例別のサービスファイル参照​

上記のデバッグワークフローは、すべての Override 使用例に適用されます。異なるのはサービスファイルと proto のみです。実装ファイルを見つけるには、次の表を使用してください。

使用例Go サービスファイルProto ファイル
Matchmakingpkg/server/matchFunctionService.gopkg/proto/matchFunction.proto
Cloud Save Validatorリポジトリの README を参照リポジトリの README を参照
Lootbox Rollリポジトリの README を参照リポジトリの README を参照
Profanity Filterリポジトリの README を参照リポジトリの README を参照
Revocationリポジトリの README を参照リポジトリの README を参照
Rotating Shop Itemsリポジトリの README を参照リポジトリの README を参照
Session DSMリポジトリの README を参照リポジトリの README を参照
Session Managerリポジトリの README を参照リポジトリの README を参照
Challenge Assignmentリポジトリの README を参照リポジトリの README を参照

各使用例と言語のリポジトリへのリンクについては、 Extend Override リポジトリを参照してください。

リファレンス​

に最終更新
On this page