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

Last updated on July 14, 2026

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

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

プロジェクト構造​

src/
└── main/
    ├── java/
    │   └── com/accelbyte/extend/serviceextension/
    │       ├── Application.java            # エントリーポイント
    │       ├── service/
    │       │   └── MyService.java          # ビジネスロジック
    │       ├── interceptor/
    │       │   └── AuthServerInterceptor.java  # IAM トークンと権限の検証
    │       └── ...
    └── proto/
        └── service.proto                   # gRPC API の定義
ファイル機能
Application.javaエントリーポイント — gRPC サーバー、gRPC-Gateway、メトリクス、認証を結び付けます。
service/MyService.javaビジネスロジック — gRPC サービスメソッドを実装します。
interceptor/AuthServerInterceptor.javaすべての受信リクエストの IAM トークンと権限を検証します。
proto/service.protogRPC API を定義します — エンドポイント、リクエスト/レスポンスの形式、必要な権限。

ポート番号:

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

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

ターミナルから​

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

./gradlew bootRun

VS Code から​

Terminal → Run Task → "Run: Service" を使用します。 このタスクは .vscode/tasks.json で定義されており、.env ファイルを自動的に読み込みます。

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

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

{"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": "java",
  "request": "launch",
  "mainClass": "com.accelbyte.extend.serviceextension.Application",
  "envFile": "${workspaceFolder}/.env",
  "cwd": "${workspaceFolder}"
}

汎用ガイドのデバッガーの接続の手順に従い、ドロップダウンから "Debug: Service" を選択します。

その他の IDE — JVM リモートデバッグ​

デフォルトでポート 5005 でリスンする JVM デバッグエージェントを使用してアプリを起動します。

export $(grep -v '^#' .env | xargs)
./gradlew bootRun --debug-jvm

次に IDE（IntelliJ IDEA、Eclipse）を開き、localhost:5005 を対象とする Remote JVM Debug 設定を作成します。

ブレークポイントの設置場所​

調査したいことファイルと場所
呼び出されている特定の REST エンドポイントservice/MyService.java — 該当メソッドの先頭
認証/トークン検証の失敗interceptor/AuthServerInterceptor.java — interceptCall メソッド
データが正しく保存・読み込みされないサービスで使用しているリポジトリまたはストレージクラス
サービスがまったく起動しないApplication.java — main メソッドと Bean 初期化処理

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

ログの読み方​

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

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

curl および grpcurl の使い方については、汎用ガイドの grpcurl でのテストを参照してください。

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

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

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

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

原因: 生成された gRPC スタブが再ビルドされていません。

対処法: protobuf の Gradle プラグインを実行するために、クリーンビルドを実行します。

./gradlew clean build

Gradle デーモンの問題​

サービスの動作が実行ごとに一貫しない場合は、Gradle デーモンを停止して再試行してください。

./gradlew --stop
./gradlew bootRun

リモートデバッグ用の JVM ポート競合​

Java 言語ガイドのリモートデバッグ用の JVM ポート競合を参照してください。

ポート競合の確認（サービスポート）​

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

AI アシスタンス​

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

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

参考資料​

に最終更新
On this page