ドキュメント価格ブログ
お問い合わせ
ログイン無料で新規登録
Back to Tech Articles

Expressアプリケーションにおける堅牢なエラーハンドリング：実践ガイド

10月 06, 2025
# Misc

Lukas Schneider

DevOps Engineer · Leapcell

この記事はEnglish、한국어、Deutschでも利用できます
Cover of "Expressアプリケーションにおける堅牢なエラーハンドリング：実践ガイド"

はじめに

Web開発の世界では、堅牢で信頼性の高いアプリケーションを構築することが最優先事項です。たとえ細心の注意を払って作成されたコードであっても、ネットワーク障害から無効なユーザー入力まで、予期せぬ問題に遭遇する可能性があります。これらのエラーをどのように予測し、優雅に処理できるかは、ユーザーエクスペリエンス、アプリケーションの安定性、開発者の生産性に大きく影響します。人気のあるミニマリストWebフレームワークであるExpress.jsを使用するJavaScript開発者にとって、効果的なエラーハンドリング戦略を理解することは不可欠です。この記事では、Expressアプリケーションでのエラー管理のベストプラクティスについて、try-catchブロック、Promise.catch()ハンドラー、およびグローバルエラーミドルウェアとの相互作用に焦点を当てて解説します。これらのテクニックを習得することで、機能的であるだけでなく、回復力があり、保守性の高いExpressアプリケーションを構築できるようになります。

コアコンセプトの理解

Expressでのエラーハンドリングの詳細に入る前に、私たちの戦略の構成要素となるJavaScriptにおける基本的なエラーハンドリングメカニズムを簡単に復習しましょう。

  • try-catchブロック: この同期エラーハンドリングメカニズムにより、コードブロックをtryし、そのブロック内でエラーが発生した場合、それをcatchして処理できます。エラーが直接スローされる同期操作に最適です。

    try {
    // エラーをスローする可能性のあるコード
    const result = JSON.parse("{invalid json");
    console.log(result);
} catch (error) {
    console.error("An error occurred:", error.message);
}

  • Promises: Promisesは、非同期操作の最終的な完了（または失敗）とその結果の値を表すオブジェクトです。これらは、非同期コードを処理するための構造化された方法を提供します。

  • Promisesの.catch(): Promisesを扱う場合、非同期操作中に発生したエラーは通常、Promiseチェーンを伝播し、.catch()メソッドを使用してキャッチできます。これはtry-catchの非同期版です。

    function fetchData() {
    return new Promise((resolve, reject) => {
        setTimeout(() => {
            const success = Math.random() > 0.5;
            if (success) {
                resolve("Data fetched successfully!");
            } else {
                reject(new Error("Failed to fetch data."));
            }
        }, 1000);
    });
}

fetchData()
    .then(data => console.log(data))
    .catch(error => console.error("Promise caught error:", error.message));

  • Expressミドルウェア: Expressミドルウェア関数は、リクエストオブジェクト（req）、レスポンスオブジェクト（res）、およびアプリケーションのリクエスト・レスポンスサイクルの次のミドルウェア関数にアクセスできる関数です。コードを実行したり、リクエストおよびレスポンスオブジェクトを変更したり、リクエスト・レスポンスサイクルを終了したり、次のミドルウェアを呼び出したりできます。Expressのエラーハンドリングミドルウェアは、4つの引数：(err, req, res, next)をとる特別な種類のミドルウェアです。

Expressエラーハンドリングのベストプラクティス

これらのコンセプトを、Expressアプリケーションの効果的で実践的なエラーハンドリング戦略に統合しましょう。

1. 同期操作のためのローカルtry-catch

ルートハンドラーまたはその他のミドルウェア内の同期コードに対しては、try-catchが直接的なエラーを処理する最も簡単な方法です。これにより、同期エラーによるサーバーのクラッシュを防ぎ、クライアントに意味のあるエラーレスポンスを返すことができます。

// 例：エラーをスローする可能性のある同期操作
app.get('/sync-data', (req, res, next) => {
    try {
        const userInput = req.query.data;
        if (!userInput) {
            throw new Error("Data query parameter is required.");
        }
        // 同期処理の失敗をシミュレート
        if (userInput === 'fail') {
            throw new Error("Simulated synchronous processing error.");
        }
        res.status(200).send(`Processed: ${userInput}`);
    } catch (error) {
        // エラーを次のエラーハンドリングミドルウェアに渡す
        next(error);
    }
});

