Sails 实时通信编程指南:深入掌握 `sails.sockets` 方法集(join / broadcast / blast / 房间订阅)

原创2026-09-20 14:46:101,458 阅读
文章标签:后端

Sails 实时通信编程指南:深入掌握 sails.sockets 方法集(join / broadcast / blast / 房间订阅)

导读

sails.sockets 是 Sails 框架内置的实时通信接口集合,它为服务端向已连接的 socket 客户端主动推送事件与数据提供了一套统一、简单的 API,是构建聊天室、通知中心、实时仪表盘等功能的基石。本文以官方参考文档为主线,逐一拆解 sails.sockets.* 全部 8 个方法的签名、参数与实战示例,并结合当前仓库中 pubsub hook 的源码实现,说明这些方法如何支撑更高层的 Resourceful PubSub 与蓝图(blueprint)API,帮助你写出可直接运行、且能平滑扩展至多服务器集群的实时应用代码。


一、认识 sails.sockets:Sails 实时消息的统一入口

Sails 通过 sails.sockets.* 暴露一组方法,为与服务器建立连接的 socket 客户端提供简单的实时通信接口。其核心价值在于:服务端可以主动把事件和数据推送给已连接的客户端,而无需等待客户端发起 HTTP 请求。无论客户端来自浏览器标签页、iOS 应用,还是家中的物联网设备,这些方法都一视同仁、开箱即用。

1.1 与底层 Socket.IO 的关系

这些方法的底层实现基于 Sails 内置的一个 Socket.IO 实例,该实例以 sails.io 的形式直接暴露(详见仓库文档 advanced-usage 中关于 sails.io 的说明)。从当前仓库的 package.json 可以看到,项目直接依赖了 "socket.io" 以及封装层 "sails-hook-sockets": "^3.0.0":

// package.json(节选)
"socket.io": "...",
"sails-hook-sockets": "^3.0.0",
"socket.io-client": "2.0.3"

官方强烈建议:几乎永远不要直接使用 sails.io,而应该调用 sails.sockets.* 上的方法。sails.sockets 在 Socket.IO 之上做了统一封装,尤其是为多服务器部署提供了额外的内建支持。

1.2 与 Resourceful PubSub 的分层关系

除了 sails.sockets.*,某些场景还可以使用 Resourceful PubSub 方法,后者是更高一层的抽象,被 Sails 内建的 blueprint API 所使用。两者的关系从当前仓库 lib/hooks/pubsub/index.js 的源码中可以看得非常清楚——pubsub hook 正是通过调用 sails.sockets 的方法来实现自己的高层能力:

  • 第 228 行:sails.sockets.broadcast( room, self.identity, data, socketToOmit );
  • 第 279 行:sails.sockets.join( socket, self._room(id) );
  • 第 329 行:sails.sockets.leave( socket, self._room(id));
  • 第 1100 行:sails.sockets.getId(socket)(订阅时记录日志)
  • 第 1124 行:sails.sockets.addRoomMembersToRooms(self._classRoom(), self._room(id) );
  • 第 1141 行:sails.sockets.removeRoomMembersFromRooms(self._classRoom(), self._room(id) );

也就是说,sails.sockets 是「基础设施层」,Resourceful PubSub 是建立在它之上的「模型业务层」。理解底层方法,才能真正驾驭上层抽象。


二、方法总览

方法 说明
.addRoomMembersToRooms() 将某个房间的全部成员订阅到另外的一个或多个房间
.blast() 向连接到服务器的所有 socket 广播一条消息
.broadcast() 向某个房间内的所有 socket 广播一条消息
.getId() 从传入的 socket 请求(req)中解析出 socket ID
.join() 将某个 socket 订阅到某个房间
.leave() 将某个 socket 从某个房间退订
.leaveAll() 将某房间的所有成员从该房间以及它们当前订阅的所有其他房间退订(自动生成的、与 socket ID 同名的房间除外)
.removeRoomMembersFromRooms() 将某房间的全部成员从一个或多个其他房间退订

关于已弃用的方法:如果你在表中没找到想要的方法,请注意——一批 sails.sockets 方法在 Sails v0.12 中已被弃用,原因要么是已经有了性能更高的别名,要么是出于性能与可扩展性(scalability)的考量。详见仓库中的 v0.12 升级指南。典型的例子就是 sails.sockets.id(),它只是 sails.sockets.getId() 的别名,已在 v0.12 弃用(见 sails.sockets.id)。


