エラーハンドリングの実装パターン
GS2 を使用したゲーム開発における、実践的なエラーハンドリングとリトライ戦略のベストプラクティス
エラー・例外
Game Server Services を利用する上で発生する一般的なエラー
GS2 が応答するエラーは一定の法則を持って応答されます。 法則を理解することで、エラーの解消が迅速に行えるようになります。
エラーメッセージの例
[{"component":"progress","message":"quest.progress.progress.error.notFound"}]| セクション | 説明 |
|---|---|
| component | エラーが発生した対象を示し、メンバー名、メソッド名が入ります。 |
| message | エラー箇所の詳細、エラーを表すキーワードが入ります。 サービス名.コンポーネント.error.エラー内容 |
主要なエラー内容
| 主要なエラー内容 | 説明 |
|---|---|
| failed | 処理に失敗しました。 |
| invalid | 不正なパラメータです。 |
| require | 必要な引数がありません。 |
| tooLong | 引数の文字数が長すぎます。 |
| tooMany | 配列の要素数が多すぎます。 |
| exists | 既に存在しています。 |
| duplicate | 重複、既に存在しています。 |
| notFound | 見つかりませんでした。 |
| notMatch | 合致しませんでした。 |
例外の種類
SDK によってエラーはある程度分類され、送出される例外の型が変化します。
すべての例外は Gs2Exception を継承しており、以下のプロパティを参照することでリトライの要否を判断できます。
- RecommendRetry: ユーザーに「リトライ」を促すボタンを表示するなど、手動リトライを検討すべきエラー。
- RecommendAutoRetry: ユーザーに通知せず、システム側で自動的にリトライしても安全なエラー。
| 例外 | エラー内容 | ステータスコード | RecommendRetry | RecommendAutoRetry |
|---|---|---|---|---|
| BadRequestException | リクエストの内容が不正です。 | 400 | ||
| UnauthorizedException | 権限の認証ができませんでした。 | 401 | ||
| QuotaLimitExceededException | クォータの制限を超えました。 | 402 | ✔︎ | |
| NotFoundException | 対象が見つかりませんでした。 | 404 | ||
| ConflictException | 処理が衝突しました。 | 409 | ✔︎ | |
| InternalServerErrorException | サーバーでエラーが発生しました。 | 500 | ✔︎ | ✔︎ |
| BadGatewayException | サーバーが無効なレスポンスを受け取りました。 | 502 | ✔︎ | ✔︎ |
| ServiceUnavailableException | サービスで一時的なエラーが発生しました。 | 503 | ✔︎ | ✔︎ |
| RequestTimeoutException | リクエストがタイムアウトしました。 | 504 | ✔︎ | ✔︎ |
| UnknownException | 不明な例外が発生しました。 |
RecommendRetry が true の例外は、リクエストパラメータは正常だが、サーバーの状態によって発生する可能性があるエラーです。
このようなエラーを検知した場合、リトライすることを推奨します。
その際に成功するまでリトライするのではなく、一定回数や一定時間の経過でタイムアウトする実装を入れることを強く推奨します。 リトライをする際に、リクエスト間にスリープを入れることを推奨しており、リトライ回数に応じてスリープの長さを伸ばしていくことを推奨します。
ゲーム内でハンドリングを必要とするエラーについては、マイクロサービスごとに列挙した例外を継承したエラー固有の例外型を定義しているものがあります。 その場合、エラー固有の例外でエラーハンドリングをすることでより簡単にエラーハンドリングを実装できます。 固有のエラーを表現する例外が存在する場合、APIリファレンスのメソッドの説明に記載がありますので、そちらをご参照ください。
クライアントで発生する例外の取得
GS2-CSharp-SDK、GS2 SDK for Unityでは、接続に使用しているゲームエンジン/フレームワークで発生したエラー内容のメッセージの取得が可能です。
| 例外 | エラー内容 | ステータスコード |
|---|---|---|
| NoInternetConnectionException | インターネットの接続に失敗しました。 ※端末が機内モード/圏外/ルータに繋がっているが外に出られない等で、ソケット確立や DNS 解決に失敗したときの 接続エラーを含みます。 | 0 |
| ConnectionException | (Unityのみ) サーバーとの通信に失敗しました。 リクエストが接続できなかった、セキュリティで保護されたチャネルを確立できなかったなど。 | 0 |
| DataProcessingException | (Unityのみ) データ処理中にエラーが発生しました。 | 0 |
| HttpRequestException | (.netのみ) HttpRequestでエラーが発生しました。 | 0 |
カオスモード
GS2 C# SDK および GS2 SDK for Unity にはカオスモードが搭載されています。 カオスモードを有効化すると、指定した割合でリトライが必要な例外をランダムに発します。
開発をカオスモードを有効にした状態で進めることで、ゲーム内のエラーハンドリングをより強固なものにすることができます。 カオスモードの有効化の方法は 初期化処理 を参照してください。
実装ガイド
より具体的な実装方法やベストプラクティスについては、エラーハンドリングの実装パターン を参照してください。