バージョン: 0.13.0 (Previous)

🔗 合成サービスの作成

このガイドでは、複数のNodeblocksサービスを単一の合成サービスに組み合わせ方を紹介します。認証とプロフィール管理機能を1つのアプリケーションに統合する複合Auth + プロフィールサービスを構築します。このパターンは、サービス間でコンテキストを共有したい場合や統一されたAPIを作成したい場合に便利です。

📦 必要なパッケージ: この例ではExpress、SDK、Ramda、および cookie-parser をインポートします。インストールしてください：
npm install express @nodeblocks/backend-sdk ramda cookie-parser
npm install --save-dev @types/node @types/express @types/ramda @types/cookie-parser
⚙️ モジュール設定: この例ではトップレベルの await を使用します。ESMモジュールとして実行するか（例えば tsconfig.json で "module": "NodeNext"、package.json で "type": "module"）、bootstrapコードを async function main() に移動してください。

🖼️ アバターサポート: このサンプルのプロフィールルートはアバターURLを正規化するので、例でもSDKの createFileStorageDriver を使用します。

🔐 Google Cloud認証情報: createFileStorageDriver は内部でGoogle Cloud Storageを使用するので、環境はStillsigned URL生成のために有効なGoogle Cloud認証情報を必要とします。

🏗️ サービスアーキテクチャ

合成サービスパターンにより、以下のことができます：

複数のサービスを組み合わせる - 認証とプロフィール管理をマージ
コンテキストを共有する - 同じデータベース設定とリクエストコンテキストを使用
統一されたミドルウェア - 複数のサービスから単一のExpressミドルウェアを作成
デプロイの簡素化 - 複数の関連サービスを1つのアプリケーションとしてデプロイ

1️⃣ コンポーネントを理解する

合成サービスを構築する前に、組み合わせるものを理解しましょう：

認証サービスフィーチャー

資格情報を登録 - メール/パスワードによるアイデンティティ登録
資格情報でログイン - 認証とトークン生成
ログアウト - 現在のセッションを無効化
- このガイドは意図的に招待、MFA、ワンタイムトークン、メール検証、パスワードリセット、およびOAuthフローを除外します。

プロフィールサービスフィーチャー

プロフィールを作成 - アイデンティティの新しいプロフィールを作成
プロフィールを取得 - IDでプロフィールを取得
プロフィールを更新 - プロフィールフィールドを更新
プロフィールを削除 - プロフィールを削除
プロフィールを検索 - プロフィールの一覧表示とフィルター
- このガイドは意図的にアバターアップロードURL、アイデンティティIDによる検索、およびフォロー/いいねフローを除外します。

2️⃣ サービスミドルウェアの作成

複数のサービスフィーチャーを統合されたミドルウェアに組み合わせる compositeService.ts ファイルを作成：

src/compositeService.ts
import cookieParser from 'cookie-parser';
import express from 'express';
import {partial} from 'ramda';

import {middlewares, features, primitives, drivers, utils} from '@nodeblocks/backend-sdk';

const {withMongo, createFileStorageDriver} = drivers;
const {getCookieTokenInfo} = utils;

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

const fileStorageDriver = createFileStorageDriver(process.env.GCP_PROJECT_ID!, process.env.GCP_BUCKET_NAME!);

const {nodeBlocksErrorMiddleware} = middlewares;
const {defService, compose} = primitives;
const {
  registerCredentialsFeature,
  loginWithCredentialsFeature,
  logoutFeature,
  createProfileFeature,
  getProfileFeature,
  editProfileFeature,
  deleteProfileFeature,
  findProfilesFeature,
} = features;

const authServiceMiddleware = compose(registerCredentialsFeature, loginWithCredentialsFeature, logoutFeature);

const profileServiceMiddleware = compose(
  createProfileFeature,
  getProfileFeature,
  editProfileFeature,
  deleteProfileFeature,
  findProfilesFeature,
);

const dataStores = {
  ...(await connectToDatabase('identities')),
  ...(await connectToDatabase('profiles')),
};

const configuration = {
  // ホストアプリがcookie-parserを登録する場合のみ 'cookie' を使用。
  authMode: (process.env.AUTH_MODE === 'cookie' ? 'cookie' : 'bearer') as 'bearer' | 'cookie',
  authSecrets: {
    authEncSecret: 'your-encryption-secret',
    authSignSecret: 'your-signing-secret',
  },
  maxFailedLoginAttempts: 5,
  accessTokenSignOptions: {expiresIn: '2h'},
  refreshTokenSignOptions: {expiresIn: '2d'},
  identity: {
    typeIds: {
      admin: '100',
      guest: '000',
      regular: '001',
    },
  },
};