三、房间订阅与退订:.join() / .leave()

房间(room)是 Sails 实时消息路由的基本单元:客户端 socket 先加入某个房间,服务端再向该房间广播消息。下面先讲两个最常用的单 socket 级方法。

3.1 .join():订阅 socket 到房间

将某个 socket 订阅到一个房间,如果房间尚不存在则自动创建。

sails.sockets.join(socket, roomName);

或带回调的形式:

sails.sockets.join(socket, roomName, cb);

参数说明

参数 类型 说明
socket ((string)), ((req)) 要被订阅的 socket,可以通过 socket ID 字符串指定,也可以直接传入一个 socket 请求(req)
roomName ((string)) 要订阅的房间名。若房间不存在,会自动创建
cb ((function?)) 可选回调。操作在当前服务器上完成、或遇到致命错误时被调用;出错时以单个参数(err)调用

控制器示例

subscribeToFunRoom: function(req, res) {
  if (!req.isSocket) {
    return res.badRequest();
  }

  var roomName = req.param('roomName');
  sails.sockets.join(req, roomName, function(err) {
    if (err) {
      return res.serverError(err);
    }

    return res.json({
      message: 'Subscribed to a fun room called '+roomName+'!'
    });
  });
}

注意事项

  • sails.sockets.join() 与 Socket.IO 的 .join() 功能基本等价,但额外内建了对多服务器部署的支持。在推荐的生产环境扩展配置下,无论代码运行在哪台服务器、目标 socket 连接在哪台服务器,sails.sockets.join() 都能按文档所述正常工作。
  • 多服务器环境下,用 socket ID 调用 .join() 时,回调 cb 会在 .join() 调用在当前服务器上完成后触发,并不保证集群中其他服务器已经完成该操作。
  • 每个 socket 都会自动订阅一个以其 ID 命名的房间,因此可以通过 sails.sockets.broadcast() 直接向单个 socket 发送私信(详见下文)。
  • 传入 req 作为目标 socket 之前,务必检查 req.isSocket === true,req 必须来自 socket 请求,而不是普通的 HTTP 请求。

3.2 .leave():将 socket 从房间退订

与 .join() 对称,用于将某个 socket 从指定房间移除。

sails.sockets.leave(socket, roomName);

或带回调的形式:

sails.sockets.leave(socket, roomName, cb);

参数说明

参数 类型 说明
socket ((string)), ((req)) 要被退订的 socket,可以传入 socket 请求(req),也可以是另一个 socket 的 ID
roomName ((string)) 要退订的房间名
cb ((function?)) 可选回调。操作在当前服务器上完成、或遇到致命错误时被调用;出错时以单个参数(err)调用

控制器示例:将发起请求的 socket 从指定房间退订。

leaveFunRoom: function(req, res) {
  if ( _.isUndefined(req.param('roomName')) ) {
    return res.badRequest('`roomName` is required.');
  }

  if (!req.isSocket) {
    return res.badRequest('This endpoints only supports socket requests.');
  }

  var roomName = req.param('roomName');
  sails.sockets.leave(req, roomName, function(err) {
    if (err) {return res.serverError(err);}
    return res.json({
      message: 'Left a fun room called '+roomName+'!'
    });
  });
}

注意事项

  • sails.sockets.leave() 与 Socket.IO 的 .leave() 功能基本等价,但同样额外内建了多服务器部署支持;在推荐的生产环境扩展配置下,无论代码在哪台服务器上运行、目标 socket 连接在哪台服务器,行为都保持一致。
  • 多服务器环境下用 socket ID 调用时,回调同样只在当前服务器完成时触发。
  • 传入 req 作为被退订的 socket 前,务必确认 req.isSocket === true。

四、广播消息:.broadcast() 与 .blast()

广播是实时推送的核心动作。Sails 提供了两个层级:broadcast 面向「房间内」的 socket,blast 面向「全部」socket。

4.1 .broadcast():向房间广播

向一个或多个房间内的所有 socket 广播消息(也可以定向发送给某个特定 socket)。

