2025年10月14日日本語

Express.jsアプリケーションでTypeScriptミドルウェアを理解し、実装するための包括的なガイド。堅牢で保守可能なコードのための高度なタイプパターンを探求します。

TypeScriptミドルウェア：Expressミドルウェアのタイプパターンをマスターする

Express.jsは、ミニマリストで柔軟なNode.jsのWebアプリケーションフレームワークであり、開発者は堅牢でスケーラブルなAPIとWebアプリケーションを構築できます。TypeScriptは静的型付けを追加することでExpressを強化し、コードの保守性を向上させ、エラーを早期に検出します。ミドルウェア関数はExpressの基礎であり、ルートハンドラーに到達する前にリクエストをインターセプトして処理できます。この記事では、Expressミドルウェアを定義および利用するための高度なTypeScriptタイプパターンを探求し、タイプ安全性とコードの明瞭さを向上させます。

Expressミドルウェアの理解

ミドルウェア関数は、リクエストオブジェクト（req）、レスポンスオブジェクト（res）、およびアプリケーションのリクエスト/レスポンスサイクル内の次のミドルウェア関数にアクセスできる関数です。ミドルウェア関数は、次のタスクを実行できます。

任意のコードを実行する。
リクエストオブジェクトとレスポンスオブジェクトを変更する。
リクエスト/レスポンスサイクルを終了する。
スタック内の次のミドルウェア関数を呼び出す。

ミドルウェア関数は、Expressアプリケーションに追加されると、順番に実行されます。ミドルウェアの一般的なユースケースは次のとおりです。

リクエストのログ記録。
ユーザーの認証。
リソースへのアクセス権の認可。
リクエストデータの検証。
エラー処理。

基本的なTypeScriptミドルウェア

基本的なTypeScript Expressアプリケーションでは、ミドルウェア関数は次のようになります。

            
import { Request, Response, NextFunction } from 'express';

function loggerMiddleware(req: Request, res: Response, next: NextFunction) {
  console.log(`Request: ${req.method} ${req.url}`);
  next();
}

export default loggerMiddleware;

このシンプルなミドルウェアは、リクエストメソッドとURLをコンソールに記録します。タイプアノテーションを分解してみましょう。

Request：Expressリクエストオブジェクトを表します。
Response：Expressレスポンスオブジェクトを表します。
NextFunction：呼び出されると、スタック内の次のミドルウェアを実行する関数。

このミドルウェアは、Expressアプリケーションで次のように使用できます。

            
import express from 'express';
import loggerMiddleware from './middleware/loggerMiddleware';

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

app.use(loggerMiddleware);

app.get('/', (req, res) => {
  res.send('Hello, world!');
});

app.listen(port, () => {
  console.log(`Server listening on port ${port}`);
});

ミドルウェアの高度なタイプパターン

基本的なミドルウェアの例は機能しますが、より複雑なシナリオでは柔軟性とタイプ安全性が不足しています。TypeScriptを使用したミドルウェア開発を強化する高度なタイプパターンを探求しましょう。

1. カスタムリクエスト/レスポンスタイプ

多くの場合、RequestまたはResponseオブジェクトをカスタムプロパティで拡張する必要があります。たとえば、認証後、Requestオブジェクトにuserプロパティを追加する場合があります。TypeScriptでは、宣言のマージを使用して既存のタイプを拡張できます。

            
// src/types/express/index.d.ts
import { Request as ExpressRequest } from 'express';

declare global {
  namespace Express {
    interface Request {
      user?: {
        id: string;
        email: string;
        // ... other user properties
      };
    }
  }
}

export {}; // This is needed to make the file a module

この例では、オプションのuserプロパティを含めるようにExpress.Requestインターフェイスを拡張しています。認証ミドルウェアで、このプロパティを設定できます。

            
import { Request, Response, NextFunction } from 'express';

function authenticationMiddleware(req: Request, res: Response, next: NextFunction) {
  // Simulate authentication logic
  const userId = req.headers['x-user-id'] as string; // Or fetch from a token, etc.

  if (userId) {
    // In a real application, you would fetch the user from a database
    req.user = {
      id: userId,
      email: `user${userId}@example.com`
    };
    next();
  } else {
    res.status(401).send('Unauthorized');
  }
}

export default authenticationMiddleware;

