Sails 框架 `sails.sockets.leaveAll()` 详解:一键清空房间订阅与多服务器语义
Sails 框架 sails.sockets.leaveAll() 详解:一键清空房间订阅与多服务器语义
导读
在基于 Sails(Realtime MVC Framework for Node.js)构建的实时应用中,房间(Room)是组织 socket 客户端订阅的最小单元,而 sails.sockets.leaveAll() 是 sails.sockets 系列 API 中为数不多的批量退订方法:它能把某个房间的全部成员从该房间"疏散"出去,并顺带解除他们订阅的所有其他房间。本文以仓库中的官方参考文档 sails.sockets.leaveAll.md 为主体,结合 lib/hooks/pubsub/index.js 的源码实现与配套文档,完整讲解其签名、参数、实战用法、底层房间命名机制,以及多服务器环境下的回调语义,帮助你安全地用它实现聊天室解散、模型实例销毁清理等场景。
一、sails.sockets.leaveAll() 在实时通信体系中的定位
1.1 房间模型与 sails.sockets API
Sails 的实时通信建立在 Socket.IO 之上:客户端(浏览器标签页、iOS 应用、IoT 设备等)与服务器之间维护一条全双工的持久连接,服务器可以随时主动向客户端推送数据。sails.sockets 就是暴露给开发者的一层简洁服务端接口,对应参考文档 sails.sockets.md 中列出的方法族:
| 方法 | 作用 |
|---|---|
.join() |
将某个 socket 订阅到一个房间 |
.leave() |
将某个 socket 从房间退订 |
.broadcast() |
向一个或多个房间广播消息 |
.addRoomMembersToRooms() |
将某房间的全部成员批量订阅到其他房间 |
.removeRoomMembersFromRooms() |
将某房间的全部成员从其他房间批量退订 |
.leaveAll() |
将某房间的全部成员从该房间及所有其他房间退订 |
从 sails.sockets.join.md 可以得知一个关键事实:每个 socket 在连接时都会被自动订阅到一个以其 socket ID 命名的房间(例如 "BetX2G-2889Bg22xi-jy"),这使服务器可以直接按 ID 向单个 socket 定向广播。sails.sockets.leaveAll() 的例外条款正与此相关——它会解除成员的所有手动订阅房间,但保留这个与 socket ID 同名的自动房间。
1.2 与 .leave()、.removeRoomMembersFromRooms() 的差异
.leave(socket, roomName)只让单个 socket 离开一个房间(见 sails.sockets.leave.md);.removeRoomMembersFromRooms(sourceRoom, destRooms)让 sourceRoom 的成员从指定的一个或多个其他房间退订(见 sails.sockets.removeRoomMembersFromRoom.md);.leaveAll(roomName)则更"激进":roomName 房间的所有成员,除了离开 roomName 自身,还会被强制离开它们当前订阅的每一个其他房间。
这种"以房间为维度、全量清退"的行为,使 leaveAll() 成为房间生命周期终结时的理想清理工具。事实上,根据 migration-guide-0.12.md 与 To0.12.md 的记录,.leaveAll() 与 .addRoomMembersToRooms()、.removeRoomMembersFromRooms() 一起,是 Sails v0.12 新增的一批 sails.sockets 方法。
二、API 签名与参数详解
2.1 方法签名
sails.sockets.leaveAll(roomName, cb);
2.2 参数说明
| 参数 | 类型 | 详情 |
|---|---|---|
roomName |
((string)) | 要疏散的房间。注意:该房间的成员会被强制离开他们订阅的所有房间,而不仅仅是这一个房间。 |
cb |
((function?)) | 可选回调。当操作在当前服务器上完成时(见下文"多服务器语义"),或遇到致命错误时被调用。出错时以单个参数(err)调用。 |
与 .join() / .leave() 不同,leaveAll() 的第一参数不接收 socket 或 req——它面向的是"房间里的一群人",而不是某一个 socket,因此天然适合服务端后台任务(定时清理、管理命令)而非单个客户端请求。
2.3 参数校验与容错
虽然仓库内 leaveAll() 的具体实现位于 sockets 底层(sails.sockets 方法由 sockets 相关模块提供),但从兄弟方法的行为可以推断出通用约定:
roomName必须是非空字符串;如果房间不存在或已无成员,操作仍然是安全的(空操作);cb在正常情况下以无参形式调用(表示成功),出错时以(err)调用;在控制器中收到err时应返回 5xx 响应,例如res.serverError(err)。
三、实战示例:在控制器中使用 sails.sockets.leaveAll()
以下示例直接继承自官方参考文档 sails.sockets.leaveAll.md 的原始代码,并补充了类型检查与注释:
// 在某个控制器(Controller)的动作(Action)中:
unsubscribeFunRoomMembersFromEverything: function(req, res) {
sails.sockets.leaveAll('funRoom', function(err) {
if (err) { return res.serverError(err); }
// 至此,所有订阅在 "funRoom" 中的 socket:
// 1) 已从 "funRoom" 退订;
// 2) 也已从它们订阅的其他所有房间退订。
// (但它们与各自 socket ID 同名的自动房间不受影响,
// 因此仍可通过 sails.sockets.broadcast(socketId, ...) 定向联系到它们。)
return res.ok();
});
}
3.1 增强示例:安全地"解散"一个聊天室
假设你的应用用 chatroom:<id> 命名房间来承载聊天室,解散聊天室时既要清空成员订阅,又要避免重复调用:
// 在 /api/controllers/ChatroomController.js 中
destroyChatroomAndEvictMembers: function(req, res) {
var chatroomId = req.param('id');
if (!chatroomId) { return res.badRequest('`id` is required.'); }
var roomName = 'chatroom:' + chatroomId;
// 1. 让所有成员离开该房间及其所有其他房间
sails.sockets.leaveAll(roomName, function(err) {
if (err) { return res.serverError(err); }
// 2. 此时可以向这些成员发送一条“房间已关闭”的告别消息。
// 注意:成员刚被清退,不应再向 roomName 广播,
// 而应使用 broadcast() 配合每位成员的 socket ID(即其自动房间名)。
return res.ok({ message: 'Chatroom ' + chatroomId + ' closed; all members evicted.' });
});
}
提示:由于
leaveAll()会解除成员的所有手动订阅,若你的业务还希望这些成员继续保留在某个"全局大厅"房间,应在调用leaveAll()之后,用 sails.sockets.join() 或 sails.sockets.addRoomMembersToRooms() 重新建立所需订阅。
四、源码级原理:房间命名与批量退订的调用链
4.1 pubsub hook:sails.sockets 的核心使用方
leaveAll() 所属的 sails.sockets 是底层 socket 抽象,而 Sails 的 pubsub hook 是它最重要的消费者之一。从源码看,pubsub hook 的初始化(initialize)有两个硬性依赖:sails.hooks.sockets 与 sails.hooks.orm,任一缺失都会导致 hook 被禁用或直接报错(见 lib/hooks/pubsub/index.js)。也就是说,sails.sockets.* 方法的可用性以 sockets hook 被启用为前提。
4.2 房间命名规则
pubsub hook 为每个模型生成了两类房间名,源码中有明确定义:
- 实例房间(
_room(id)):'sails_model_' + this.identity + '_' + id + ':' + this.identity(见 lib/hooks/pubsub/index.js); - 类房间(
_classRoom()):'sails_model_create_' + this.identity(见 lib/hooks/pubsub/index.js)。
这套命名规则解释了为什么"每个 socket 的自动房间名就是其 ID"这类约定只适用于 sails.sockets 层,而资源型 pubsub 的房间则是"模型实例"维度。当你调用 sails.sockets.join()、sails.sockets.leave()、sails.sockets.broadcast() 时,操作的就是这些命名房间(例如 sails.sockets.join(socket, self._room(id)) 见 lib/hooks/pubsub/index.js)。
4.3 模型销毁时的批量清退:.leaveAll() 的姊妹用法
在 pubsub hook 的 _retire(model) 方法中(见 lib/hooks/pubsub/index.js),当模型实例被销毁时,Sails 会调用:
sails.sockets.removeRoomMembersFromRooms(self._classRoom(), self._room(id));
这行代码的意图是:把所有订阅了该类房间(class room)的 socket,从被销毁实例的实例房间(instance room)中批量退订,避免向已不存在的记录继续推送。这与 leaveAll() 同属"Sails 批量管理房间成员"的工具族,只是粒度不同——removeRoomMembersFromRooms 是"从一个房间拿出成员、退订到指定房间",而 leaveAll() 是"拿出成员、退订到所有房间"。理解这两者的对称关系(对应新增方法 addRoomMembersToRooms,见 lib/hooks/pubsub/index.js),可以帮助你在自定义逻辑中按需组合使用。
4.4 底层实现:Socket.IO 与 sails.io
根据 sails.sockets.md 的说明,sails.sockets.* 方法基于 Sails 内置的 Socket.IO 实例(即 sails.io)实现。官方建议几乎永远不要直接操作 sails.io,而是统一通过 sails.sockets.* 调用——leaveAll() 正是这一抽象层的典型代表:它把"遍历房间成员 + 逐个退订 + 多服务器同步"这类易错细节封装成一行调用。
五、多服务器(集群)环境下的语义与注意事项
5.1 回调仅代表"当前服务器已完成"
官方文档对 cb 的说明非常关键:
在多服务器环境中,回调函数(
cb)会在.leaveAll()调用在当前服务器上完成时执行。这并不保证集群中的其他服务器已经完成了该操作。
也就是说,cb 不是"全集群一致性"的屏障。如果你的业务逻辑在回调里立刻向这些成员广播消息,而他们此前订阅的其他房间数据尚未在集群内同步完毕,理论上可能出现短暂的不一致窗口。
5.2 无回调调用的 "volatile" 特性
Multi-server environments.md 进一步指出:在集群环境中,不带回调的 socket 方法可能是 volatile 的——即使代码看起来立即执行完成,实际传播也可能需要不确定的时间。因此,不要在无回调的 leaveAll() 之后立刻假设订阅关系已在全集群生效。
5.3 集群部署的正确姿势
要让 sails.sockets 系列方法在多服务器环境下如单机一样工作,需要:
- 准备一个 Redis 实例(官方文档建议使用托管 Redis);
- 安装
@sailshq/socket.io-redis作为应用依赖; - 在
config/sockets.js中将sails.config.sockets.adapter设置为@sailshq/socket.io-redis,并配置host、password等字段指向 Redis 实例。
完成上述配置后,leaveAll() 等方法的房间成员信息将通过 Redis 在集群内共享,无论代码运行在哪台服务器、目标 socket 连接在哪台服务器,行为都是一致的(这一结论同样适用于 .join() / .leave(),参见 sails.sockets.join.md 中的说明)。
5.4 边界情况清单
- 自动房间不受影响:每个 socket 与其 ID 同名的自动房间不会被
leaveAll()解除,因此仍可通过sails.sockets.broadcast(socketId, ...)定向送达消息(参考 sails.sockets.join.md 与 sails.sockets.broadcast.md 中的 Notes)。 - 操作幂等:对空房间或不存在房间调用是安全的,回调最终仍会被调用。
- 错误处理:
cb出错时以(err)形式调用,应在回调内显式处理(如res.serverError(err)),不要吞掉异常。
六、延伸阅读
- 方法族总览与弃用说明:sails.sockets.md
- 单 socket 订阅 / 退订:sails.sockets.join.md、sails.sockets.leave.md
- 批量订阅 / 退订兄弟方法:sails.sockets.addRoomMembersToRooms.md、sails.sockets.removeRoomMembersFromRoom.md
- 定向广播与 socket ID 获取:sails.sockets.broadcast.md、sails.sockets.getid.md
- 实时通信概念与服务端编程指南:Realtime.md、On the server.md、Multi-server environments.md
- 底层实现参考:lib/hooks/pubsub/index.js(房间命名、批量成员管理调用链);版本引入记录:migration-guide-0.12.md