const context = {
  dataStores,
  configuration,
  fileStorageDriver,
  // フィーチャー合成はprofileServiceのように自動的にこれを設定しません。
  ...(configuration.authMode === 'cookie' && {
    authenticate: getCookieTokenInfo,
  }),
};

const appMiddleware = compose(authServiceMiddleware, profileServiceMiddleware);

express()
  // 単一のネームスペース下にサービスを定義できます（例：/api/auth、/api/profiles）
  .use(cookieParser())
  .use('/api', defService(partial(appMiddleware, [context])))
  .use(nodeBlocksErrorMiddleware())
  .listen(8089, () => console.log('Server running'));

3️⃣ パターンの理解

サービス合成

合成サービスの鍵は複数のフィーチャーを組み合わせる compose 関数です：

// 個々のサービスミドルウェア
const authServiceMiddleware = compose(registerCredentialsFeature, loginWithCredentialsFeature, logoutFeature);

const profileServiceMiddleware = compose(
  createProfileFeature,
  getProfileFeature,
  editProfileFeature,
  deleteProfileFeature,
  findProfilesFeature,
);

// 結合されたミドルウェア
const appMiddleware = compose(authServiceMiddleware, profileServiceMiddleware);

共有コンテキスト

すべてのサービスは同じコンテキストオブジェクトを共有し、以下を含みます：

表示された認証とプロフィールルート用のデータベースコレクション（identities と profiles）
認証シークレットとトークンオプションを含むネストされた configuration
プロフィールレスポンスのアバターURL正規化用の fileStorageDriver
クッキー認証をオプトインする場合の authenticate 関数

後で招待トークン登録またはMFA / ワンタイムトークンログインを有効にする場合、認証データストアに invitations および/または onetimetokens を追加してください。

const context = {
  dataStores: {
    ...(await connectToDatabase('identities')),
    ...(await connectToDatabase('profiles')),
  },
  configuration: {
    authSecrets: {
      authEncSecret: 'your-encryption-secret',
      authSignSecret: 'your-signing-secret',
    },
    maxFailedLoginAttempts: 5,
    accessTokenSignOptions: {expiresIn: '2h'},
    refreshTokenSignOptions: {expiresIn: '2d'},
    identity: {
      typeIds: {
        admin: '100',
        guest: '000',
        regular: '001',
      },
    },
  },
  fileStorageDriver,
};

部分適用

Ramdaの partial 関数はミドルウェアにコンテキストを事前に適用します：

defService(partial(appMiddleware, [context]));

これはExpressで使用できるように準備されたサービスファクトリを作成します。コンテキストは常に1要素アレイとして渡してください：[{ dataStores, configuration, ... }]。

4️⃣ APIエンドポイント

合成サービスは以下のエンドポイントを公開：

この例はベアラートークンを使用します。クッキー認証を使用するには、configuration.authMode を 'cookie' に設定し、ホストアプリで cookie-parser を登録し、上記のように context.authenticate を getCookieTokenInfo に設定してください。

認証エンドポイント

POST /api/auth/register - 新しいアイデンティティを登録
POST /api/auth/login - 資格情報でログイン
POST /api/auth/logout - ログアウトしてセッションを無効化
- 認証が必要

プロフィール管理エンドポイント

POST /api/profiles - 新しいプロフィールを作成
- 認証が必要
- 管理者またはプロフィールのオーナーが作成可能
GET /api/profiles/:profileId - IDでプロフィールを取得
- 認証が必要
- 管理者またはプロフィールのオーナーが閲覧可能
PATCH /api/profiles/:profileId - プロフィールを更新
- 認証が必要
- 管理者またはプロフィールのオーナーが更新可能
DELETE /api/profiles/:profileId - プロフィールを削除
- 認証が必要
- 管理者またはプロフィールのオーナーが削除可能
GET /api/profiles - プロフィールの一覧表示/フィルター
- 認証が必要
- 管理者のみ

5️⃣ 合成サービスのテスト

# 新しいアイデンティティを登録
curl -X POST http://localhost:8089/api/auth/register \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "user@example.com",
    "password": "securepass123"
  }'

# 資格情報でログイン
curl -X POST http://localhost:8089/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "user@example.com",
    "password": "securepass123"
  }'

# プロフィールを作成（登録/ログインからidentityIdを必要とします）
curl -X POST http://localhost:8089/api/profiles \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <access-token>' \
  -d '{
    "identityId": "6dcdd50a-e0e6-445d-82e1-3da35bc2c149",
    "name": "John Doe"
  }'

# IDでプロフィールを取得
curl -X GET http://localhost:8089/api/profiles/PROFILE_ID \
  -H 'Authorization: Bearer <access-token>'

# プロフィールを更新
curl -X PATCH http://localhost:8089/api/profiles/PROFILE_ID \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <access-token>' \
  -d '{
    "name": "John Smith"
  }'

