⚡ クイックスタート
このハンズオンチュートリアルでは、5分未満でゼロから動作する API まで構築します。
準備済みの Authentication Service と User Service を公開する最小限の Express サーバーを MongoDB で作成します。
📋 前提条件
開始する前に、システムに以下がインストールされていることを確認してください：
- 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 の最新のローカル開発版を使用する必要がある場合は、以下の手順に従ってください：
- SDK をローカルにクローンしてビルドします：
git clone <sdk-repository-url>
cd nodeblocks-backend-sdk
npm install
npm run build
npm link
- クイックスタートプロジェクトで、ローカル版にリンクします：
npm link @nodeblocks/backend-sdk
- 公開版に戻すには：
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 { withMongo } = drivers;
const connectToDatabase = withMongo('mongodb://localhost:27017', 'dev', 'user', 'password');
// Authentication Service - handles user registration, login, and token management
express()
.use(
authService(
await connectToDatabase('identities'),
{
authSecrets: {
authEncSecret: 'your-encryption-secret',
authSignSecret: 'your-signing-secret',
},
identity: {
typeIds: {
admin: '100',
guest: '000',
regular: '010',
},
},
}
),
userService(
{
...(await connectToDatabase('users')),
...(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'));
⚠️ 重要:
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 '{"name":"John","identityId":"6dcdd50a-e0e6-445d-82e1-3da35bc2d149"}'
以下のような JSON レスポンスが返されるはずです：
{
"id": "878fc020-b313-42a9-bdc6-4946b9be598e",
"identityId": "6dcdd50a-e0e6-445d-82e1-3da35bc2d149",
"organizationFollows": [],
"productLikes": [],
"profileFollows": [],
"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 '{"identityId":"6dcdd50a-e0e6-445d-82e1-3da35bc2d149"}'
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 が完成しました：
- 認証システム - ユーザー登録とログイン
- JWT トークン管理 - アクセストークンとリフレッシュトークン
- ユーザーの CRUD 操作 (作成、読み取り、更新、削除)
- JSON Schema を使用した自動検証
- 適切な接続処理を含む 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- ユーザーを削除（管理者または本人）
🔐 認証フロー
/auth/register経由でユーザーアカウントを登録/auth/login経由でログインしてアクセストークンとリフレッシュトークンを取得- 保護されたエンドポイントには
Authorization: Bearer <token>ヘッダーでアクセストークンを使用
➡️ 次のステップ
- カスタムサービスの作成 - 独自のサービスを構築する方法を学習
- スキーマの概念 - データ検証を理解
- ハンドラーパターン - ビジネスロジックの整理をマスター