メインコンテンツまでスキップ
バージョン: 0.14.0 (最新)

📂 カテゴリ

カテゴリは、categoryService を介して一般向けのカテゴリ参照と管理者専用の作成・編集・ステータス変更・削除操作を提供します。

スタート here​

本サービスを /api 以下にマウントします。MongoDB の categories コレクションと identities コレクション、authSecrets、および保護された変更用の設定済みアイデンティティタイプ ID が必要です。defService は返されるルーターに JSON パースをインストールします。authMode が 'cookie' の場合のみ、サービス前に cookie-parser を登録してください。

エクスポートされた categoryService は Service<CategoryServiceDataStore, CategoryServiceConfiguration> であり、(dataStores, configuration, drivers?) から Express ルーターを返します。

import express from 'express';
import { services } from '@nodeblocks/backend-sdk';

const app = express();
app.use('/api', services.categoryService(
  { categories, identities },
  {
    authSecrets: {
      authEncSecret: process.env.AUTH_ENC_SECRET!,
      authSignSecret: process.env.AUTH_SIGN_SECRET!,
    },
    authMode: 'bearer',
    identity: { typeIds: { admin: 'admin-type-id', guest: 'guest-type-id', regular: 'regular-type-id' } },
  },
));
設定デフォルト / ソースの動作効果
authSecrets.authEncSecret / authSecrets.authSignSecretサービス設定で必須；認証ユーティリティに渡される実行時の認証設定として必須。
identity.typeIds.admin保護ルート認可で必須；checkIdentityType(['admin']) で読み込まれるカテゴリを変更できるアイデンティティタイプを選択。
authMode省略または 'bearer' は getBearerTokenInfo を選択；'cookie' は getCookieTokenInfo を選択保護ルートのトークン転送方法を変更。

公開ルートは認証バリデータを構成しません。保護されたルートは isAuthenticated() と checkIdentityType(['admin']) を実行します。クッキーモードの場合、ホストアプリケーションでクッキーミドルウェアが必要です。

サービスの実行子は res.json(result) 経由で通常のハンドラ値を返し、200 ステータスを供給します。{ statusCode: 204 } を返すターミネータは代わりに res.status(204).json(undefined) を使用します。カテゴリにはドメインブロックエクスポートがありません；そのルートはカテゴリハンドラと共有エンティティ・ページネーションユーティリティを使用します。

よくあるタスク​

タスク開始点契約
カテゴリを1件取得または一覧取得公開ルートルート と リストスキーマ
カテゴリの作成または編集管理者アクセストークンまたはクッキー作成、更新
ステータス変更または削除管理者アクセストークンまたはクッキーステータスと削除ルート
選択したエンドポイントを構成フィーチャーコンポーザフィーチャー

Bearer HTTP ワークフロー​

保護されたエンドポイントを使用する前に、シェル変数を宣言してください：

export ADMIN_ACCESS_TOKEN='replace-with-an-admin-access-token'
export CATEGORY_ID='replace-with-a-category-id'

curl 'http://localhost:8080/api/categories?name=Electronics&page=1&limit=20'

curl -X POST 'http://localhost:8080/api/categories' \
  -H "authorization: Bearer $ADMIN_ACCESS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"name":"Electronics","description":"Devices and accessories","status":"active"}'

curl -X POST "http://localhost:8080/api/categories/$CATEGORY_ID/disable" \
  -H "authorization: Bearer $ADMIN_ACCESS_TOKEN"

一覧は { data, metadata: { pagination } } とともに 200 を返します；省略されたページネーション値はページ 1 とリミット 10 がデフォルトです。作成は正規化されたカテゴリとともに 200 を返します。無効化は空の 204 で成功します；存在しないカテゴリは doesCategoryExist により 404 で拒否されます。ルートマトリックス と リクエストスキーマ を参照してください。

authMode: 'cookie' の場合、カテゴリマウント前に cookie-parser を登録し、Authentication クッキーワークフロー 経由でアクセスクッキーを取得してから、Authorization ヘッダーの代わりに保存されたクッキーを送信してください：

export CATEGORY_ID='replace-with-a-category-id'

curl -X PATCH "http://localhost:8080/api/categories/$CATEGORY_ID" \
  -b cookies.txt \
  -H 'content-type: application/json' \
  -d '{"description":"Updated category description"}'

このリクエストは Bearer ワークフローと同じ管理者アイデンティティを必要とし、成功時に正規化されたカテゴリを返します。

カスタムフィーチャー構成​

この断片は作成・一覧・ステータス操作のみをマウントします。ホストは categories、identities、認証シークレット、およびアイデンティティタイプ ID を提供する必要があります。defService は JSON パースをインストールし、クッキーモードは追加で cookie-parser が必要です。

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

const composeCategoryRoutes = primitives.compose(
  features.createCategoryFeature,
  features.findCategoriesFeatures,
  features.editCategoryStatusFeatures,
);

const configuration = {
  authSecrets: {
    authEncSecret: process.env.AUTH_ENC_SECRET!,
    authSignSecret: process.env.AUTH_SIGN_SECRET!,
  },
  identity: {
    typeIds: {
      admin: 'admin-type-id',
      guest: 'guest-type-id',
      regular: 'regular-type-id',
    },
  },
};

const categoryRouter = primitives.defService(partial(composeCategoryRoutes, [{
  authenticate: utils.getBearerTokenInfo,
  configuration,
  dataStores: { categories, identities },
}]));

app.use('/api', categoryRouter);

クッキー転送の場合、utils.getCookieTokenInfo に置換し、ホストアプリケーションで cookie-parser を登録してください。

リファレンスマップ​

ページ目的
フィーチャースキーマとルートの構成。
ハンドラパイプライン操作とレスポンスターミネータ。
ルート正確なエンドポイント、アクセス、レスポンス契約。
スキーマリクエストと再利用可能なオブジェクト契約。
バリデータカテゴリ存在チェックと共有アクセスガード。

SDK にカテゴリ固有のブロックレイヤーのエクスポートがないため、カテゴリのブロックページはありません。

関連モジュール​

サービスレベルの使用については Category service、アクセストークンとクッキーの設定については Authentication、ルート検証については validator component、共有エラーレスポンスについては error handling を参照してください。