Node.jsとExpress.jsでRESTful APIを構築する方法

1. プロジェクトのセットアップ

Node.jsとExpress.jsを使用してRESTful APIを構築するには、まずプロジェクトの初期設定を行う必要があります。package.jsonの設定、必要なパッケージのインストール、基本的なディレクトリ構造の作成を行います。

プロジェクトのセットアップでは、Node.jsプロジェクトの初期化、Express.jsのインストール、基本的なディレクトリ構造の作成を行います。

# プロジェクトの初期化
npm init -y

# Express.jsのインストール
npm install express

# 開発用ツールのインストール
npm install --save-dev nodemon

{
  "name": "express-api",
  "version": "1.0.0",
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js"
  },
  "dependencies": {
    "express": "^4.18.2"
  },
  "devDependencies": {
    "nodemon": "^3.0.1"
  }
}

2. 基本的なExpressアプリケーション

Express.jsを使用して、最小限のサーバーアプリケーションを作成します。基本的なルーティング、ミドルウェアの使用、サーバーの起動方法を学びます。

const express = require('express');
const app = express();
const PORT = process.env.PORT || 3000;

// JSONボディのパース
app.use(express.json());

// 基本的なルート
app.get('/', (req, res) => {
  res.json({ message: 'Hello, Express!' });
});

// サーバーの起動
app.listen(PORT, () => {
  console.log(`Server is running on port ${PORT}`);
});

3. RESTful APIの実装

Express.jsを使用して、RESTful APIを実装します。ユーザー管理APIを例に、CRUD操作（作成、読み取り、更新、削除）を実装します。

const express = require('express');
const app = express();
app.use(express.json());

// 仮のデータストア
let users = [
  { id: 1, name: '山田太郎', email: 'yamada@example.com' },
  { id: 2, name: '佐藤花子', email: 'sato@example.com' }
];

// ユーザー一覧を取得
app.get('/users', (req, res) => {
  res.json(users);
});

// 特定のユーザーを取得
app.get('/users/:id', (req, res) => {
  const user = users.find(u => u.id === parseInt(req.params.id));
  if (!user) {
    return res.status(404).json({ error: 'User not found' });
  }
  res.json(user);
});

// 新規ユーザーを作成
app.post('/users', (req, res) => {
  const { name, email } = req.body;
  const newUser = {
    id: users.length + 1,
    name,
    email
  };
  users.push(newUser);
  res.status(201).json(newUser);
});

// ユーザーを更新
app.put('/users/:id', (req, res) => {
  const user = users.find(u => u.id === parseInt(req.params.id));
  if (!user) {
    return res.status(404).json({ error: 'User not found' });
  }
  user.name = req.body.name || user.name;
  user.email = req.body.email || user.email;
  res.json(user);
});

// ユーザーを削除
app.delete('/users/:id', (req, res) => {
  const index = users.findIndex(u => u.id === parseInt(req.params.id));
  if (index === -1) {
    return res.status(404).json({ error: 'User not found' });
  }
  users.splice(index, 1);
  res.status(204).send();
});

app.listen(3000, () => {
  console.log('Server is running on port 3000');
});

4. ミドルウェアの活用

ミドルウェアは、リクエストとレスポンスの間に実行される関数です。ロギング、認証、エラーハンドリングなど、様々な用途で使用できます。カスタムミドルウェアを作成し、適切に活用する方法を学びます。

// ロギングミドルウェア
const logger = (req, res, next) => {
  console.log(`${req.method} ${req.path} - ${new Date().toISOString()}`);
  next();
};

// 認証ミドルウェア
const authenticate = (req, res, next) => {
  const token = req.headers.authorization?.split(' ')[1];
  if (!token) {
    return res.status(401).json({ error: 'Authentication required' });
  }
  // トークンの検証（簡略化）
  if (token !== 'valid-token') {
    return res.status(401).json({ error: 'Invalid token' });
  }
  req.user = { id: 1, name: 'Test User' };
  next();
};

// ミドルウェアの使用
app.use(logger);

// 保護されたルート
app.get('/protected', authenticate, (req, res) => {
  res.json({ message: 'Protected route', user: req.user });
});

5. エラーハンドリング

