- ユーザー向けエラーメッセージ生成は「技術的なエラーを“人が理解できる言葉”に翻訳するための必須技術」
- ユーザー向けエラーメッセージの目的は「状況を正しく伝え、行動を促すこと」
- ステップ1：エラーコードを定義する（内部識別用）
- ステップ2：ユーザー向けメッセージ辞書を作る（翻訳テーブル）
- ステップ3：内部エラー（AppError）を作る
- ステップ4：ユーザー向けメッセージを生成する関数を作る（最重要）
- ステップ5：内部ログとユーザー向けメッセージを分離する
- ステップ6：UI に表示するテンプレートを作る
- ステップ7：業務で使えるユーザー向けエラーメッセージ生成ユーティリティ（完成版）
- ステップ8：業務での活用例
- 深掘り：ユーザー向けエラーメッセージが重要な理由
- まとめ：ユーザー向けエラーメッセージ生成は「技術とユーザー体験をつなぐ翻訳技術」
ユーザー向けエラーメッセージ生成は「技術的なエラーを“人が理解できる言葉”に翻訳するための必須技術」
業務システムでは、内部で発生したエラーをそのままユーザーに見せることはできません。 理由は明確で、技術的なエラーメッセージは次のような問題を引き起こすからです。
- 「意味が分からない」ためユーザーが混乱する
- 内部情報が漏洩しセキュリティリスクになる
- 不安を与え、ユーザー体験が悪化する
- 問い合わせが増え、サポートコストが上がる
そのため、内部エラー（Errorオブジェクト）と ユーザー向けエラーメッセージは 別物として設計する必要があります。
ここでは、初心者でも理解しやすいように、 エラーコード → 内部エラー → ユーザー向けメッセージ という流れでステップバイステップで解説します。
ユーザー向けエラーメッセージの目的は「状況を正しく伝え、行動を促すこと」
ユーザー向けメッセージは次の3要素で構成されます。
- 何が起きたか（状況）
- なぜ起きたか（原因）※必要なら
- どうすればいいか（次の行動）
例：
「通信エラーが発生しました。時間をおいて再度お試しください。」
これは内部的には API-002: Timeout のようなエラーですが、 ユーザーには技術的な情報を隠し、行動を促す形に変換しています。
ステップ1：エラーコードを定義する（内部識別用）
export const ErrorCodes = {
API_TIMEOUT: "API-002",
API_INVALID_RESPONSE: "API-001",
AUTH_TOKEN_EXPIRED: "AUTH-001",
VALID_REQUIRED: "VALID-001",
SYS_UNKNOWN: "SYS-001",
};
ステップ2：ユーザー向けメッセージ辞書を作る（翻訳テーブル）
export const UserErrorMessages = {
[ErrorCodes.API_TIMEOUT]: "通信が混み合っています。時間をおいて再度お試しください。",
[ErrorCodes.API_INVALID_RESPONSE]: "サーバーから正しい情報を取得できませんでした。",
[ErrorCodes.AUTH_TOKEN_EXPIRED]: "ログインの有効期限が切れています。再度ログインしてください。",
[ErrorCodes.VALID_REQUIRED]: "入力されていない項目があります。確認してください。",
[ErrorCodes.SYS_UNKNOWN]: "予期しないエラーが発生しました。再度お試しください。",
};
ステップ3：内部エラー（AppError）を作る
class AppError extends Error {
constructor(code, message, extra = {}) {
super(message);
this.code = code;
Object.assign(this, extra);
}
}
ステップ4：ユーザー向けメッセージを生成する関数を作る（最重要）
function toUserMessage(error) {
const code = error.code || ErrorCodes.SYS_UNKNOWN;
return UserErrorMessages[code] || UserErrorMessages[ErrorCodes.SYS_UNKNOWN];
}
使用例
const err = new AppError(ErrorCodes.API_TIMEOUT, "API timeout");
console.log(toUserMessage(err));
出力：
通信が混み合っています。時間をおいて再度お試しください。
ステップ5：内部ログとユーザー向けメッセージを分離する
内部ログ（開発者向け）とユーザー向けメッセージは別に扱います。
function handleError(error, context) {
Logger.error(error, context); // 内部ログ
return toUserMessage(error); // ユーザー向け
}
ステップ6：UI に表示するテンプレートを作る
function showErrorToUser(error) {
const msg = toUserMessage(error);
alert(msg); // 実務ではモーダルやトーストに置き換える
}
ステップ7：業務で使えるユーザー向けエラーメッセージ生成ユーティリティ（完成版）
export const UserErrorUtil = {
toMessage(error) {
const code = error.code || ErrorCodes.SYS_UNKNOWN;
return UserErrorMessages[code] || UserErrorMessages[ErrorCodes.SYS_UNKNOWN];
},
handle(error, context = "") {
Logger.error(error, context); // 内部ログ
return this.toMessage(error); // ユーザー向け
},
show(error) {
const msg = this.toMessage(error);
alert(msg); // UI表示
},
};
ステップ8：業務での活用例
API 呼び出し
try {
await fetch("/api/user");
} catch (e) {
const err = new AppError(ErrorCodes.API_TIMEOUT, "API timeout", { original: e });
UserErrorUtil.show(err);
}
認証エラー
throw new AppError(ErrorCodes.AUTH_TOKEN_EXPIRED, "Token expired");
バリデーションエラー
throw new AppError(ErrorCodes.VALID_REQUIRED, "name is required");
深掘り：ユーザー向けエラーメッセージが重要な理由
1. ユーザー体験を守る
技術的なエラーをそのまま見せると混乱します。
2. セキュリティリスクを防ぐ
内部情報（SQL、APIレスポンスなど）を隠せます。
3. サポートコストを下げる
「何が起きたか」「どうすればいいか」が明確になります。
4. チーム全体で統一されたメッセージになる
バラバラな表現を防ぎ、品質が向上します。
5. ログとユーザー向けメッセージを分離できる
内部ログは詳細、ユーザー向けは簡潔という設計が可能です。
まとめ：ユーザー向けエラーメッセージ生成は「技術とユーザー体験をつなぐ翻訳技術」
ユーザー向けエラーメッセージ生成を導入することで、次のメリットが得られます。
- ユーザー体験が向上する
- 内部情報が漏れず安全になる
- 障害対応が高速化する
- ログとユーザー向けメッセージを分離できる
- チーム全体で統一された表現になる
エラーコード管理と組み合わせることで、 業務システムの品質が劇的に向上します。