serverpod-endpoints

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Serverpod Endpoints

Serverpod 端点

Extend

Endpoint

with instance methods; first parameter is

Session

, return

Future<T>

(or

Stream<T>

for real-time data streaming). Place anywhere under server

lib/

. If

serverpod start

is not running with hot-reload, run

serverpod generate

to update the client.

通过实例方法扩展

Endpoint

；第一个参数为

Session

，返回

Future<T>

（若为实时数据流则返回

Stream<T>

）。可放置在服务端

lib/

目录下的任意位置。如果

serverpod start

未启用热重载，请运行

serverpod generate

来更新客户端。

Defining an endpoint

定义端点

dart

import 'package:serverpod/serverpod.dart';

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

Client name is derived from the class name minus

Endpoint

suffix (

ExampleEndpoint

→

example

dart

import 'package:serverpod/serverpod.dart';

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

客户端名称由类名去掉

Endpoint

后缀派生而来（

ExampleEndpoint

→

example

）。

Calling from the client

从客户端调用

dart

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

Client initialized once:

dart

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

dart

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

客户端只需初始化一次：

dart

final serverUrl = await getServerUrl();
client = Client(serverUrl)
  // 使用Flutter时：
  ..connectivityMonitor = FlutterConnectivityMonitor()
  // 使用身份验证时：
  ..authSessionManager = FlutterAuthSessionManager();

Supported parameter and return types

支持的参数和返回类型

Primitives:
```
bool
```
,
```
int
```
,
```
double
```
,
```
String
```

Duration

DateTime

(UTC),

ByteData

UuidValue

Uri

BigInt

Generated serializable models (from
```
.spy.yaml
```
)
```
List
```
,
```
Map
```
,
```
Set
```
,
```
Record
```
— strictly typed with the above

Default request size limit: 512 kB. Change with

maxRequestSize

in config. Use the file upload API for large files.

基本类型：
```
bool
```
、
```
int
```
、
```
double
```
、
```
String
```

Duration

、

DateTime

（UTC）、

ByteData

、

UuidValue

、

Uri

、

BigInt

生成的可序列化模型（来自
```
.spy.yaml
```
）
```
List
```
、
```
Map
```
、
```
Set
```
、
```
Record
```
—— 需严格使用上述类型进行类型标注

默认请求大小限制：512 kB。可通过配置中的

maxRequestSize

修改。大文件请使用文件上传API。

Session

Provides: database access (

session.db

Model.db

), cache (

session.caches

), logging, request context. Do not capture for use after the request completes.

提供：数据库访问（

session.db

、

Model.db

）、缓存（

session.caches

）、日志记录、请求上下文。请勿在请求完成后捕获并使用Session。

Excluding from code generation

排除代码生成

Entire endpoint:
```
@doNotGenerate
```
on the class.
Single method:
```
@doNotGenerate
```
on the method.

整个端点： 在类上添加
```
@doNotGenerate
```
注解。
单个方法： 在方法上添加
```
@doNotGenerate
```
注解。

Endpoint inheritance

端点继承

Concrete extends concrete: Client gets both; subclass exposes own + inherited methods.
Abstract endpoint: Not registered; only concrete subclass is exposed.
Parent with
@doNotGenerate
: Parent hidden; subclass gets a client implementing inherited methods.

Overriding is allowed: same signature, different behavior, client code unchanged.

具体类继承具体类： 客户端会获取两者的方法；子类会暴露自身及继承的方法。
抽象端点： 不会被注册；仅具体子类会被暴露。
父类带有
@doNotGenerate
：父类会被隐藏；子类的客户端会实现继承的方法。

允许重写：签名相同，行为不同，客户端代码无需修改。

Backward compatibility

向后兼容性

Older app versions may still call your server. Do not rename parameters (REST API passes by name). Do not delete methods, add required parameters, or change signatures; add new methods or optional named parameters instead.

When you must break an endpoint's API, create a versioned endpoint:

dart

@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
  }
}

Old clients use

client.team.join()

; new clients use

client.teamV2.joinWithCode(...)

. Remove the old endpoint after all clients upgrade. Alternative: extract logic into a helper class callable from both endpoints.

旧版本应用可能仍会调用你的服务端。请勿重命名参数（REST API按名称传递参数）。请勿删除方法、添加必填参数或修改签名；应添加新方法或可选命名参数。

当必须打破端点API时，请创建版本化端点：

dart

@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 {
    // 新实现
  }
}

旧客户端使用

client.team.join()

；新客户端使用

client.teamV2.joinWithCode(...)

。待所有客户端升级后再移除旧端点。替代方案：将逻辑提取到可从两个端点调用的辅助类中。