数据订阅与实时更新

最后更新：2026 年 7 月 16 日

任何数据查询都可以被订阅。订阅会按查询所定义的形状，把服务端数据复制到客户端。第一次送达的是完整的数据对象；此后只要服务端数据发生变化，Delta 就会立即送达所有已订阅的客户端。

信息

用订阅来保持本地那份服务端数据副本的时效性 —— 通过响应式的 Delta，并由 JSONPatch 优化同步流量。

---

创建订阅

订阅建立在查询对象之上。

var player = PlayServ.Model<Player>().Key(playerId);
var subscription = player.Listen();

---

送达模型

第一条消息按查询的形状送来完整对象。

服务端数据变化时，Delta 会毫不延迟地送达所有 listener，改动会自动应用到本地数据对象上。如果你需要掌控这个过程，就订阅 Update 这个 Event。

---

显式观察更新

在订阅上使用 Wait<Update>，即可在数据变化时自行处理更新。

subscription.Wait<Update>(e => {
  // Called whenever the data is updated
  // e.New — the new version of the data
  // e.Old — the previous version of the data
});

---

传输优化：JSONPatch

为了优化同步过程中的流量，PlayServ 使用 JSONPatch。JSONPatch 描述的是应当施加到数据对象上的改动。即便数据库以 key=value 的形式存储数据，这个办法依然有效。

---

取消订阅

要取消订阅，调用 Stop()。

subscription.Stop();

---

Session 失步后的订阅恢复

Session 失步之后 —— 也就是 Session 进入 Offline 或 Recovering 再回到 Active —— 失步那一刻处于活跃状态的所有订阅都必须被恢复。这一步由 SDK 自动完成。

---

下一步

• Data Mutation & Model Extending —— 把数据改动写回服务端
• Query Language & Data Retrieval —— 查询形状、Key/Where/With，以及仅限表达式的约束
• Session Lifecycle & States —— 恢复规则所引用的 Session 状态 Offline、Recovering、Active