Local Debugging Guide for Extend Override — Java

Last updated on July 14, 2026

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

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

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

プロジェクト構造​

matchmaking-function-grpc-plugin-server-java/
├── build.gradle                         # Gradle build — includes protobuf plugin
├── gradlew                              # Gradle wrapper
├── .env.template                        # Environment variable template
└── src/main/
    ├── java/net/accelbyte/matchmaking/function/grpc/server/
    │   ├── App.java                     # Entry point — gRPC server, auth, observability
    │   ├── MatchmakingFunctionService.java  # Your override logic
    │   ├── GameRules.java               # Rules parsing (POJO)
    │   ├── AllianceRule.java            # Alliance rule model
    │   ├── config/
    │   │   └── AppConfiguration.java   # Spring Boot configuration
    │   └── interceptor/
    │       ├── AuthInterceptor.java     # IAM token validation interceptor
    │       └── LoggingInterceptor.java  # Request/response logging interceptor
    ├── proto/
    │   └── matchFunction.proto          # Protobuf definition
    └── resources/
        ├── application.yml              # Server config, auth toggle
        └── logback-spring.xml           # Logging configuration
ファイル機能
App.javaエントリポイント — gRPC サーバーを起動し、auth インターセプターと可観測性スタックを組み込みます。
MatchmakingFunctionService.javaオーバーライドロジック — MatchFunctionGrpc.MatchFunctionImplBase を拡張し、getStatCodes、validateTicket、enrichTicket、makeMatches、backfillMatches を実装します。
interceptor/AuthInterceptor.java受信するすべての gRPC 呼び出しの IAM トークンを検証します。
src/main/proto/matchFunction.protoProtobuf 定義 — サービスメソッドの信頼できる情報源です。
src/main/resources/application.ymlauth トグルを含むサーバー設定です。

ポート番号:

ポート用途
6565gRPC サーバー — AGS からの呼び出しを受信します
8080Prometheus メトリクスエンドポイント（/metrics）
Java では認証がデフォルトで無効です

application.yml では、PLUGIN_GRPC_SERVER_AUTH_ENABLED はデフォルトで false （${PLUGIN_GRPC_SERVER_AUTH_ENABLED:false}）です。これは Go、Python、C# のリポジトリと 反対で、それらはデフォルトで true になっています。どちらの方向でも予期しない動作を避けるため、 必ず .env で明示的に設定してください。

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

ターミナルから実行する​

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

./gradlew bootRun

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

以下のような Spring Boot と gRPC の起動ログが表示されるはずです。

INFO  net.accelbyte.matchmaking.function.grpc.server.App - Starting App
INFO  o.l.springboot.grpc.GRpcServerRunner - Starting gRPC Server ...
INFO  o.l.springboot.grpc.GRpcServerRunner - gRPC Server started, listening on port 6565
INFO  o.s.b.w.embedded.tomcat.TomcatWebServer - Tomcat started on port(s): 8080

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

grpcurl -plaintext localhost:6565 list
VS Code タスクはありません

Java の Override リポジトリには .vscode/tasks.json は同梱されていません。ターミナルから ./gradlew bootRun を使用するか、ワークフローに合わせて VS Code タスクを手動で設定してください。

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

JVM リモートデバッグ（推奨）​

Java リポジトリには .vscode/launch.json は同梱されていません。代わりに Gradle の 組み込み JVM デバッグサポートを使用します。

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

これによりアプリケーションが起動し、ポート 5005 でデバッガーが接続するまで待機（サスペンド）します。

次に、以下の起動設定を VS Code の .vscode/launch.json に追加します（ファイルが存在しない場合は 作成してください）。

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach: JVM (5005)",
      "type": "java",
      "request": "attach",
      "hostName": "localhost",
      "port": 5005
    }
  ]
}

接続するには、Run and Debug のドロップダウンから "Attach: JVM (5005)" を選択します。

IntelliJ IDEA / Eclipse​

localhost:5005 を対象とする Remote JVM Debug 設定を作成します。ターミナルで ./gradlew bootRun --debug-jvm を実行し、IDE からアタッチします。

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

調査したい内容ファイルと場所
呼び出される特定の gRPC メソッドMatchmakingFunctionService.java — 対象メソッドの先頭
ストリーミングチケット処理MatchmakingFunctionService.java — makeMatches の StreamObserver.onNext 内
ルールのパースMatchmakingFunctionService.java — gson.fromJson(rules.getJson(), GameRules.class)
認証／トークン検証の失敗interceptor/AuthInterceptor.java — interceptCall メソッド
サービスが全く起動しないApp.java — main メソッドと Spring コンテキストの初期化

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

ログを読む​

サービスは、logback-spring.xml で構成された構造化ログ出力を持つ Logback を使用しています。 jq によるログのフィルタリングについては、 Java 言語ガイドを参照してください。

サービスの実行中に error レベルの出力のみをストリームするには、以下を実行します。

./gradlew bootRun 2>&1 | grep ERROR

Override を手動でテストする​

grpcurl の使用方法とオーバーライドされた AGS 機能のトリガーについては、Override メインガイドの Override を手動でテストするを参照してください。

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

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

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

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

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

対処方法:

./gradlew generateProto

または、再生成を確実にするためにフルクリーンビルドを実行します。

./gradlew clean build

PLUGIN_GRPC_SERVER_AUTH_ENABLED がデフォルトで false になる​

症状: 明示的に無効化していないにもかかわらず、認証が無効になっているように見える。

原因: application.yml の PLUGIN_GRPC_SERVER_AUTH_ENABLED のデフォルト値は false です （デフォルトで true になる Go、Python、C# とは異なります）。

対処方法: 認証を有効にしたい場合は .env で PLUGIN_GRPC_SERVER_AUTH_ENABLED=true を明示的に 設定してください。あるいは、ローカル開発セッションで false が正しい設定であることを確認してください。

Gradle デーモンの問題​

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

./gradlew --stop
./gradlew bootRun

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

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

AI アシスタンス​

各 Override 使用例のアプリテンプレートには、.claude/skills/debugging-guide/SKILL.md に Claude エージェントスキルが同梱されています。AI プロンプトのヒントと MCP サーバーの詳細については、 Override メインガイドの AI アシスタンスによるデバッグを参照してください。

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

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

使用例Java サービスファイルProto ファイル
Matchmaking…/grpc/server/MatchmakingFunctionService.javasrc/main/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