套接字客户端 (sails.io.js)
本节文档介绍适用于浏览器的 Sails 套接字客户端 SDK。它用 JavaScript 编写，也可在服务器上使用。
此外，还有几个社区项目实现了针对原生 iOS、Android 和 Windows Phone 的 Sails/Socket.IO 客户端。
概述
Sails 套接字客户端 (sails.io.js) 是一个微小的浏览器库，默认情况下会捆绑在新 Sails 应用程序中。它是一个轻量级的包装器，位于 Socket.IO 客户端之上，其目的是尽可能简化向 Sails 后端发送和接收消息的过程。
sails.io.js 的主要职责是为使用 WebSockets/Socket.IO 与 Sails 应用程序通信提供一个熟悉、类似 Ajax 的接口。这基本上意味着提供 .get()、.post()、.put() 和 .delete() 方法，这些方法允许您利用实时功能，同时仍然重用用于应用程序其他部分的相同后端路由。换句话说，在浏览器中运行 io.socket.post('/user') 将以与对相同路由进行 HTTP POST 请求完全相同的方式在您的 Sails 应用程序中路由。
基本用法（浏览器）
在浏览器中，使用 sails.io.js 所需的只是在 <SCRIPT> 标签中包含该库。Sails 会将该库添加到所有新应用程序的 assets/js/dependencies 文件夹中，因此您可以编写
<!--
This will import the sails.io.js library bundled in your Sails app by default.
The bundled version embeds minified code for the Socket.io client as well.
One tick of the event loop after importing this script, a new "eager" socket
will automatically be created begin connecting unless you configure it not to.
-->
<script type="text/javascript" src="/js/dependencies/sails.io.js"></script>
然后在后续的内联或外部脚本中将 io.socket 作为全局变量使用。有关日常使用情况的详细说明和示例，请参见 io.socket。
基本用法（Node.js）
要在 Node.js 脚本中使用 Sails 套接字客户端 SDK，您需要安装并需要 sails.io.js 和 socket.io-client 库
// Initialize the sails.io.js library with the socket.io-client module,
// which will automatically create and connect a new socket as io.socket
// unless you configure it not to.
var io = require('sails.io.js')( require('socket.io-client') );
有关从 Node.js 使用 Sails 套接字客户端的更多信息，请参见 sails.io.js GitHub 存储库。
配置 sails.io.js 库
本节重点介绍 JavaScript 套接字客户端最常见的运行时环境：浏览器。有关在 Node.js 脚本中配置套接字客户端的帮助，请参见
sails.io.jsGitHub 存储库。
在浏览器中配置 Sails 的套接字客户端有两种方法：在 <script> 标签上使用 HTML 属性，或以编程方式修改 io.sails 对象。
使用 HTML 属性进行基本配置
配置套接字客户端的四个最常见设置（autoConnect、environment、headers 和 url）的最简单方法是在脚本标签上添加一个或多个 HTML 属性
<script src="/js/dependencies/sails.io.js"
autoConnect="false"
environment="production"
headers='{ "x-csrf-token": "<%= typeof _csrf !== 'undefined' ? _csrf : '' %>" }'
></script>
此示例将禁用急切套接字连接，将客户端环境强制为“生产”（这会禁用日志），并设置一个 x-csrf-token 标头，该标头将在每个套接字请求中发送（除非被覆盖）。请注意，headers 字典之类的复合值用一对单引号括起来。这是因为以这种方式指定的复合值必须是JSON 编码的，这意味着它们的键名和值字符串必须用双引号括起来（出于类似的原因，值字符串中的字符串用单引号括起来）。
可以用作 HTML 属性的任何配置都可以使用 data- 前缀来提供（例如 data-autoConnect、data-environment、data-headers、data-url）。这是为了支持在处理非标准 HTML 属性方面存在问题的浏览器的用户（或者如果您认为使用非标准 HTML 属性会让您感到不适）。如果提供了标准 HTML 属性和 data- 前缀的 HTML 属性，则后者优先。
注意：为了使用这种方法配置套接字客户端，如果您正在使用默认的 Grunt 资源管道（它会自动注入脚本标签），您需要从
pipeline.js文件中删除sails.io.js，然后改为包含一个显式的<script>标签，该标签导入它。
使用 io.sails 进行编程配置
从 Sails v0.12.x 开始，只能使用 HTML 属性设置最基本的配置选项。如果要配置上述未提到的任何其他选项，您需要以编程方式与 io.sails 交互。幸运的是，上述方法实际上只是一个方便的快捷方式，可以完成此操作！这是工作原理
当您在 <script> 标签中加载它时，sails.io.js 库会在一个事件循环周期后等待，然后自动连接一个套接字（如果启用了 io.sails.autoConnect，请参见下文）。这允许您在套接字开始连接之前设置您在 io.sails 上指定的任何属性。但是，为了确保在连接之前读取 io.sails 属性，您应该在包含 sails.io.js 的 <script> 标签后立即放置设置这些属性的代码
<script src="/js/dependencies/sails.io.js"></script>
<script type="text/javascript">
io.sails.url = 'https://myapp.com';
</script>
<!-- ...other scripts... -->
通常，套接字客户端始终连接到提供脚本的服务器。上面的示例将导致急切（自动连接）套接字尝试与运行在 https://myapp.com 上的 Sails 服务器进行（跨域）套接字连接。
注意：如果您正在使用默认的 Grunt 资源管道（它会自动注入脚本标签），最好将
sails.io.js从pipeline.js文件中排除，改为为其显式添加<script>标签。这确保您的配置将在“急切”自动连接套接字开始连接之前应用，因为这意味着您用于编程配置的内联<script>标签（例如，设置io.sails.url = 'https://myapp.com';）在套接字客户端之后立即执行。
高级用法
您还可以使用 io.sails.connect 手动创建和连接客户端套接字。这将返回 SailsSocket 的一个实例。有关不太常见和更高级的用例（例如连接多个套接字）的更多信息，请参见 SailsSocket。
高级配置
sails.io.js 库及其各个客户端套接字有一些配置选项。全局配置位于 io.sails 中，它——除了其他内容之外——允许您禁用“急切”套接字和新套接字的默认设置。也可以在手动连接时配置单个套接字——有关这方面的更多信息，请参见 io.sails.connect()。
常见问题
我可以在 XYZ 前端框架中使用它吗？
可以。Sails 套接字客户端可以与任何前端框架一起使用，无论它是 Angular、React、Ember、Backbone、Knockout、jQuery、FishBerry 等等。
我必须使用它吗？
不需要。在基于浏览器的 UI 中构建实时/聊天功能时，Sails 套接字客户端非常有用，但与 assets/ 目录的其余部分一样，如果您正在构建一个 原生 Android 应用程序 或完全没有用户界面的 API，它可能不是特别有用。
幸运的是，与 Sails 中的每个其他样板文件和文件夹一样，套接字客户端是完全可选的。要删除它，只需删除 assets/js/dependencies/sails.io.js 即可。
它如何工作？
在幕后，套接字客户端 (sails.io.js) 会发出具有保留名称的 Socket.IO 消息，当 Sails 解释这些消息时，会根据您的应用程序的路由和蓝图配置将其路由到适当的策略/控制器等等。
如何指示我的 Sails 应用程序不与当前浏览器会话连接套接字？
默认情况下，套接字连接将使用与初始套接字握手一起发送的 cookie 标头链接到当前浏览器会话（如果有）。为了关闭此行为，在套接字连接之前将 nosession=true 添加到套接字的 query 属性 中。例如
<script src="/js/dependencies/sails.io.js"></script>
<script type="text/javascript">io.sails.query='nosession=true';</script>
我可以绕过此客户端并直接使用 Socket.IO 吗？
可以绕过 Sails 应用程序中的请求解释器并直接与 Socket.IO 通信。但是，不建议这样做，因为它破坏了框架中其他地方使用的约定优于配置的理念。Sails 套接字客户端 (sails.io.js) 是不显眼的：它通过包装原生 Socket.IO 客户端并公开一个更高级别的 API 来工作，该 API 利用 Sails 中的虚拟请求解释器来发送模拟 HTTP 请求。这使您的后端代码更具可重用性，降低了新开发人员使用 WebSockets/Socket.IO 的入门门槛，并使您的应用程序更容易推理。
注意：在极少数情况下（例如，与使用 Socket.IO 直接的现有/旧前端兼容），绕过请求解释器是必需的。如果您发现自己处于这种境地，您可以使用 Socket.IO 客户端、SDK，然后在后端使用
sails.io访问原始 Socket.IO 实例。请仅在您拥有直接使用 Socket.IO 的丰富经验时才走上这条道路，并且仅在您首先检查了socketshook 的内部结构（尤其是“管理总线”实现，它是一个 Redis 集成，位于 @sailshq/socket.io-redis 之上，并为 Sails 的多服务器支持提供动力，用于加入/离开房间）后才走上这条道路。
为了在 sailsjs.com 上获得更好的体验，请更新您的浏览器。
参考
- 应用程序
- 蓝图 API
- 命令行界面
-
配置
- sails.config.*
- sails.config.blueprints
- sails.config.bootstrap()
- sails.config.custom
- sails.config.datastores
- sails.config.globals
- sails.config.http
- sails.config.i18n
- sails.config.log
- sails.config.models
- sails.config.policies
- sails.config.routes
- sails.config.security
- sails.config.session
- sails.config.sockets
- sails.config.views
-
请求 (`req`)
- req._startTime
- req.body
- req.cookies
- req.fresh
- req.headers
- req.hostname
- req.ip
- req.ips
- req.isSocket
- req.method
- req.options
- req.originalUrl
- req.params
- req.path
- req.protocol
- req.query
- req.secure
- req.signedCookies
- req.socket
- req.subdomains
- req.url
- req.wantsJSON
- req.xhr
- req.accepts()
- req.acceptsCharsets()
- req.acceptsLanguages()
- req.allParams()
- req.file()
- req.get()
- req.is()
- req.param()
- req.setLocale()
- req.setTimeout()
- req.host
- 响应 (`res`)
- Waterline (ORM)
- WebSocket
参考
用心打造
Sails 框架由位于德克萨斯州奥斯汀的 网络和移动工作室 以及我们的贡献者共同开发。我们于 2012 年创建了 Sails 来协助我们的 Node.js 项目。自然而然地，我们将其开源了。我们希望它能让你的生活更轻松！
© 2012-2024 The Sails Company.
Sails 框架是根据 MIT 许可协议免费开源的。
插图由 Edamame 提供。