API リファレンス

このページでは、よく使う公開の API、戻り値、制約を用途ごとに一覧にしています。完全なパラメーター、オーバーロード、補助の型は、インストールされた宣言を参照してください。データベースのリファレンスの章へのリンクは下にあります。作業の流れについては アプリ開発 と フレームワーク を参照してください。

概念のガイドは フレームワーク を参照してください。スキーマ、照会、トランザクションは データベースのトピック で学べます。

公開のインポートの入口

ソースのディレクトリと npm のエクスポートは異なることがあります。依存関係の非公開の src/ やビルドのファイルではなく、package.json で宣言された公開の入口からインポートしてください。パッケージの用途については Core とツールのパッケージ一覧 を参照してください。

サービスコンテナと依存性注入

クライアントとサーバーは同じサービスコンテナの概念を使い、それぞれのランタイムで別々のインスタンスを持ちます。

import { createServiceToken, ServiceContainer } from '@nocobase/service-provider';

interface GreetingService {
  greet(name: string): string;
}

const greetingToken = createServiceToken<GreetingService>('example.greeting');
const services = new ServiceContainer();
services.singleton(greetingToken, () => ({
  greet: (name) => `Hello, ${name}`,
}));

const message = services.resolve(greetingToken).greet('NocoBase');
// Hello, NocoBase

1 つのコンテナで同じトークンを 2 回結び付けることはできません。同じ名前で新しいトークンを作っても同じ識別子にはならないため、利用側は提供側がエクスポートしたトークンをインポートする必要があります。シングルトンのファクトリーは同期です。非同期の初期化はライフサイクルのフックで行います。

アプリでは、ランタイムの既存のコンテナを使います。React のコンポーネントは useService(token) でサービスを解決し、サーバーのコードでは一般に app.container.resolve(token) を使います。React の Provider はコンポーネントツリーのコンテキストを提供するもので、ServiceProvider とは異なります。登録と実行の順序については ServiceProvider を参照してください。

クライアントのリクエスト

アプリの React のコンポーネントの中で useApiClient() を呼び出し、設定済みのクライアントを取得します。独立した呼び出し側は、@nocobase/api-client を直接の依存関係として宣言し、その createApiClient({ baseURL }) を使えます。アプリのクライアントも、これらのインターフェースと型を再エクスポートしています。

リクエストのオプションには、path、method、query、headers、signal、credentials があります。JSON のボディには json を、それ以外のボディには body を使い、両方を設定しないでください。既定のメソッドは GET、既定の credentials は include です。

import type { ApiClient } from '@nocobase/app-client';

type Announcement = { id: string; title: string };

export async function loadAnnouncements(api: ApiClient) {
  const response = await api.request<{ data: Announcement[] }>({
    path: '/announcements',
    method: 'GET',
    query: { limit: 20 },
  });
  return response.data;
}

これは、{ data: [...] } を返すお知らせのエンドポイントをアプリが提供していることを前提にしています。request() は包みを保ち、TypeScript のジェネリクスはレスポンスを検証しません。リモートの repository() の呼び出しには対応するサーバーのエンドポイントが必要で、データベースのテーブルを作成しても HTTP で公開されることはありません。身元、入力の検証、データの権限は、引き続きサーバーが扱います。

サーバーの HTTP

ルートのファクトリーはアプリを受け取り、Hono の Router を返します。宣言は、アプリまたはプラグインの拡張の入口で登録します。通常の API の接頭辞は /api で、アプリのベースパスも考慮します。

別々の依存関係のコピーによるメタデータのレジストリーの混在を避けるため、OpenAPI の記述のヘルパーは @nocobase/app-server/router からインポートします。アクセスのチェックが有効な場合、アプリは /api/swagger で画面を、/api/swagger/docs でドキュメントを公開します。既定のテンプレートでのアクセスは引き続き身元と権限のチェックに従い、自動で匿名のエンドポイントのディレクトリになるわけではありません。

完全な例については、HTTP ルートと API と プラグインのサーバー API を参照してください。

設定

public は、ブラウザーから読み取れる、セクションからの相対の末端のパスを宣言します。似た名前のクライアントのファイルがあっても、サーバーの設定が自動で公開されることはありません。優先順位、例、環境変数については 設定リファレンス を参照してください。

データベースの管理

アプリでは、既存の databaseManagerToken を解決します。独立したツールやテストでは、自分で DatabaseManager を作成して解放します。

db.builder() はメソッドで、connection.builder はプロパティです。CollectionBuilder は型としてだけエクスポートされています。new CollectionBuilder() を呼び出すのではなく、データベースからインスタンスを取得してください。

Repository の戻り値

同じ findMany() の照会で、await と非同期の反復を混ぜたり、繰り返し消費したりしないでください。一括の更新と削除には、フィルターまたは明示的な all: true が必要です。

context は照会の変数を提供するもので、トランザクションのハンドルではありません。Repository はコールバックのトランザクションの接続から取得します。外側の接続の Repository が、自動でトランザクションに参加することはありません。Builder の transaction() メソッドも、現在データベースのトランザクションを開始しません。

Repository は、現在の HTTP のユーザーを推測しません。認可からポリシーを導き、withPolicy() を適用して行とフィールドの権限を設けます。ユーザーが指定したフィルターは認可ではありません。データの照会と操作 を参照してください。

完全な宣言とデータベースの章

• データベースの API の目次
• 公開のエクスポートの一覧
• DatabaseManager
• 接続とダイアレクトの取り決め
• マイグレーションとシード
• コレクション、フィールド、リレーション、メタデータ
• Query
• Repository
• 権限のポリシー
• トランザクション
• データベースのイベント
• テストのツール

これらのリンクは Core のリビジョン 015404ecd0db（2026-10-26）に固定されており、完全なシグネチャー、エクスポートの境界、既知の制限を含みます。パッケージ一覧 は、同じリビジョンのクライアント、HTTP、設定のソースにリンクしています。ロックファイルとローカルにインストールされた型も確認してください。パッケージが 1 つのバージョン番号を共有しているわけではありません。

サービス、リクエスト、設定の例は、型チェックと実行に合格しています。メモリ上の SQLite でのチェックでも、1 件の変更の戻り値、照会、トランザクションのロールバックを、既定のテンプレート beta.83 のインストール済みの依存関係で、外部のデータベースに接続せずに検証しています。