sails.sockets.broadcast(roomNames, data);

或者:

sails.sockets.broadcast(roomNames, eventName, data);
sails.sockets.broadcast(roomNames, data, socketToOmit);
sails.sockets.broadcast(roomNames, eventName, data, socketToOmit);

参数说明

参数 类型 说明
roomNames ((string)), ((Array)) 要广播的一个或多个房间名(参见 sails.sockets.join)。若要定向发送给单个 socket,直接用该 socket 的 ID 作为房间名即可
eventName ((string?)) 可选。客户端用来识别这条消息的事件名,默认值为 'message'
data ((json)) 消息中要发送的数据
socketToOmit ((req?)) 可选。若提供,则属于该 socket 请求的 socket 不会收到这条消息。适用于「由客户端触发的广播,但不想让该客户端再收到自己的回显」的场景(例如聊天室里把消息发给除自己之外的所有人)

服务端示例(在 action、service 或任意服务器脚本中):

sails.sockets.broadcast('artsAndEntertainment', { greeting: 'Hola!' });

客户端监听示例:

io.socket.on('message', function (data){
  console.log(data.greeting);
});

更多用法包括:向多个房间广播、使用自定义事件名、排除发起请求的 socket 等,可参考本仓库 broadcast 的方法文档进一步展开。

注意事项

  • sails.sockets.broadcast() 与 Socket.IO 的 .emit() / .broadcast() 功能基本等价。
  • 每个 socket 都自动订阅了一个以其 ID 命名的房间,因此可以直接通过 sails.sockets.broadcast() 实现向单个 socket 的点对点私信。
  • 传入 req 作为 socketToOmit 前,务必确认 req.isSocket === true——要排除的是 socket 请求,不是普通 HTTP 请求。
  • data 必须是 JSON 可序列化的:最好使用纯对象 / 数组,并确保数据中没有循环引用。如果不确定,建议手动构造广播数据,或先调用类似 rttc.dehydrate(data, true, true) 的方法做处理。

4.2 .blast():向所有 socket 广播

向连接到服务器的所有 socket 广播一条消息;如果你的部署是使用 Redis 的多服务器集群,则会广播到集群内所有服务器上的全部 socket。

sails.sockets.blast(data);

或者:

sails.sockets.blast(eventName, data);
sails.sockets.blast(data, socketToOmit);
sails.sockets.blast(eventName, data, socketToOmit);

参数说明

参数 类型 说明
eventName ((string?)) 可选,默认值为 'message'
data ((json)) 消息中要发送的数据
socketToOmit ((req?)) 可选。若提供,与该 socket 请求关联的 socket 不会收到这条广播。适用于「广播事件由请求用户触发,而该用户不需要再听一遍」的场景

控制器示例

sails.sockets.blast('user_logged_in', {
  msg: 'User #' + user.id + ' just logged in.',
  user: {
    id: user.id,
    username: user.username
  }
}, req);

注意事项

  • 传入 req 之前务必检查 req.isSocket === true。要排除某个 socket,当前 req 必须来自 socket 请求,而不是任意 HTTP 请求。

broadcast 与 blast 的选择:需要把消息发给特定用户群体时用 broadcast(配合房间),需要全局通知(如系统公告、全员在线状态变更)时用 blast。从仓库源码看,pubsub hook 内部的模型级广播使用的是 broadcast(如 lib/hooks/pubsub/index.js 第 228、387、1072 行的调用),可见房间机制是资源级消息路由的基础。


五、获取 socket 身份:.getId()

在实时场景中,服务端经常需要知道「是谁在跟我说话」。.getId() 用于从传入的 socket 请求中解析出 socket ID,拿到 ID 之后就能通过 broadcast(以 ID 作为房间名)向该 socket 定向发送私信。

sails.sockets.getId(req);

参数说明

参数 类型 说明
req ((req)) 一个 socket 请求(req)

控制器示例

// Controller action
getSocketID: function(req, res) {
  if (!req.isSocket) {
    return res.badRequest();
  }

  var socketId = sails.sockets.getId(req);
  // => "BetX2G-2889Bg22xi-jy"

  sails.log('My socket ID is: ' + socketId);

  return res.json(socketId);
}

注意事项

  • 务必先确认 req.isSocket === true 再传入 req。该方法对 HTTP 请求不生效!

