serverpod-endpoints

Serverpod エンドポイント

Endpoint にインスタンスメソッドを追加します。最初のパラメーターは Session、戻り値は Future<T>（リアルタイムデータのストリーミングでは Stream<T>）です。サーバーの lib/ 以下なら、どこに配置してもかまいません。保存すると Serverpod runner がクライアントを再生成します。runner がない場合は、serverpod generate を実行してください。

エンドポイントの定義

import 'package:serverpod/serverpod.dart';

class ExampleEndpoint extends Endpoint {
  Future<String> hello(Session session, String name) async {
    return 'Hello $name';
  }
}

クライアント名はクラス名から Endpoint サフィックスを除いて決まります（ExampleEndpoint → example）。

クライアントから呼び出す

var result = await client.example.hello('World');

クライアントは一度だけ初期化します。

final serverUrl = await getServerUrl();
client = Client(serverUrl)
  // When using Flutter:
  ..connectivityMonitor = FlutterConnectivityMonitor()
  // When using authentication:
  ..authSessionManager = FlutterAuthSessionManager();

対応するパラメーターと戻り値の型

• プリミティブ型：bool、int、double、String
• Duration、DateTime（UTC）、ByteData、UuidValue、Uri、BigInt
• 生成されたシリアライズ可能なモデル（.spy.yaml から生成）
• List、Map、Set、Record — 上記の型で厳密に型指定します

デフォルトのリクエストサイズ上限は 512 kB です。設定の maxRequestSize で変更できます。大きなファイルにはファイルアップロード API を使用してください。

セッション

データベースアクセス（session.db、Model.db）、キャッシュ（session.caches）、ログ、リクエストコンテキストを提供します。リクエストの完了後に使用するためにキャプチャしないでください。

コード生成から除外する

• エンドポイント全体： クラスに @doNotGenerate を指定します。
• 単一のメソッド： メソッドに @doNotGenerate を指定します。

エンドポイントの継承

• 具象クラスが具象クラスを継承： クライアントには両方が含まれます。サブクラスは独自のメソッドと継承したメソッドを公開します。
• 抽象エンドポイント： 登録されません。具象サブクラスのみが公開されます。
• 親クラスに @doNotGenerate を指定： 親クラスは非表示になり、サブクラスは継承したメソッドを実装するクライアントを取得します。

オーバーライドは可能です。同じシグネチャーで動作を変更しても、クライアントコードは変わりません。

後方互換性

古いアプリのバージョンから、引き続きサーバーが呼び出されることがあります。パラメーター名は変更しないでください（REST API では名前で渡されます）。メソッドの削除、必須パラメーターの追加、シグネチャーの変更は避け、新しいメソッドまたは省略可能な名前付きパラメーターを追加してください。

エンドポイントの API を破壊的に変更する必要がある場合は、バージョン付きエンドポイントを作成します。

@Deprecated('Use TeamV2Endpoint instead')
class TeamEndpoint extends Endpoint {
  Future<TeamInfo> join(Session session) async { /* ... */ }
}

class TeamV2Endpoint extends TeamEndpoint {
  @override
  @doNotGenerate
  Future<TeamInfo> join(Session session) async => throw UnimplementedError();

  Future<NewTeamInfo> joinWithCode(Session session, String invitationCode) async {
    // New implementation
  }
}

古いクライアントでは client.team.join() を使用し、新しいクライアントでは client.teamV2.joinWithCode(...) を使用します。すべてのクライアントがアップグレードした後で、古いエンドポイントを削除してください。別の方法として、両方のエンドポイントから呼び出せるヘルパークラスにロジックを切り出せます。