この例では、JSON.parseが失敗した場合や、カスタムバリデーションがエラーをスローした場合、catchブロックがそれをキャプチャします。catchブロックから直接エラーレスポンスを送信する（エラーレスポンスのフォーマットに一貫性がなくなる可能性がある）のではなく、next(error)を使用してグローバルエラーハンドラーに渡します。これにより、エラーレスポンスが集中化されます。

2. 非同期操作のためのPromise.catch()

非同期操作（データベース呼び出し、APIリクエスト、ファイルI/Oなど）を扱う場合、Promiseが標準です。Promiseチェーン内で発生するエラーは、.catch()を使用してキャッチする必要があります。try-catchと同様に、ベストプラクティスは、キャッチしたエラーをnextミドルウェアに渡して一元的に処理することです。

// 例：Promiseを使用した非同期操作
app.get('/async-data', (req, res, next) => {
    someAsyncOperation(req.query.id)
        .then(data => {
            if (!data) {
                // データが見つからない場合、カスタムエラーオブジェクトを作成できます
                const error = new Error("Data not found.");
                error.statusCode = 404; // エラーハンドラーのためにステータスコードを追加
                throw error; // .then()内でスローすると、次の.catch()に渡される
            }
            res.status(200).json(data);
        })
        .catch(error => {
            // someAsyncOperationまたは.then()内のスローからのあらゆるエラーをキャッチ
            next(error);
        });
});

// 非同期操作をシミュレートするヘルパー関数
function someAsyncOperation(id) {
    return new Promise((resolve, reject) => {
        setTimeout(() => {
            if (id === '123') {
                resolve({ id: '123', name: 'Sample Item' });
            } else if (id === 'error') {
                reject(new Error("Database connection failed."));
            } else {
                resolve(null); // データが見つからないことをシミュレート
            }
        }, 500);
    });
}

よりクリーンな非同期エラーハンドリングのためのasync/awaitの使用：

async/awaitを使用すると、非同期コードは同期コードのように見え、動作するように書くことができ、try-catchブロックを非同期操作にさえ適用できます。これは、可読性のためにしばしば好まれるアプローチです。

// 例：async/awaitとtry-catch
app.get('/async-await-data', async (req, res, next) => {
    try {
        const id = req.query.id;
        if (!id) {
            const error = new Error("ID parameter is required.");
            error.statusCode = 400;
            throw error;
        }

        const data = await someAsyncOperation(id); // Promiseを待機

        if (!data) {
            const error = new Error("Item not found.");
            error.statusCode = 404;
            throw error;
        }
        res.status(200).json(data);
    } catch (error) {
        // 同期および非同期のすべてのエラーがここでキャッチされる
        next(error);
    }
});

このパターンは、async関数内の単一のtry-catchブロックの下で、同期および非同期操作の両方のエラーハンドリングを集中化し、コードをはるかにクリーンで理解しやすくします。

3. グローバルエラーハンドリングミドルウェア

これは、堅牢なExpressエラーハンドリング戦略の要です。グローバルエラーミドルウェア関数は、他のすべてのルートとミドルウェアの後で登録されます。Expressは、4つの引数：(err, req, res, next)を受け入れるため、これをエラーハンドラーとして認識します。ルートまたは他のミドルウェアからnext(error)に渡されたすべてエラーは、最終的にここに到達します。

// グローバルエラーハンドリングミドルウェアを定義
// これはExpressアプリ定義の最後のミドルウェアである必要があります
app.use((err, req, res, next) => {
    console.error(`Error encountered: ${err.message}`);
    // 開発環境では完全なスタックトレースをログに記録しますが、本番環境ではそうしない場合があります
    if (process.env.NODE_ENV === 'development') {
        console.error(err.stack);
    }

    // ステータスコードを決定
    // エラーオブジェクトにアタッチされたステータスコードを優先し、デフォルトは500
    const statusCode = err.statusCode || 500;

    // 一貫したエラーレスポンスを構築
    res.status(statusCode).json({
        status: 'error',
        statusCode: statusCode,
        message: err.message || 'An unexpected error occurred.',
        // 本番環境では、クライアントにスタックトレースなどの機密性の高いエラー詳細を送信しないようにしてください
        // 500エラーには汎用的なメッセージを送信する場合があります
        ...(process.env.NODE_ENV === 'development' && { stack: err.stack })
    });
});