在仓库源码中也能看到它的实际用法:pubsub hook 在订阅 socket 时用 sails.sockets.getId(socket) 记录日志(lib/hooks/pubsub/index.js 第 1100 行),并在多处使用 sails.sockets.parseSocket(req)(第 253、302、1092 行)把请求解析成 socket 对象——这正是 getId 等方法的内部协作方式。

历史遗留:v0.12 之前名为 sails.sockets.id(),它是 getId() 的别名,已在 v0.12 弃用(见 sails.sockets.id)。新代码请统一使用 .getId()。


六、房间级批量操作:.addRoomMembersToRooms() / .removeRoomMembersFromRooms() / .leaveAll()

当应用需要整体迁移、清空或重组一批用户所属的房间时,逐个 socket 调用 join / leave 显然低效。Sails 提供了三个「以房间为单位」的批量方法。

6.1 .addRoomMembersToRooms():将某房间全部成员批量订阅到其他房间

sails.sockets.addRoomMembersToRooms(sourceRoom, destRooms, cb);

参数说明

参数 类型 说明
sourceRoom ((string)) 从中获取成员的房间
destRooms ((string)), ((array)) 要把 sourceRoom 的成员订阅到的房间(可单个字符串,也可字符串数组)
cb ((function?)) 可选回调。操作在当前服务器上完成、或遇到致命错误时被调用;出错时以单个参数(err)调用

控制器示例

subscribeFunRoomMembersToFunnerRooms: function(req, res) {
  sails.sockets.addRoomMembersToRooms('funRoom', ['greatRoom', 'awesomeRoom'], function(err) {
    if (err) {return res.serverError(err);}
    res.json({
      message: 'Subscribed all members of `funRoom` to `greatRoom` and `awesomeRoom`!'
    });
  });
}

多服务器注意事项:回调会在 .addRoomMembersToRooms() 调用在当前服务器上完成时触发,不保证集群内其他服务器已经执行完该操作。

6.2 .removeRoomMembersFromRooms():将某房间全部成员从其他房间批量退订

与 6.1 对称,用于从「一个或多个其他房间」中移除某房间的全部成员。

sails.sockets.removeRoomMembersFromRooms(sourceRoom, destRooms, cb);

参数说明

参数 类型 说明
sourceRoom ((string)) 从中获取成员的房间
destRooms ((string)), ((array)) 要将 sourceRoom 的成员从其中退订的房间(可单个字符串,也可字符串数组)
cb ((function?)) 可选回调。操作在当前服务器上完成、或遇到致命错误时被调用;出错时以单个参数(err)调用

控制器示例

unsubscribeFunRoomMembersFromFunnerRooms: function(req, res) {
  sails.sockets.removeRoomMembersFromRooms('funRoom', ['greatRoom', 'awesomeRoom'], function(err) {
    if (err) {return res.serverError(err);}
    res.json({
      message: 'Unsubscribed all members of `funRoom` from `greatRoom` and `awesomeRoom`!'
    });
  });
}

多服务器注意事项:回调在操作于当前服务器完成后触发,不保证集群中其他服务器已同步完成。

这两个方法在 pubsub hook 中被用于「类级房间 → 实例级房间」的订阅关系维护:当模型新增/删除记录时,hook 会把整个模型类的订阅成员批量挂到具体实例房间上(lib/hooks/pubsub/index.js 第 1124、1141 行)。

6.3 .leaveAll():清空某房间所有成员的全部订阅

把某个房间(例如 chatroom7)的所有成员从该房间以及它们当前订阅的其他所有房间中退订,唯一例外是自动生成、与各 socket ID 同名的房间(这是保留点对点私信通道的设计考量)。

sails.sockets.leaveAll(roomName, cb);

参数说明

参数 类型 说明
roomName ((string)) 要疏散(evacuate)的房间。注意:该房间的成员将被强制离开它们所有的房间,而不仅仅是这一个
cb ((function?)) 可选回调。操作在当前服务器上完成、或遇到致命错误时被调用;出错时以单个参数(err)调用

控制器示例

unsubscribeFunRoomMembersFromEverything: function(req, res) {

  sails.sockets.leaveAll('funRoom', function(err) {
    if (err) { return res.serverError(err); }

    // Unsubscribed all sockets in "funRoom" from "funRoom".
    // And... from every other room too.

    return res.ok();

  });
}

