feat: Implement unified error handling system
- Added `errors.py` to define a centralized error management system with error codes and metadata. - Created `VRCTError` class for generating standardized error responses. - Introduced `error_handling_migration_guide.md` to document migration patterns for existing error handling to the new system. - Updated error handling patterns in the codebase to utilize the new error management system.
This commit is contained in:
misyaguziya
212
src-python/docs/error_handling_migration_guide.md
Normal file
212
src-python/docs/error_handling_migration_guide.md
Normal file
@@ -0,0 +1,212 @@
|
||||
# エラーハンドリング統一システム移行ガイド
|
||||
|
||||
## 概要
|
||||
|
||||
`errors.py`で定義された統一エラーシステムを使用して、すべてのエラーハンドリングを標準化しました。
|
||||
|
||||
## 変更パターン
|
||||
|
||||
### 1. 基本的なエラーレスポンス
|
||||
|
||||
#### 修正前:
|
||||
```python
|
||||
response = {
|
||||
"status": 400,
|
||||
"result": {
|
||||
"message": "Error message",
|
||||
"data": some_value
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 修正後:
|
||||
```python
|
||||
from errors import ErrorCode, VRCTError
|
||||
|
||||
response = VRCTError.create_error_response(
|
||||
ErrorCode.APPROPRIATE_ERROR_CODE,
|
||||
data=some_value
|
||||
)
|
||||
```
|
||||
|
||||
### 2. run_mapping経由のエラー通知
|
||||
|
||||
#### 修正前:
|
||||
```python
|
||||
self.run(
|
||||
400,
|
||||
self.run_mapping["error_device"],
|
||||
{
|
||||
"message": "No mic device detected",
|
||||
"data": None
|
||||
},
|
||||
)
|
||||
```
|
||||
|
||||
#### 修正後:
|
||||
```python
|
||||
error_response = VRCTError.create_error_response(
|
||||
ErrorCode.DEVICE_NO_MIC,
|
||||
data=None
|
||||
)
|
||||
self.run(
|
||||
error_response["status"],
|
||||
self.run_mapping["error_device"],
|
||||
error_response["result"],
|
||||
)
|
||||
```
|
||||
|
||||
### 3. 例外からのエラー生成
|
||||
|
||||
#### 修正前:
|
||||
```python
|
||||
except Exception as e:
|
||||
errorLogging()
|
||||
response = {
|
||||
"status": 400,
|
||||
"result": {
|
||||
"message": f"Error {e}",
|
||||
"data": original_value
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 修正後:
|
||||
```python
|
||||
except Exception as e:
|
||||
errorLogging()
|
||||
response = VRCTError.create_exception_error_response(
|
||||
e,
|
||||
data=original_value
|
||||
)
|
||||
```
|
||||
|
||||
## 既に移行済みの箇所
|
||||
|
||||
### デバイスエラー
|
||||
- ✅ `progressBarMicEnergy` - `ErrorCode.DEVICE_NO_MIC`
|
||||
- ✅ `progressBarSpeakerEnergy` - `ErrorCode.DEVICE_NO_SPEAKER`
|
||||
|
||||
### ウェイトダウンロードエラー
|
||||
- ✅ `DownloadCTranslate2.downloaded` - `ErrorCode.WEIGHT_CTRANSLATE2_DOWNLOAD`
|
||||
- ✅ `DownloadWhisper.downloaded` - `ErrorCode.WEIGHT_WHISPER_DOWNLOAD`
|
||||
|
||||
### 翻訳エラー
|
||||
- ✅ `micMessage` - `ErrorCode.TRANSLATION_ENGINE_LIMIT`, `ErrorCode.TRANSLATION_VRAM_MIC`, `ErrorCode.TRANSLATION_DISABLED_VRAM`
|
||||
- ✅ `speakerMessage` - `ErrorCode.TRANSLATION_ENGINE_LIMIT`, `ErrorCode.TRANSLATION_VRAM_SPEAKER`, `ErrorCode.TRANSLATION_DISABLED_VRAM`
|
||||
- ✅ `chatMessage` - `ErrorCode.TRANSLATION_ENGINE_LIMIT`, `ErrorCode.TRANSLATION_VRAM_CHAT`, `ErrorCode.TRANSLATION_DISABLED_VRAM`
|
||||
- ✅ `setEnableTranslation` - `ErrorCode.TRANSLATION_VRAM_ENABLE`, `ErrorCode.TRANSLATION_DISABLED_VRAM`
|
||||
|
||||
### バリデーションエラー
|
||||
- ✅ `setMicThreshold` - `ErrorCode.VALIDATION_MIC_THRESHOLD`
|
||||
- ✅ `setSpeakerThreshold` - `ErrorCode.VALIDATION_SPEAKER_THRESHOLD`
|
||||
- ✅ `setMicRecordTimeout` - `ErrorCode.VALIDATION_MIC_RECORD_TIMEOUT`
|
||||
- ✅ `setMicPhraseTimeout` - `ErrorCode.VALIDATION_MIC_PHRASE_TIMEOUT`
|
||||
- ✅ `setMicMaxPhrases` - `ErrorCode.VALIDATION_MIC_MAX_PHRASES`
|
||||
- ✅ `setSpeakerRecordTimeout` - `ErrorCode.VALIDATION_SPEAKER_RECORD_TIMEOUT`
|
||||
- ✅ `setSpeakerPhraseTimeout` - `ErrorCode.VALIDATION_SPEAKER_PHRASE_TIMEOUT`
|
||||
- ✅ `setSpeakerMaxPhrases` - `ErrorCode.VALIDATION_SPEAKER_MAX_PHRASES`
|
||||
- ✅ `setOscIpAddress` - `ErrorCode.VALIDATION_INVALID_IP`, `ErrorCode.VALIDATION_CANNOT_SET_IP`
|
||||
|
||||
### VRC連携エラー
|
||||
- ✅ `setEnableVrcMicMuteSync` - `ErrorCode.VRC_MIC_MUTE_SYNC_OSC_DISABLED`
|
||||
|
||||
### 認証エラー
|
||||
- ✅ `setDeeplAuthKey` - `ErrorCode.AUTH_DEEPL_LENGTH`, `ErrorCode.AUTH_DEEPL_FAILED`
|
||||
|
||||
## 未移行の箇所（要対応）
|
||||
|
||||
以下の箇所は同様のパターンで移行が必要です:
|
||||
|
||||
### 認証関連
|
||||
- ⬜ `setPlamoAuthKey` - `ErrorCode.AUTH_PLAMO_LENGTH`, `ErrorCode.AUTH_PLAMO_FAILED`
|
||||
- ⬜ `setPlamoModel` - `ErrorCode.MODEL_PLAMO_INVALID`
|
||||
- ⬜ `setGeminiAuthKey` - `ErrorCode.AUTH_GEMINI_LENGTH`, `ErrorCode.AUTH_GEMINI_FAILED`
|
||||
- ⬜ `setGeminiModel` - `ErrorCode.MODEL_GEMINI_INVALID`
|
||||
- ⬜ `setOpenAIAuthKey` - `ErrorCode.AUTH_OPENAI_INVALID`, `ErrorCode.AUTH_OPENAI_FAILED`
|
||||
- ⬜ `setOpenAIModel` - `ErrorCode.MODEL_OPENAI_INVALID`
|
||||
- ⬜ `setGroqAuthKey` - `ErrorCode.AUTH_GROQ_INVALID`, `ErrorCode.AUTH_GROQ_FAILED`
|
||||
- ⬜ `setGroqModel` - `ErrorCode.MODEL_GROQ_INVALID`
|
||||
- ⬜ `setOpenRouterAuthKey` - `ErrorCode.AUTH_OPENROUTER_INVALID`, `ErrorCode.AUTH_OPENROUTER_FAILED`
|
||||
- ⬜ `setOpenRouterModel` - `ErrorCode.MODEL_OPENROUTER_INVALID`
|
||||
|
||||
### 接続関連
|
||||
- ⬜ `checkTranslatorLMStudioConnection` - `ErrorCode.CONNECTION_LMSTUDIO_FAILED`
|
||||
- ⬜ `setTranslatorLMStudioURL` - `ErrorCode.CONNECTION_LMSTUDIO_URL_INVALID`
|
||||
- ⬜ `setTranslatorLMStudioModel` - `ErrorCode.MODEL_LMSTUDIO_INVALID`
|
||||
- ⬜ `checkTranslatorOllamaConnection` - `ErrorCode.CONNECTION_OLLAMA_FAILED`
|
||||
- ⬜ `setTranslatorOllamaModel` - `ErrorCode.MODEL_OLLAMA_INVALID`
|
||||
|
||||
### WebSocket関連
|
||||
- ⬜ `setWebSocketHost` - `ErrorCode.VALIDATION_INVALID_IP`, `ErrorCode.WEBSOCKET_HOST_INVALID`
|
||||
- ⬜ `setWebSocketPort` - `ErrorCode.WEBSOCKET_PORT_UNAVAILABLE`
|
||||
- ⬜ `setEnableWebSocketServer` - `ErrorCode.WEBSOCKET_SERVER_UNAVAILABLE`
|
||||
|
||||
### 音声認識VRAM関連
|
||||
- ⬜ `startTranscriptionSendMessage` - `ErrorCode.TRANSCRIPTION_VRAM_MIC`, `ErrorCode.TRANSCRIPTION_SEND_DISABLED_VRAM`
|
||||
- ⬜ `startTranscriptionReceiveMessage` - `ErrorCode.TRANSCRIPTION_VRAM_SPEAKER`, `ErrorCode.TRANSCRIPTION_RECEIVE_DISABLED_VRAM`
|
||||
|
||||
## エラーコードとエンドポイントの対応
|
||||
|
||||
`errors.py`の`ENDPOINT_ERROR_MAPPING`に、すべてのエンドポイントとエラーコードの対応が定義されています。
|
||||
UI開発者はこのマッピングを参照して、各エンドポイントがどのようなエラーを返すか確認できます。
|
||||
|
||||
## エラーレスポンスの構造
|
||||
|
||||
統一されたエラーレスポンスは以下の構造を持ちます:
|
||||
|
||||
```python
|
||||
{
|
||||
"status": 400, # HTTPステータスコード
|
||||
"result": {
|
||||
"error_code": "ERROR_CODE_CONSTANT", # エラーコード定数
|
||||
"message": "Human readable message", # 人間が読めるメッセージ
|
||||
"data": None or original_value, # エラー時に戻す値（通常は元の値）
|
||||
"details": {}, # 追加情報（オプション）
|
||||
"category": "category_name", # エラーカテゴリ
|
||||
"severity": "warning|error|critical", # 重要度
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## UI側での活用
|
||||
|
||||
UI側では`error_code`を使用して、エラーの種類を判定し、適切な処理を行うことができます:
|
||||
|
||||
```javascript
|
||||
if (response.status === 400) {
|
||||
const { error_code, message, data, severity } = response.result;
|
||||
|
||||
switch (error_code) {
|
||||
case "DEVICE_NO_MIC":
|
||||
// マイクデバイスエラーの処理
|
||||
break;
|
||||
case "VALIDATION_MIC_THRESHOLD":
|
||||
// バリデーションエラーの処理（元の値に戻す）
|
||||
setValue(data);
|
||||
break;
|
||||
// ...
|
||||
}
|
||||
|
||||
// 重要度に応じた表示
|
||||
if (severity === "critical") {
|
||||
showCriticalError(message);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 移行作業の進め方
|
||||
|
||||
1. **パターンの確認**: 上記の変更パターンを参照
|
||||
2. **エラーコードの特定**: `errors.py`から適切な`ErrorCode`を選択
|
||||
3. **コードの置き換え**: 古いエラーハンドリングを新しいシステムに置き換え
|
||||
4. **テスト**: エラーが正しく返されることを確認
|
||||
5. **チェックリストの更新**: このドキュメントの✅を更新
|
||||
|
||||
## 注意事項
|
||||
|
||||
- すべてのエラーは`errors.py`に定義されたエラーコードを使用すること
|
||||
- 新しいエラーが必要な場合は、まず`errors.py`に追加すること
|
||||
- エラーメッセージは`ERROR_METADATA`で定義されたデフォルトメッセージを使用すること
|
||||
- カスタムメッセージが必要な場合は`custom_message`パラメータを使用
|
||||
- `data`パラメータには、エラー時にUIが元の値に戻せるように、元の値を渡すこと
|
||||
Reference in New Issue
Block a user