グローバルエラーミドルウェアの主な利点：

  • 一元化されたエラーハンドリング： アプリケーション全体のエラーはすべて単一のポイントにルーティングされ、一貫したエラーレスポンスが保証されます。
  • 分離： ルートハンドラーはアプリケーションロジックに焦点を当て、エラーレスポンスのフォーマットをミドルウェアに委任します。
  • セーフティネット： 個別のtry-catchまたは.catch()ブロックから逃れた未処理のエラーをキャッチし、サーバーのクラッシュを防ぎます。
  • ロギング： エラーをファイル、外部ロギングサービス、またはコンソールに記録するのに理想的です。
  • カスタマイズ： エラーの種類、環境（開発対本番）、その他の要因に基づいてエラーレスポンスを調整できます。

統合：完全な例

const express = require('express');
const app = express();
const port = 3000;

// JSONリクエストの解析用ミドルウェア
app.use(express.json());

// 非同期操作をシミュレートするヘルパー関数
function simulateDBFetch(id) {
    return new Promise((resolve, reject) => {
        setTimeout(() => {
            if (id === '1') {
                resolve({ id: '1', name: 'Product A', price: 29.99 });
            } else if (id === 'critical-fail') {
                reject(new Error("Database connection error."));
            } else {
                resolve(null); // 見つからず
            }
        }, 300);
    });
}

// 同期および非同期（async/await）エラーハンドリングを含むルート
app.get('/products/:id', async (req, res, next) => {
    try {
        const productId = req.params.id;

        // 同期バリデーション
        if (!productId || typeof productId !== 'string') {
            const error = new Error("Invalid product ID provided.");
            error.statusCode = 400;
            throw error; // キャッチブロックに直接スロー
        }

        // エラーの可能性を伴う非同期操作
        const product = await simulateDBFetch(productId);

        if (!product) {
            const error = new Error(`Product with ID ${productId} not found.`);
            error.statusCode = 404;
            throw error; // キャッチブロックに直接スロー
        }

        res.status(200).json(product);

    } catch (error) {
        // すべてのエラー（同期または非同期）をキャッチし、グローバルエラーハンドラーに渡す
        next(error);
    }
});

// 未処理のPromise拒否を示すルート（グローバル未処理拒否ハンドラーまたはExpress 5+が必要）
// Express 5+はasyncルートからのエラーを自動的にキャッチし、次のエラーミドルウェアに渡しますが、
// 明示的な.catch(next)またはasync/await try-catchは依然として良い実践です
app.get('/unhandled-promise', (req, res, next) => {
    // このPromiseは拒否され、ここでキャッチされない場合、Expressのデフォルトハンドラーまたはカスタムグローバルハンドラーによってキャッチされます。
    // Express 4.xの場合、これは通常、未処理のPromise拒否プロセスクラッシュを引き起こします。
    // Express 5.x+の場合、この拒否は自動的に次のエラーミドルウェアに渡されます。
    Promise.reject(new Error("This is an unhandled promise rejection error!"));
});

// 同期サーバーサイドレンダリングエラーのルート（例）
app.get('/render-error', (req, res, next) => {
    try {
        // レンダリングエラーをシミュレートする（例：テンプレート変数の欠落）
        // const templateEngine = require('some-template-engine');
        // templateEngine.render('non-existent-template', { data: null });
        throw new Error("Failed to render the page due to missing template data.");
    } catch (error) {
        next(error);
    }
});

// 404 Not Foundハンドラー - 特定のエラータイプとして機能
app.use((req, res, next) => {
    const error = new Error(`Cannot find ${req.originalUrl}`);
    error.statusCode = 404;
    next(error); // エラーハンドリングミドルウェアに渡す
});

