バージョン: 0.14.0 (最新)

⚡ クイックスタート

このハンズオンチュートリアルでは、ゼロからAPIの実行まで5分以下で到達します。

準備済み認証サービスとプロフィールサービスをMongoDBでバックエンドとして公開する最小限のExpressサーバーを作成します。

📋 前提条件

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

Node.js（v18以降）
Docker および Docker Compose（MongoDB用）
npm または yarn（パッケージマネージャー）

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

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

mkdir quickstart
cd quickstart

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

npm install express@^4.21.2 @nodeblocks/backend-sdk@^0.14.0
npm install -D typescript @types/node @types/express@^4.17.0

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

⚠️ 互換性: このドキュメントは @nodeblocks/backend-sdk 0.14.0 および Express 4.21.x で検証されました。このチュートリアルにはSDKにTypeScriptが必要です。

Cookie認証依存関係

クイックスタートはデフォルトでbearer認証を使用します。authMode: 'cookie' を設定する場合、cookie-parser とそのTypeScript宣言もインストールしてください：

npm install cookie-parser
npm install -D @types/cookie-parser

ローカル開発バージョンの使用

すでに nodeblocks-backend-sdk リポジトリがプロジェクトの隣にチェックアウトされている場合（例：monorepoの場合）、ローカルでビルドしてリンクします：

cd /path/to/nodeblocks-backend-sdk
npm install
npm run build
npm link

cd /path/to/quickstart
npm link @nodeblocks/backend-sdk

公開パッケージに戻す場合：

npm unlink @nodeblocks/backend-sdk
npm install @nodeblocks/backend-sdk@^0.14.0

3️⃣ TypeScriptの初期化

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

npx tsc --init

生成された tsconfig.json を更新して、このチュートリアルでのExpressデフォルトインポートがコンパイルされるようにします：

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "moduleResolution": "Node",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true
  }
}

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
      MONGO_INITDB_ROOT_USERNAME: user
      MONGO_INITDB_ROOT_PASSWORD: password

💡 ノート: MONGO_INITDB_ROOT_* は**admin**データベースにルートユーザーを作成します。以下の withMongo 接続URLには authSource=admin が含まれており、dev データベースに接続するとき認証が成功します。ユーザー名とパスワードはDocker Composeの値と一致する必要があります。

デタッチドモードでMongoDBを開始：

docker compose up -d

5️⃣ サーバーのBootstrap

認証およびプロフィールサービスの両方を実行するための最小限のセットアップとして /index.ts を作成します：

import express from 'express';

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

const {nodeBlocksErrorMiddleware} = middlewares;
const {authService, profileService} = services;
const {withMongo} = drivers;

const connectToDatabase = withMongo('mongodb://localhost:27017/?authSource=admin', 'dev', 'user', 'password');

async function main() {
  // 認証サービス - 登録、ログイン、およびトークン管理を処理
  express()
    .use(
      authService({
        ...(await connectToDatabase('identities')),
        ...(await connectToDatabase('refreshtokens')),
      }, {
        authSecrets: {
          authEncSecret: 'your-encryption-secret',
          authSignSecret: 'your-signing-secret',
        },
        identity: {
          typeIds: {
            admin: '100',
            guest: '000',
            regular: '010',
          },
        },
      }),
      profileService(
        {
          ...(await connectToDatabase('profiles')),
          ...(await connectToDatabase('identities')),
          ...(await connectToDatabase('organizations')),
          ...(await connectToDatabase('products')),
        },
        {
          authSecrets: {
            authEncSecret: 'your-encryption-secret',
            authSignSecret: 'your-signing-secret',
          },
          identity: {
            typeIds: {
              admin: '100',
              guest: '000',
              regular: '010',
            },
          },
        },
      ),
    )
    .use(nodeBlocksErrorMiddleware())
    .listen(8089, () => console.log('Server running on http://localhost:8089'));
}

main().catch(error => {
  console.error(error);
  process.exit(1);
});

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

🔑 認証セットアップ: このクイックスタートは登録、ログイン、リフレッシュトークン、およびログアウトフローに必要な identities と refreshtokens データストアを構成します。authService は招待、ワンタイムトークン、メール、およびOAuthルートもマウントします; 必要なデータストアとドライバー（例：invitations、onetimetokens、メール、およびOAuthドライバー）を提供してからそれらを有効にしてください。プロフィールサービスには、エンドポイントにアクセスするために有効な認証トークンが必要です。

🖼️ プロフィールスコープ: この例は意図的にアバターなしのプロフィールをサポートしています。profileService はアバターのアップロードとアバター正規化ルートもマウントしますが、そのドライバーを構成するまで avatar フィールドを送信しないでくださいまたはアバターエンドポイントを使用しないでください。フォロー/いいねルートはこのクイックスタートの範囲外です。