エラーハンドリングは、APIの堅牢性を向上させる重要な要素です。統一されたエラーレスポンス形式、エラーミドルウェアの実装、適切なHTTPステータスコードの使用を学びます。

// カスタムエラークラス
class AppError extends Error {
  constructor(message, statusCode) {
    super(message);
    this.statusCode = statusCode;
    this.isOperational = true;
    Error.captureStackTrace(this, this.constructor);
  }
}

// エラーミドルウェア
const errorHandler = (err, req, res, next) => {
  const statusCode = err.statusCode || 500;
  const message = err.message || 'Internal Server Error';
  
  res.status(statusCode).json({
    error: {
      code: statusCode,
      message: message,
      ...(process.env.NODE_ENV === 'development' && { stack: err.stack })
    }
  });
};

// エラーの使用例
app.get('/users/:id', (req, res, next) => {
  const user = users.find(u => u.id === parseInt(req.params.id));
  if (!user) {
    return next(new AppError('User not found', 404));
  }
  res.json(user);
});

// エラーミドルウェアの登録（最後に配置）
app.use(errorHandler);

6. バリデーション

バリデーションは、入力データの検証を行う重要な要素です。express-validatorを使用して、リクエストデータの検証を行います。

const { body, validationResult } = require('express-validator');

// バリデーションルール
const validateUser = [
  body('name').trim().isLength({ min: 1, max: 100 }).withMessage('名前は1文字以上100文字以下である必要があります'),
  body('email').isEmail().normalizeEmail().withMessage('有効なメールアドレスを入力してください'),
  body('password').isLength({ min: 8 }).withMessage('パスワードは8文字以上である必要があります')
];

// バリデーションミドルウェア
const handleValidationErrors = (req, res, next) => {
  const errors = validationResult(req);
  if (!errors.isEmpty()) {
    return res.status(400).json({
      error: {
        code: 'VALIDATION_ERROR',
        message: 'バリデーションエラーが発生しました',
        details: errors.array()
      }
    });
  }
  next();
};

// ルートでの使用
app.post('/users', validateUser, handleValidationErrors, (req, res) => {
  const { name, email, password } = req.body;
  // バリデーション済みのデータを使用
  const newUser = { id: users.length + 1, name, email };
  users.push(newUser);
  res.status(201).json(newUser);
});

7. データベース統合

データベース統合は、APIの重要な要素です。MySQLやMongoDBなどのデータベースと統合し、データの永続化を行います。

// MySQLとの統合（mysql2を使用）
const mysql = require('mysql2/promise');

const pool = mysql.createPool({
  host: process.env.DB_HOST,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME,
  waitForConnections: true,
  connectionLimit: 10
});

app.get('/users', async (req, res, next) => {
  try {
    const [rows] = await pool.query('SELECT * FROM users');
    res.json(rows);
  } catch (error) {
    next(error);
  }
});

// MongoDBとの統合（mongooseを使用）
const mongoose = require('mongoose');

// スキーマ定義
const userSchema = new mongoose.Schema({
  name: { type: String, required: true },
  email: { type: String, required: true, unique: true },
  password: { type: String, required: true }
}, { timestamps: true });

const User = mongoose.model('User', userSchema);

// 接続
mongoose.connect(process.env.MONGODB_URI);

// ルートでの使用
app.get('/users', async (req, res, next) => {
  try {
    const users = await User.find();
    res.json(users);
  } catch (error) {
    next(error);
  }
});

8. 認証と認可

認証と認可は、APIのセキュリティにおいて重要な要素です。JWT（JSON Web Token）を使用した認証を実装し、保護されたルートを実装します。

const jwt = require('jsonwebtoken');
const bcrypt = require('bcrypt');

// ログイン
app.post('/auth/login', async (req, res, next) => {
  try {
    const { email, password } = req.body;
    const user = await User.findOne({ email });
    
    if (!user || !await bcrypt.compare(password, user.password)) {
      return res.status(401).json({ error: 'Invalid credentials' });
    }
    
    const token = jwt.sign(
      { userId: user._id },
      process.env.JWT_SECRET,
      { expiresIn: '1h' }
    );
    
    res.json({ token });
  } catch (error) {
    next(error);
  }
});