多服务器注意事项:回调在 .leaveAll() 调用于当前服务器完成后触发,不保证集群中其他服务器已同步完成。

leaveAll 常用于「房间被关闭 / 群组被解散 / 用户被全局踢出」等需要彻底清理订阅关系的场景,与逐个 leave 相比,它用一次调用完成整组清理,避免了循环调用带来的多服务器一致性问题。


七、实战组合:用 sails.sockets 搭建一个实时聊天室

将上述方法组合起来,一个典型的「加入房间 → 广播消息 → 退出房间」流程如下:

// api/controllers/chat-controller.js
module.exports = {

  // 客户端通过 socket 请求加入聊天室
  joinRoom: function(req, res) {
    if (!req.isSocket) { return res.badRequest('只支持 socket 请求'); }

    var roomName = req.param('roomName');
    sails.sockets.join(req, roomName, function(err) {
      if (err) { return res.serverError(err); }
      return res.json({ message: '已加入房间:' + roomName });
    });
  },

  // 向房间内其他成员广播消息(排除自己)
  sendMessage: function(req, res) {
    if (!req.isSocket) { return res.badRequest('只支持 socket 请求'); }

    var roomName = req.param('roomName');
    var text = req.param('text');
    var data = {
      from: sails.sockets.getId(req),   // 用 getId 标识发送者
      text: text,
      at: Date.now()
    };
    // 事件名 message,排除发送者自身
    sails.sockets.broadcast(roomName, 'message', data, req);
    return res.ok();
  },

  // 退出房间
  leaveRoom: function(req, res) {
    if (!req.isSocket) { return res.badRequest('只支持 socket 请求'); }
    var roomName = req.param('roomName');
    sails.sockets.leave(req, roomName, function(err) {
      if (err) { return res.serverError(err); }
      return res.json({ message: '已离开房间:' + roomName });
    });
  }
};

客户端配合(assets/js 中通过 sails.io.js 连接):

// 监听服务器推送的 message 事件
io.socket.on('message', function(data) {
  console.log(data.from + ' 说:' + data.text);
});

// 通过 socket 请求调用服务端 action
io.socket.post('/chat/joinRoom', { roomName: 'funRoom' }, function(){ /* ... */ });

相关客户端 API 可参考仓库中的 sails.io.js 文档 与 io.socket.on、io.socket.post。

可靠数据的小技巧:发送给客户端的 data 必须是 JSON 可序列化的纯数据(无循环引用),建议在组装 payload 时就用纯对象字面量,避免把模型实例直接丢进广播。


八、多服务器扩展与最佳实践总结

sails.sockets 方法集在多服务器部署中表现出色的关键,在于其对 Socket.IO 原生的 join/leave/broadcast 进行了扩展,使房间订阅与消息投递能够跨越集群中的不同服务器(官方推荐配合 Redis 使用,详见 Scaling)。结合源码与文档,可以总结出以下实战要点:

  1. 优先 sails.sockets.*,避免直接用 sails.io:前者提供了多服务器一致性、统一签名等额外保障。
  2. 所有接收 req 的方法都要先校验 req.isSocket === true:这是 .getId()、join(req, ...)、broadcast(..., req) 等一切以 socket 请求为参数的操作的前提。
  3. 用房间做业务隔离,用 ID 房间做点对点私信:每个 socket 自动拥有一个以自身 ID 命名的房间,天然支持单聊。
  4. 批量场景使用房间级方法:迁移订阅用 addRoomMembersToRooms,清理订阅用 removeRoomMembersFromRooms / leaveAll,避免大量循环调用。
  5. 多服务器回调语义:所有回调只在「当前服务器」完成时触发,跨服务器同步不保证在同一时刻完成,业务上要容忍这种最终一致性。
  6. 数据必须 JSON 可序列化:广播内容保持纯数据,避免循环引用。

如需进一步了解更高层的模型级订阅(模型创建、更新、销毁时自动推送),请阅读 Resourceful PubSub 及其 publish、subscribe、get-room-name 等方法文档;底层实时通信原理可参考 Realtime 概念文档。

登录后查看全文
sails