# プロフィールを削除
curl -X DELETE http://localhost:8089/api/profiles/PROFILE_ID \
  -H 'Authorization: Bearer <access-token>'

6️⃣ 環境設定

本番環境では、設定を外部化すべきです：

src/config.ts
export const config = {
  database: {
    url: process.env.MONGODB_URI || 'mongodb://localhost:27017/?authSource=admin',
    name: process.env.MONGODB_DB_NAME || 'dev',
    user: process.env.DB_USER || 'user',
    password: process.env.DB_PASSWORD || 'password',
  },
  storage: {
    gcpProjectId: process.env.GCP_PROJECT_ID || 'your-gcp-project-id',
    bucketName: process.env.GCP_BUCKET_NAME || 'your-bucket-name',
  },
  auth: {
    encSecret: process.env.AUTH_ENC_SECRET || 'your-encryption-secret',
    signSecret: process.env.AUTH_SIGN_SECRET || 'your-signing-secret',
    maxFailedAttempts: parseInt(process.env.MAX_FAILED_ATTEMPTS || '5', 10),
    accessTokenExpiresIn: process.env.ACCESS_TOKEN_EXPIRE || '2h',
    refreshTokenExpiresIn: process.env.REFRESH_TOKEN_EXPIRE || '2d',
  },
  server: {
    port: parseInt(process.env.PORT || '8089', 10),
  },
};

その後、合成サービスを更新：

src/compositeService.ts
import {drivers} from '@nodeblocks/backend-sdk';
import {config} from './config';

const {withMongo, createFileStorageDriver} = drivers;

const connectToDatabase = withMongo(
  config.database.url,
  config.database.name,
  config.database.user,
  config.database.password,
);

const fileStorageDriver = createFileStorageDriver(config.storage.gcpProjectId, config.storage.bucketName);

const context = {
  dataStores: {
    ...(await connectToDatabase('identities')),
    ...(await connectToDatabase('profiles')),
  },
  configuration: {
    authSecrets: {
      authEncSecret: config.auth.encSecret,
      authSignSecret: config.auth.signSecret,
    },
    maxFailedLoginAttempts: config.auth.maxFailedAttempts,
    accessTokenSignOptions: {expiresIn: config.auth.accessTokenExpiresIn},
    refreshTokenSignOptions: {expiresIn: config.auth.refreshTokenExpiresIn},
    identity: {
      typeIds: {
        admin: '100',
        guest: '000',
        regular: '001',
      },
    },
  },
  fileStorageDriver,
};

// ... サービスの続き

📐 ベストプラクティス

1. ドメイン別に整理

関連するフィーチャーをグループ化：

// ✅ 良い: ロジカルなグループ化
const authServiceMiddleware = compose(registerCredentialsFeature, loginWithCredentialsFeature, logoutFeature);

const profileServiceMiddleware = compose(
  createProfileFeature,
  getProfileFeature,
  editProfileFeature,
  deleteProfileFeature,
  findProfilesFeature,
);

// ❌ 避ける: 混ざった関心
const mixedMiddleware = compose(
  registerCredentialsFeature,
  createProfileFeature,
  loginWithCredentialsFeature,
  getProfileFeature,
);

➡️ 次のステップ

今、合成サービスを以下で拡張できます：

より多くのサービスを追加 - 製品、オーダー、または通知フィーチャーを含める
ミドルウェアの実装 - ロギング、レートリミッティング、またはCORSを追加
カスタムフィーチャーの実装 - ドメイン固有のビジネスロジックを作成
スキーマのオーバーライド - 組み込みフィーチャーのバリデーションをカスタマイズ
マイクロサービスの実装 - 必要に応じて別々のサービスに分割

🔗 関連リンク

カスタムサービスの作成 - 個々のサービスの構築方法を学ぶ
既存スキーマのオーバーライド - 組み込みバリデーションをカスタマイズ
プロフィールサービス - 完全なプロフィールAPIリファレンス
認証サービス - 完全な認証APIリファレンス
サービスコンポーネント - サービスアーキテクチャの理解
フィーチャーコンポーネント - フィーチャー合成の学習
エラー処理 - 合成サービスでのエラー処理

🏗️ サービスアーキテクチャ​

1️⃣ コンポーネントを理解する​

認証サービスフィーチャー​

プロフィールサービスフィーチャー​

2️⃣ サービスミドルウェアの作成​

3️⃣ パターンの理解​

サービス合成​

共有コンテキスト​

部分適用​

4️⃣ APIエンドポイント​

認証エンドポイント​

プロフィール管理エンドポイント​

5️⃣ 合成サービスのテスト​

6️⃣ 環境設定​

📐 ベストプラクティス​

1. ドメイン別に整理​

➡️ 次のステップ​

🔗 関連リンク​