ルートハンドラーで、req.userプロパティに安全にアクセスできます。

            
import express from 'express';
import authenticationMiddleware from './middleware/authenticationMiddleware';

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

app.use(authenticationMiddleware);

app.get('/profile', (req: Request, res: Response) => {
  if (req.user) {
    res.send(`Hello, ${req.user.email}! Your user ID is ${req.user.id}`);
  } else {
    // This should never happen if the middleware is working correctly
    res.status(500).send('Internal Server Error');
  }
});

app.listen(port, () => {
  console.log(`Server listening on port ${port}`);
});

2. ミドルウェアファクトリ

ミドルウェアファクトリは、ミドルウェア関数を返す関数です。このパターンは、特定のオプションまたは依存関係でミドルウェアを構成する必要がある場合に役立ちます。たとえば、メッセージを特定のファイルに記録するロギングミドルウェアを考えてみましょう。

            
import { Request, Response, NextFunction } from 'express';
import fs from 'fs';
import path from 'path';

function createLoggingMiddleware(logFilePath: string) {
  return (req: Request, res: Response, next: NextFunction) => {
    const logMessage = `[${new Date().toISOString()}] Request: ${req.method} ${req.url}\n`;
    fs.appendFile(logFilePath, logMessage, (err) => {
      if (err) {
        console.error('Error writing to log file:', err);
      }
      next();
    });
  };
}

export default createLoggingMiddleware;

このミドルウェアファクトリは次のように使用できます。

            
import express from 'express';
import createLoggingMiddleware from './middleware/loggingMiddleware';

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

const logFilePath = path.join(__dirname, 'logs', 'requests.log');
app.use(createLoggingMiddleware(logFilePath));

app.get('/', (req, res) => {
  res.send('Hello, world!');
});

app.listen(port, () => {
  console.log(`Server listening on port ${port}`);
});

3. 非同期ミドルウェア

ミドルウェア関数は、データベースクエリやAPI呼び出しなどの非同期操作を実行する必要があることがよくあります。非同期操作を正しく処理するには、非同期操作の完了後にnext関数が呼び出されるようにする必要があります。これは、async/awaitまたはPromiseを使用して実現できます。

            
import { Request, Response, NextFunction } from 'express';

async function asyncMiddleware(req: Request, res: Response, next: NextFunction) {
  try {
    // Simulate an asynchronous operation
    await new Promise(resolve => setTimeout(resolve, 100));
    console.log('Asynchronous operation completed');
    next();
  } catch (error) {
    next(error); // Pass the error to the error handling middleware
  }
}

export default asyncMiddleware;

重要：非同期ミドルウェア内でエラーを処理し、next(error)を使用してエラー処理ミドルウェアに渡すことを忘れないでください。これにより、エラーが適切に処理および記録されます。

4. エラー処理ミドルウェア

エラー処理ミドルウェアは、リクエスト/レスポンスサイクル中に発生するエラーを処理する特別なタイプのミドルウェアです。エラー処理ミドルウェア関数には、4つの引数（err、req、res、およびnext）があります。

            
import { Request, Response, NextFunction } from 'express';

function errorHandler(err: any, req: Request, res: Response, next: NextFunction) {
  console.error(err.stack);
  res.status(500).send('Something went wrong!');
}

export default errorHandler;

エラー処理ミドルウェアは、他のすべてのミドルウェアおよびルートハンドラーの後に登録する必要があります。Expressは、4つの引数の存在によってエラー処理ミドルウェアを識別します。

            
import express from 'express';
import asyncMiddleware from './middleware/asyncMiddleware';
import errorHandler from './middleware/errorHandler';

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

app.use(asyncMiddleware);

app.get('/', (req, res) => {
  throw new Error('Simulated error!'); // Simulate an error
});

app.use(errorHandler); // Error handling middleware MUST be registered last

app.listen(port, () => {
  console.log(`Server listening on port ${port}`);
});

5. リクエスト検証ミドルウェア

リクエスト検証は、安全で信頼性の高いAPIを構築する上で重要な側面です。ミドルウェアを使用して、受信リクエストデータを検証し、ルートハンドラーに到達する前に特定の基準を満たしていることを確認できます。joiまたはexpress-validatorのようなライブラリをリクエスト検証に使用できます。

