PartyKit项目Party.Server API详解
概述
PartyKit是一个用于构建实时协作应用的工具集，其中Party.Server是其核心API之一。本文将深入解析Party.Server的各个组成部分，帮助开发者更好地理解和使用这一强大的实时通信框架。
Party.Server基础
Party.Server是PartyKit服务器的核心接口，每个PartyKit服务器都是一个实现了该接口的TypeScript模块。
import type * as Party from "partykit/server";
export default class Server implements Party.Server {}
构造函数
Party.Server构造函数接收一个Party.Room实例，提供对房间状态和资源的访问：
constructor(readonly room: Party.Room) {
// 初始化逻辑
}
核心生命周期方法
1. onStart方法
在服务器启动或从休眠状态唤醒后调用，在第一个onConnect或onRequest之前执行。适合用于异步初始化操作：
async onStart() {
// 加载存储数据或获取配置
}
2. onConnect方法
当新WebSocket连接建立时触发：
async onConnect(connection: Party.Connection, ctx: Party.ConnectionContext) {
// 处理新连接
}
3. onMessage方法
当接收到客户端或其它连接方发送的消息时触发：
async onMessage(message: string | ArrayBuffer, sender: Party.Connection) {
// 处理消息
}
4. onClose方法
当WebSocket连接关闭时触发：
async onClose(connection: Party.Connection) {
// 清理连接相关资源
}
5. onError方法
当连接因错误关闭时触发：
async onError(connection: Party.Connection, error: Error) {
// 错误处理逻辑
}
HTTP请求处理
onRequest方法
处理对房间URL的HTTP请求，返回标准的Fetch API Response：
async onRequest(req: Party.Request) {
return new Response("Hello World", { status: 200 });
}
高级功能
1. 休眠选项
通过设置hibernate选项控制服务器在请求/消息之间的内存管理：
readonly options = {
hibernate: false // 默认为false
};
2. 连接标签
通过getConnectionTags方法为连接添加元数据，便于后续筛选：
getConnectionTags(connection: Party.Connection, ctx: Party.ConnectionContext) {
return [ctx.request.cf?.country ?? "unknown"];
}
3. 静态拦截方法
在请求到达房间前进行拦截处理：
static async onBeforeRequest(req: Party.Request) {
// 修改请求或直接返回响应
}
房间资源管理
Party.Room实例提供对房间状态和资源的访问：
1. 存储系统
提供异步键值存储，适合持久化数据：
// 写入数据
await this.room.storage.put("key", value);
// 读取数据
const value = await this.room.storage.get("key");
2. 广播消息
向所有连接客户端发送消息：
this.room.broadcast("系统消息", [排除的连接ID数组]);
3. 连接管理
获取和筛选当前连接：
// 获取所有连接
const allConnections = [...this.room.getConnections()];
// 按标签筛选连接
const taggedConnections = [...this.room.getConnections("tag")];
连接对象详解
Party.Connection封装了WebSocket连接：
1. 连接状态管理
// 设置状态
connection.setState({ user: "jani" });
// 读取状态
const username = connection.state?.user;
2. 基本操作
connection.send("消息内容"); // 发送消息
connection.close(); // 关闭连接
最佳实践建议
-
状态管理：小量临时数据使用连接状态(connection.state)，大量或持久化数据使用房间存储(room.storage)
-
错误处理：始终实现onError方法以处理连接异常
-
资源清理：在onClose中释放连接相关资源
-
性能优化：对不常使用的房间启用hibernate选项
-
安全考虑：使用onBeforeRequest/onBeforeConnect进行请求验证和过滤
总结
Party.Server API提供了构建实时协作应用所需的全套工具，从基础的连接管理到高级的状态持久化和消息广播。通过合理利用其生命周期方法和资源管理功能，开发者可以构建高效、可靠的实时应用系统。
