メインコンテンツまでスキップ
バージョン: 0.4.2

⚡ クイックスタート

この実践的なチュートリアルで、ゼロから動作するAPIまで5分未満で到達できます。

MongoDBをバックエンドにした既製の認証サービスとユーザーサービスを公開する最小限のExpressサーバーを作成します。

📋 前提条件​

開始する前に、システムに以下がインストールされていることを確認してください：

  • Node.js（v18以上）
  • DockerとDocker Compose（MongoDB用）
  • npmまたはyarn（パッケージマネージャー）

1️⃣ プロジェクトディレクトリの作成​

まず、クイックスタートプロジェクト用の新しいディレクトリを作成し、そこに移動します：

mkdir quickstart
cd quickstart

2️⃣ 依存関係のインストール​

npm install express@^4.19.0 mongodb @nodeblocks/backend-sdk
npm install -D typescript ts-node @types/node @types/express@^4.17.0

📝 重要: プライベート@nodeblocks/backend-sdkパッケージにアクセスするための認証トークン付き.npmrcファイルの追加を忘れないでください。

⚠️ 互換性: Nodeblocks Backend SDKはExpress v4.xと互換性があり、最適な開発体験にはTypeScriptが必要です。

ローカル開発版の使用​

SDKの最新ローカル開発版を使用する必要がある場合は、以下の手順に従ってください：

  1. SDKをローカルでクローンしビルド：
git clone <sdk-repository-url>
cd nodeblocks-backend-sdk
npm install
npm run build
npm link
  1. クイックスタートプロジェクトで、ローカル版にリンク：
npm link @nodeblocks/backend-sdk
  1. 公開版に戻すには：
npm unlink @nodeblocks/backend-sdk
npm install @nodeblocks/backend-sdk

3️⃣ TypeScriptの初期化​

適切なコンパイルと型チェックを有効にするためのTypeScript設定ファイルを作成：

npx tsc --init

これによりtsconfig.jsonファイルが生成されます。デフォルト設定を使用するか、プロジェクトのニーズに応じてカスタマイズできます。

4️⃣ Docker ComposeによるMongoDBのセットアップ​

プロジェクトルートディレクトリに以下の内容でdocker-compose.ymlを作成：

services:
  mongodb:
    image: mongo:7
    container_name: mongodb
    ports:
      - "27017:27017"
    restart: always
    environment:
      MONGO_INITDB_DATABASE: dev

💡 セキュリティ注意: 本番環境では、認証を追加してデータベースを保護できます。Docker Compose設定にMONGO_INITDB_ROOT_USERNAMEとMONGO_INITDB_ROOT_PASSWORD環境変数を含めてください。

MongoDBをデタッチモードで起動：

docker-compose up -d

5️⃣ サーバーのブートストラップ​

認証サービスとユーザーサービスの両方を実行するための最小セットアップで/index.tsを作成：

import express from 'express';

import { middlewares, services, drivers } from '@nodeblocks/backend-sdk';

const { nodeBlocksErrorMiddleware } = middlewares;
const { authService, userService } = services;
const { getMongoClient } = drivers;

const client = getMongoClient('mongodb://localhost:27017', 'dev');

// 認証サービス - ユーザー登録、ログイン、トークン管理を処理
express()
  .use(
    authService(
      {
        identity: client.collection('identity'),
      },
      {
        authSecrets: {
          authEncSecret: 'your-encryption-secret',
          authSignSecret: 'your-signing-secret',
        },
      },
    ),
    userService(
      {
        users: client.collection('users'),
        identity: client.collection('identity'),
      },
      {
        authSecrets: {
          authEncSecret: 'your-encryption-secret',
          authSignSecret: 'your-signing-secret',
        },
      }
    )
  )
  .use(nodeBlocksErrorMiddleware())
  .listen(8089, () => console.log('Server running on http://localhost:8089'));

⚠️ 重要: nodeBlocksErrorMiddleware()は必須です！これがないと、エラー発生時にAPIはJSONレスポンスの代わりにHTMLエラーページを返します。サービスの後に必ず含めてください。

🔑 認証セットアップ: 認証サービスはユーザー登録、ログイン、招待管理のエンドポイントを提供します。ユーザーサービスはそのエンドポイントにアクセスするために有効な認証トークンが必要です。