express-validatorを使用した例を次に示します。

            
import { Request, Response, NextFunction } from 'express';
import { body, validationResult } from 'express-validator';

const validateCreateUserRequest = [
  body('email').isEmail().normalizeEmail(),
  body('password').isLength({ min: 8 }),
  (req: Request, res: Response, next: NextFunction) => {
    const errors = validationResult(req);
    if (!errors.isEmpty()) {
      return res.status(400).json({ errors: errors.array() });
    }
    next();
  }
];

export default validateCreateUserRequest;

このミドルウェアは、リクエストボディのemailフィールドとpasswordフィールドを検証します。検証に失敗した場合、エラーメッセージの配列を含む400 Bad Requestレスポンスを返します。このミドルウェアは、ルートハンドラーで次のように使用できます。

            
import express from 'express';
import validateCreateUserRequest from './middleware/validateCreateUserRequest';

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

app.post('/users', validateCreateUserRequest, (req, res) => {
  // If validation passes, create the user
  res.send('User created successfully!');
});

app.listen(port, () => {
  console.log(`Server listening on port ${port}`);
});

6. ミドルウェアの依存性注入

ミドルウェア関数が外部サービスまたは構成に依存している場合、依存性注入はテスト容易性と保守性を向上させるのに役立ちます。tsyringeのような依存性注入コンテナを使用するか、依存関係を引数としてミドルウェアファクトリに渡すことができます。

依存性注入を使用したミドルウェアファクトリの例を次に示します。

            
// src/services/UserService.ts
export class UserService {
  async createUser(email: string, password: string): Promise {
    // In a real application, you would save the user to a database
    console.log(`Creating user with email: ${email} and password: ${password}`);
    await new Promise(resolve => setTimeout(resolve, 500)); // Simulate a database operation
  }
}

            
// src/middleware/createUserMiddleware.ts
import { Request, Response, NextFunction } from 'express';
import { UserService } from '../services/UserService';

function createCreateUserMiddleware(userService: UserService) {
  return async (req: Request, res: Response, next: NextFunction) => {
    try {
      const { email, password } = req.body;
      await userService.createUser(email, password);
      res.status(201).send('User created successfully!');
    } catch (error) {
      next(error);
    }
  };
}

export default createCreateUserMiddleware;

            
// src/app.ts
import express from 'express';
import createCreateUserMiddleware from './middleware/createUserMiddleware';
import { UserService } from './services/UserService';
import errorHandler from './middleware/errorHandler';

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

app.use(express.json()); // Parse JSON request bodies

const userService = new UserService();
const createUserMiddleware = createCreateUserMiddleware(userService);

app.post('/users', createUserMiddleware);

app.use(errorHandler);

app.listen(port, () => {
  console.log(`Server listening on port ${port}`);
});

TypeScriptミドルウェアのベストプラクティス

ミドルウェア関数を小さく、焦点を絞って維持します。各ミドルウェア関数は、単一の責任を持つ必要があります。
ミドルウェア関数にわかりやすい名前を使用します。名前は、ミドルウェアが行うことを明確に示す必要があります。
エラーを適切に処理します。常にエラーをキャッチし、next(error)を使用してエラー処理ミドルウェアに渡します。
カスタムリクエスト/レスポンスタイプを使用して、タイプ安全性を強化します。必要に応じて、RequestインターフェイスとResponseインターフェイスをカスタムプロパティで拡張します。
ミドルウェアファクトリを使用して、特定のオプションでミドルウェアを構成します。
ミドルウェア関数をドキュメント化します。ミドルウェアが行うこととその使用方法を説明します。
ミドルウェア関数を徹底的にテストします。ミドルウェア関数が正しく機能していることを確認するために、ユニットテストを作成します。

結論

TypeScriptは、静的型付けを追加し、コードの保守性を向上させ、エラーを早期に検出することにより、Expressミドルウェアの開発を大幅に強化します。カスタムリクエスト/レスポンスタイプ、ミドルウェアファクトリ、非同期ミドルウェア、エラー処理ミドルウェア、リクエスト検証ミドルウェアなどの高度なタイプパターンを習得することで、堅牢でスケーラブルでタイプセーフなExpressアプリケーションを構築できます。ミドルウェア関数を小さく、焦点を絞り、十分にドキュメント化するようにベストプラクティスに従うことを忘れないでください。