基础

finlight.me WebSocket API 提供持续的、实时的金融新闻文章流，在文章可用的那一刻即时投递。与需要定期轮询的传统 REST 端点不同，WebSocket 方式让您可以维持一个持久连接，无需反复请求即可接收更新。这带来更快的数据投递、高效的资源使用以及更好的用户体验。

在本指南中，您将学习使用 finlight.me WebSocket API 进行连接、认证和保持连接的基本步骤。

注意：要使用 WebSocket 功能，您需要拥有付费订阅。免费层级不包含 WebSocket 功能。您至少需要一个包含 WebSocket 功能的订阅。

连接到 WebSocket

要开始接收实时金融新闻更新，您需要与 finlight.me 服务器建立 WebSocket 连接。该连接将保持打开，直到您或服务器将其关闭。一旦连接建立，您就可以开始订阅文章流，并在新文章发布时接收消息。

注意：WebSocket API 在技术上会在 2 小时后断开连接。不过，我们的 TypeScript 或 Python 客户端库会通过自动重连为您处理此问题。如有需要，您也可以手动重连。

WebSocket 端点：
wss://wss.finlight.me

要点：

实时数据：WebSocket 协议支持全双工连接，意味着数据可以实时地在服务器之间双向流动。
发布/订阅模型：连接后，您可以指定您的查询（例如 query: "nvidia"），服务器会立即发送匹配的最新文章，随后发送陆续可用的新文章。
无需反复轮询：服务器会将新文章推送给您，而不是让您持续轮询服务器以获取新数据，从而减少开销和延迟。

使用 Takeover 管理连接限制

每个订阅层级都包含固定数量的并行 WebSocket 连接。如果您尝试打开的连接超过所在层级允许的数量，您有两个选择：

默认行为（takeover: false）：新的连接尝试将被拒绝，您会收到一条错误，提示您已达到连接上限。
Takeover 模式（takeover: true）：最旧的现有连接将被自动关闭，新连接将取而代之。

启用 Takeover 的示例：

const { FinlightApi } = require('finlight-client')

const client = new FinlightApi(
  {
    apiKey: 'YOUR_API_KEY',
    logger: console,
    logLevel: 'info',
  },
  {
    // WebSocket-specific options
    takeover: true, // Automatically close oldest connection when limit is reached
  },
)

client.websocket.connect(
  { query: 'nvidia', language: 'en' },
  (article) => {
    console.log('New article received:', article)
  },
)

何时使用 Takeover：

开发/测试：当您频繁重启应用且不想手动关闭现有连接时很有用。
单一活动实例：当您希望确保只有最近的连接实例处于活动状态时。
自动迁移：在服务器之间迁移或重新部署应用时。

何时避免使用 Takeover：

生产环境：您希望对连接管理拥有明确的控制权。
多个合法连接：当您有意为不同目的运行多个连接实例时。
调试：当您需要了解为何会达到连接上限时。

认证

为确保安全和授权访问，所有到 finlight.me 的 WebSocket 连接都必须使用您的 API 密钥进行认证。该密钥用于验证您拥有接收实时内容所需的权限和访问权利。

在初始的 WebSocket 握手请求标头中包含您的 API 密钥。大多数 WebSocket 客户端库都允许您在创建连接时指定附加标头。

标头：
x-api-key: YOUR_API_KEY

如何获取 API 密钥：

在 finlight 控制台注册。
导航到 API Keys 部分以创建和管理您的密钥。

代码片段（Node.js 示例）：

const WebSocket = require('ws')

const socket = new WebSocket('wss://wss.finlight.me', {
  headers: {
    'x-api-key': 'YOUR_API_KEY',
  },
})

socket.on('open', () => {
  console.log('Connected to finlight.me WebSocket!')
  // You can now send a subscription request to start receiving articles
})

socket.on('error', (err) => {
  console.error('WebSocket error:', err)
})

保持连接活动（Ping/Pong 机制）

WebSocket 连接可以长时间保持打开，但网络状况、代理和防火墙可能会断开不活动的连接。为缓解这一问题，finlight.me 支持 ping/pong 保活机制。

工作原理：

客户端发送 ping：客户端按固定间隔（例如每 8 分钟）向服务器发送一条 ping 消息。
服务器响应 pong：服务器以 pong 消息回复，表示连接仍然存活。
无响应处理：如果客户端在一定时间内未收到 pong，则可认为连接已丢失并尝试重连。

这个简单的心跳确保客户端和服务器双方都知道连接仍然活动，并能不间断地交换数据。

示例（使用 setInterval 的 Node.js）：

socket.on('open', () => {
  console.log('Connected to finlight WebSocket')

  // Send a ping every 8 minutes
  const pingInterval = setInterval(
    () => {
      if (socket.readyState === WebSocket.OPEN) {
        console.log('Sending ping...')
        socket.send(JSON.stringify({ action: 'ping' }))
      }
    },
    8 * 60 * 1000,
  ) // 8 minutes in milliseconds

  socket.on('message', (data) => {
    const message = JSON.parse(data)
    if (message.action === 'pong') {
      console.log('Received pong, connection is alive.')
    } else {
      // Handle other messages, such as incoming articles
      console.log('Received message:', message)
    }
  })

  socket.on('close', () => {
    clearInterval(pingInterval)
    console.log('WebSocket connection closed.')
  })
})

为什么 Ping/Pong 很重要？

长时间运行的连接：许多应用依赖持续运行的 WebSocket 连接。没有保活机制，这些连接可能会悄然失败。
网络可靠性：ping/pong 检查可确保短暂的网络问题不会让客户端对已断开的连接毫不知情。
资源效率：快速检测到连接丢失有助于客户端节省资源，避免无限期地等待永远不会到达的新数据。

连接时长限制

finlight.me 的 WebSocket 基础设施由 AWS API Gateway 提供支持，它对每个 WebSocket 会话施加 2 小时的硬性最大连接时长。这是一个平台级别的限制 —— 无论是否活动，所有连接都会在 2 小时后被 AWS 关闭。

这对您意味着什么

您的连接将在 2 小时后自动关闭，即使它正在积极接收数据或发送 ping。
这是预期行为，并不表示存在错误或网络问题。
为保持无缝体验，您需要在每个 2 小时窗口后重连。

我们已为您处理好

我们的 Python 和 TypeScript 客户端库都会透明地处理此问题：

当服务器在 2 小时后关闭连接时，客户端会检测到断开。
随后它会自动尝试重连，以最小的中断保持您的数据流。
这可确保数据持续流动，无需手动干预。

如果您不使用我们的库而自行构建客户端，请务必在您这一端实现重连逻辑，以妥善处理 2 小时限制。

通过理解这些基础知识 —— 安全地连接、认证您的请求，以及使用 ping/pong 心跳维持连接 —— 您已经在高效地将 finlight.me 的 WebSocket API 集成到应用中的路上了。从这里开始，您可以探索订阅消息、source 或 language 等过滤器，并处理传入的文章，以构建丰富的实时金融新闻体验。