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(...)。所有客户端升级后，再删除旧端点。另一种做法是将逻辑提取到一个辅助类中，供两个端点调用。