// 認証ミドルウェア
const authenticateToken = (req, res, next) => {
  const token = req.headers.authorization?.split(' ')[1];
  
  if (!token) {
    return res.status(401).json({ error: 'Authentication required' });
  }
  
  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.userId = decoded.userId;
    next();
  } catch (error) {
    return res.status(403).json({ error: 'Invalid token' });
  }
};

// 保護されたルート
app.get('/users/me', authenticateToken, async (req, res, next) => {
  try {
    const user = await User.findById(req.userId);
    res.json(user);
  } catch (error) {
    next(error);
  }
});

9. レート制限

レート制限は、APIの過剰な使用を防ぎ、サーバーの負荷を軽減するための仕組みです。express-rate-limitを使用して、レート制限を実装します。

const rateLimit = require('express-rate-limit');

// グローバルレート制限
const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15分
  max: 100, // 最大100リクエスト
  message: {
    error: 'Too many requests, please try again later.'
  },
  standardHeaders: true,
  legacyHeaders: false
});

app.use(limiter);

// 特定のルート用のレート制限
const authLimiter = rateLimit({
  windowMs: 15 * 60 * 1000,
  max: 5, // ログイン試行は5回まで
  skipSuccessfulRequests: true
});

app.use('/auth/login', authLimiter);

10. CORS設定

CORS（Cross-Origin Resource Sharing）は、異なるオリジンからのリクエストを許可するための仕組みです。corsパッケージを使用して、CORSを設定します。

const cors = require('cors');

// 基本的なCORS設定
app.use(cors());

// 詳細なCORS設定
const corsOptions = {
  origin: process.env.ALLOWED_ORIGINS?.split(',') || 'http://localhost:3000',
  methods: ['GET', 'POST', 'PUT', 'DELETE'],
  allowedHeaders: ['Content-Type', 'Authorization'],
  credentials: true
};

app.use(cors(corsOptions));

11. 環境変数の管理

環境変数は、設定情報を管理するための重要な仕組みです。dotenvパッケージを使用して、環境変数を管理します。

// .envファイル
// DB_HOST=localhost
// DB_USER=root
// DB_PASSWORD=password
// DB_NAME=mydb
// JWT_SECRET=your-secret-key
// PORT=3000

// index.js
require('dotenv').config();

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

const PORT = process.env.PORT || 3000;

// 環境変数の使用
const dbConfig = {
  host: process.env.DB_HOST,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME
};

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

12. ベストプラクティス

Express.jsを使用したRESTful APIの構築におけるベストプラクティスをまとめます。これらの原則に従うことで、使いやすく、保守しやすく、拡張性の高いAPIを構築できます。

• ルートの分離: ルートを別ファイルに分離し、app.jsやindex.jsをクリーンに保ちます。ルーターを使用して、関連するルートをグループ化します。
• ミドルウェアの適切な使用: ミドルウェアを適切に使用し、ロギング、認証、エラーハンドリングなどを実装します。ミドルウェアの順序に注意し、必要な場所に配置します。
• エラーハンドリング: 統一されたエラーレスポンス形式を使用し、適切なHTTPステータスコードを返します。エラーミドルウェアを最後に配置し、すべてのエラーをキャッチします。
• バリデーション: 入力データの検証を行い、不正なデータを防ぎます。express-validatorを使用して、バリデーションを実装します。
• 環境変数の管理: 機密情報や設定情報を環境変数で管理し、.envファイルを使用します。本番環境では、環境変数を適切に設定します。
• セキュリティ対策: HTTPSの使用、入力検証、SQLインジェクション対策、XSS対策などを実装し、安全なAPIを構築します。helmetパッケージを使用して、セキュリティヘッダーを設定します。
• パフォーマンス最適化: キャッシング、データベースクエリの最適化、接続プールの使用などにより、APIのパフォーマンスを向上させます。
• ロギング: 適切なロギングを実装し、エラーや重要なイベントを記録します。winstonやmorganなどのパッケージを使用します。
• テスト: 単体テスト、統合テスト、E2Eテストを実装し、APIの品質を保証します。JestやSupertestなどのパッケージを使用します。
• APIドキュメント: OpenAPI（Swagger）を使用して、APIをドキュメント化します。これにより、開発者がAPIを理解しやすくなります。