// グローバルエラーハンドリングミドルウェア（最後にする必要があります）
app.use((err, req, res, next) => {
    console.error(`[ERROR] ${err.message}`);
    if (process.env.NODE_ENV === 'development' && err.stack) {
        console.error(err.stack);
    }

    const statusCode = err.statusCode || 500;
    const responseBody = {
        status: 'error',
        statusCode: statusCode,
        message: err.message || 'Something went wrong on the server.',
    };

    // 本番環境では、500エラーの詳細なエラーを明らかにしない
    if (statusCode === 500 && process.env.NODE_ENV === 'production') {
        responseBody.message = 'An internal server error occurred.';
    }
    
    res.status(statusCode).json(responseBody);
});

// サーバーの起動
app.listen(port, () => {
    console.log(`Server running on http://localhost:${port}`);
    console.log(`Open http://localhost:${port}/products/1`);
    console.log(`Open http://localhost:${port}/products/non-existent`);
    console.log(`Open http://localhost:${port}/products/critical-fail`);
    console.log(`Open http://localhost:${port}/unhandled-promise (Express 5+ or with global unhandled rejection catch)`);
    console.log(`Open http://localhost:${port}/render-error`);
    console.log(`Open http://localhost:${port}/non-existent-path`);
});

重要な検討事項：

  • Express 5.0とasyncルートハンドラー： Express 5.0（現在ベータ/RC）は、asyncルートハンドラー内でスローされたエラーを自動的にキャッチし、次のエラーミドルウェアに渡します。これにより、グローバルエラーハンドラーがある限り、すべてのasyncハンドラーでawait呼び出しを明示的にtry-catchブロックで囲む必要がなくなります。ただし、try-catchは、エラーを渡す前に特定のstatusCodeまたはメッセージをアタッチするための、より詳細なエラーハンドリングとしては依然として優れています。

  • 未処理のPromise拒否（Expressルート外）： Express 5.x はasyncルートからのエラーを処理しますが、グローバルなunhandledRejectionハンドラーは、Expressリクエスト/レスポンスサイクルの外で拒否される可能性のあるPromiseや、直接awaitされないPromiseにとって、依然として重要です。

    process.on('unhandledRejection', (reason, promise) => {
    console.error('Unhandled Rejection at:', promise, 'reason:', reason);
    // アプリケーション固有のロギング、クリーンアップ、またはプロセスの終了
    // ここでもスローしないでください！
    // process.exit(1); // 重大なエラーの場合は終了を検討する
});

  • エラーロギング： 堅牢なロギングソリューション（例：Winston、Pino）を統合して、エラーの詳細、スタックトレース、コンテキストをキャプチャします。これはデバッグと監視に非常に役立ちます。

  • カスタムエラークラス： より構造化されたエラーハンドリングのために、Errorを拡張し、ステータスコードやその他の関連情報を含めることができるカスタムエラークラス（例：NotFoundError、ValidationError、UnauthorizedError）の作成を検討してください。これにより、グローバルミドルウェアでのエラーの識別と処理がはるかにクリーンになります。

    class AppError extends Error {
    constructor(message, statusCode) {
        super(message);
        this.statusCode = statusCode;
        this.status = `${statusCode}`.startsWith('4') ? 'fail' : 'error';
        this.isOperational = true; // プログラミングエラーと運用エラーを区別するため
        Error.captureStackTrace(this, this.constructor);
    }
}

// 使用例：throw new AppError('Product not found', 404);

結論

効果的なエラーハンドリングは、堅牢なソフトウェアの証です。同期操作（特にasync/awaitを使用する場合）にtry-catchを体系的に使用し、非同期フローにPromise.catch()を活用し、グローバルエラーハンドリングミドルウェアを介してエラーレスポンスを一元化することにより、Express.js開発者は、回復力があり、クライアントに一貫したフィードバックを提供し、保守およびデバッグが容易なアプリケーションを構築できます。この階層化されたアプローチにより、エラーが未処理のままになることなく、より安定したユーザーフレンドリーなエクスペリエンスにつながります。

Share this article

HackerNews

More Posts from Leapcell

cover

Node.js APIにおけるDTOの静かなる力

cover

コールバック地獄からAsync-Awaitへ：非同期JavaScriptを使いこなす旅

Popular Posts