Cookie認証を使用する

cookie認証の場合、import cookieParser from 'cookie-parser'; を追加し、2つのサービス呼び出しの前に .use(cookieParser()) を呼び出し、メイン例の両方のサービス設定オブジェクトに authMode: 'cookie' を設定します。

SDKは req.cookies から認証トークンを読み取ります; ホストアプリケーションには cookie-parser を登録しません。

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"
  }'

201 Created レスポンスが空の本文とともに返されます。

ノート: 登録はレスポンス本文にidentity idを返しません。プロフィール作成時に identityId として使用する場合は、ログインレスポンス（ステップ2）の id フィールドを使用してください。

ステップ2: アクセストークンを取得するためにログイン

登録されたアイデンティティでログインして、アクセストークンとidentity idを取得：

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

アクセストークン、リフレッシュトークン、およびidentity idを含むレスポンスが返されます：

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

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

これでアクセストークンとログインレスポンスの id を使用して、プロフィールサービスエンドポイントにアクセスできます：

# プロフィールを作成（identityId = ログインレスポンスからのid）
curl -X POST http://localhost:8089/profiles \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"John","identityId":"f792cde5-958b-49e9-bf83-13d59c1e35c0"}'

以下のようなJSONレスポンスが返されるはずです：

{
  "id": "878fc020-b313-42a9-bdc6-4946b9be598e",
  "identityId": "f792cde5-958b-49e9-bf83-13d59c1e35c0",
  "name": "John",
  "organizationFollows": [],
  "productLikes": [],
  "profileFollows": [],
  "createdAt": "2025-06-18T06:19:55.974Z",
  "updatedAt": "2025-06-18T06:19:55.974Z"
}

🚨 エラー処理について

エラーミドルウェアのアクションを見るために、無効なリクエストを試してください：

# 必須フィールドが不足 - バリデーションエラーをトリガー
curl -X POST http://localhost:8089/profiles \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <bearer-token-from-auth-service>' \
  -d '{"identityId":"f792cde5-958b-49e9-bf83-13d59c1e35c0"}'

nodeBlocksErrorMiddleware() 付き（✅ 正しい）：

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

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（ mounted サービスのサブセット）を持っています：

認証システム - 登録とログイン付き
JWTトークン管理 - アクセスおよびリフレッシュトークン付き
プロフィールのCRUD操作 （作成、読み取り、更新、削除）
JSONスキーマによる自動検証
MongoDB統合
適切なHTTPステータスコード付きJSONエラーレスポンス
型安全のためのTypeScriptサポート

本番ノート: withMongo はコレクションリクエストごとに新しいMongoDBクライアントを作成します。これはクイックスタートには便利ですが、本番アプリケーションは1つの MongoClient を作成し、サービス間でそのコレクションを再利用し、グラシヤスシャットダウン中に閉じるべきです。

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

認証サービス（`/auth`）

POST /auth/register - 新しいアイデンティティを登録
POST /auth/login - ログインしてアクセストークンを取得
POST /auth/logout - ログアウトしてトークンを取り消す（認証必要；bearerモードでは本文に refreshToken が必要）

プロフィールサービス（`/profiles`） - 認証必要

POST /profiles - 新しいプロフィールを作成（管理者または自身）
GET /profiles - すべてのプロフィールを一覧表示（管理者のみ）
GET /profiles/:profileId - IDでプロフィールを取得（管理者またはプロフィール所有者）
PATCH /profiles/:profileId - プロフィールを更新（管理者またはプロフィール所有者）
DELETE /profiles/:profileId - プロフィールを削除（管理者またはプロフィール所有者）

🔐 認証フロー

登録 /auth/register 経由
ログイン /auth/login でアクセスおよびリフレッシュトークンを取得
アクセストークンを使用 Authorization: Bearer <token> ヘッダーで保護されたエンドポイントに

➡️ 次のステップ

カスタムサービスの作成 - 独自のサービスを構築する方法を学ぶ
スキーマコンセプト - データ検証を理解する
ハンドラパターン - ビジネスロジックの編成をマスターする

📋 前提条件​

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

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

Cookie認証依存関係​

ローカル開発バージョンの使用​

3️⃣ TypeScriptの初期化​

4️⃣ Docker ComposeでMongoDBをセットアップ​

5️⃣ サーバーのBootstrap​

Cookie認証を使用する​

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

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

ステップ1: 登録​

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

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

🚨 エラー処理について​

🎉 あなたが構築したもの​

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

認証サービス（/auth）​

プロフィールサービス（/profiles） - 認証必要​

🔐 認証フロー​

➡️ 次のステップ​