6️⃣ サーバーのビルドと実行​

TypeScriptコードをコンパイルしてサーバーを起動：

npx tsc
node index.js

以下の出力が表示されるはずです：

Server running on http://localhost:8089

認証サービスとユーザーサービスの両方を備えたAPIサーバーが実行中です！

7️⃣ 認証フローのテスト​

ステップ1: ユーザー登録​

まず、認証サービスを通じてユーザーアカウントを作成：

curl -X POST http://localhost:8089/auth/register \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "user@example.com",
    "password": "securepassword123"
  }'

ステップ2: アクセストークン取得のためのログイン​

登録したユーザーでログインしてアクセストークンを取得：

curl -X POST http://localhost:8089/auth/login \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "user@example.com",
    "password": "securepassword123"
  }'

アクセストークン、リフレッシュトークン、アイデンティティIDを含むレスポンスを受け取るはずです：

{
  "accessToken": "77c268e06d87594067d91c5b2f08e532...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "id": "f792cde5-958b-49e9-bf83-13d59c1e35c0"
}

ステップ3: アクセストークンの使用​

アクセストークンを使用してユーザーサービスエンドポイントにアクセスできます：

# ユーザープロフィール作成
curl -X POST http://localhost:8089/users/ \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{"email":"user@example.com","name":"田中","status":"active"}'

以下のようなJSONレスポンスを受け取るはずです：

{
  "id": "922ebcee-159f-4c92-8f2c-2599d7ed1680",
  "email": "user@example.com",
  "name": "田中", 
  "status": "active",
  "createdAt": "2025-06-18T06:19:55.974Z",
  "updatedAt": "2025-06-18T06:19:55.974Z"
}

🚨 エラーハンドリングの理解​

無効なリクエストを行って、エラーミドルウェアの動作を確認してみましょう：

# 必須フィールドが不足 - 検証エラーをトリガー
curl -X POST http://localhost:8089/users \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <bearer-token-from-auth-service>' \
  -d '{"email":"john@example.com"}'

nodeBlocksErrorMiddleware()使用時（✅ 正しい）:

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must have required property 'name'",
      "request body must have required property 'status'"
    ]
  }
}

nodeBlocksErrorMiddleware()未使用時（❌ 間違い）:

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Error</title>
</head>
<body>
<pre>NodeblocksError: Validation Error<br> --error stack--</pre>
</body>
</html>

💡 重要なポイント: エラーミドルウェアはすべてのエラーを一貫したJSONレスポンスに変換し、APIをクライアントフレンドリーにします。

🎉 構築したもの​

おめでとうございます！✨ 以下の機能を備えた完全なREST APIを構築しました：

  • ユーザー登録とログインを含む認証システム
  • アクセストークンとリフレッシュトークンによるJWTトークン管理
  • ユーザーのCRUD操作（作成、読み取り、更新、削除）
  • JSONスキーマを使用した自動検証
  • 適切な接続処理によるMongoDB統合
  • 適切なHTTPステータスコード付きJSONエラーレスポンス
  • 型安全性のためのTypeScriptサポート

🔗 利用可能なエンドポイント​

認証サービス（/auth）​

  • POST /auth/register - 新規ユーザー登録
  • POST /auth/login - ログインしてアクセストークン取得
  • POST /auth/logout - ログアウトしてトークン無効化

ユーザーサービス（/users） - 認証が必要​

  • POST /users - 新規ユーザー作成（管理者のみ）
  • GET /users - 全ユーザーリスト（管理者のみ）
  • GET /users/:userId - IDでユーザー取得（管理者または本人）
  • PATCH /users/:userId - ユーザー更新（管理者または本人）
  • DELETE /users/:userId - ユーザー削除（管理者または本人）
  • POST /users/:userId/lock - ユーザーアカウントロック（管理者のみ）
  • POST /users/:userId/unlock - ユーザーアカウントアンロック（管理者のみ）

🔐 認証フロー​

  1. /auth/registerでユーザーアカウントを登録
  2. /auth/loginでアクセストークンとリフレッシュトークンを取得してログイン
  3. 保護されたエンドポイント用にAuthorization: Bearer <token>ヘッダーでアクセストークンを使用

➡️ 次のステップ​