跳转到主要内容

​
什么是断开连接？

与流式 API 建立连接意味着发起一个长时间保持的 HTTPS 请求，并逐步解析返回的数据。连接到 filtered stream 端点时，你应构造一个 HTTPS 请求，并在可行的情况下尽可能长时间地持续读取该流。除非出现服务端错误、客户端端过度延迟、网络问题、例行服务器维护或重复登录等情况，我们的服务器会无限期保持连接。对于与流式端点的连接，断开连接很常见，应当预期并据此实现重连逻辑。  

​
为什么流式连接可能会断开

你的流可能会因多种原因而断开。请查看流返回的错误消息以了解失败原因。可能的断开原因包括：
  • 认证错误（例如使用了错误的令牌或错误的认证方式）。
  • X 侧重启了流式服务器。这通常与代码部署有关，属于预期情况，应在系统设计中加以考虑。
  • 客户端处理不过来流中传送的 Post 数量，或读取数据过慢。每个流式连接背后都有一个发送给客户端的消息队列；如果该队列随时间增长过大，连接将被关闭。
  • 你的账户超出了每日/每月的 Post 配额。
  • 活跃的冗余连接过多。
  • 客户端突然停止读取数据。如果从流中读取的 Post 速率骤降，连接将被关闭。
  • 服务器与客户端之间可能存在网络问题。
  • 临时的服务器端问题，或计划中的维护与更新。（请查看状态页）  

​
常见的断线错误包括：

	"errors": [{
		"title": "operational-disconnect",
		"disconnect_type": "UpstreamOperationalDisconnect",
		"detail": "该数据流因运维原因已在上游断开连接。",
		"type": "https://api.x.com/2/problems/operational-disconnect"
	}]
}

{
	"title": "ConnectionException",
	"detail": "此流已达到允许的最大连接数限制。",
	"connection_issue": "TooManyConnections",
	"type": "https://api.x.com/2/problems/streaming-connection"
}

​
预期断连并重新连接

在流式获取 Post 时，目标是尽可能长时间保持连接，同时也要意识到可能会发生断连。该端点每 20 秒发送一次保活心跳（表现为一个换行符）。使用此信号来检测是否发生断连。
  1. 你的代码应检测新内容和心跳不再到达的情况。
  2. 如果发生这种情况，你的代码应触发重连逻辑。一些客户端和语言允许指定读取超时，你可以将其设置为 20 秒。
  3. 你的服务应检测到这些断连并尽快重连。
一旦已建立的连接中断，应立即尝试重连。如果重连失败，请根据错误类型放缓重连尝试的频率：
  • 对 TCP/IP 层的网络错误采取线性退避。这类问题通常是临时的，且往往很快恢复。每次重连尝试将延迟增加 250ms，最高至 16 秒。
  • 对适合重连的 HTTP 错误采取指数退避。从等待 5 秒开始，每次加倍，最高至 320 秒。
  • 对 HTTP 429 错误（超出速率限制）采取指数退避。从等待 1 分钟开始，并在每次尝试时加倍。请注意，每次收到 HTTP 429 都会增加你必须等待的时间，直到你的账户不再受速率限制为止。  

​
恢复丢失的 data

如果确实发生断连，您可以采用多种策略来确保拿回所有可能错过的 data。我们在集成指南的恢复 data页面详述了用于找回遗漏 data 的关键步骤。   

​
速率限制与使用

要检查连接限制，响应会返回三个响应头。这有助于了解规则端点可调用的次数，以及流式端点允许的重连尝试次数。
  • x-rate-limit-limit 表示在 15 分钟时间窗口内你的客户端被允许发起的请求配额。
  • x-rate-limit-remaining 表示在 15 分钟时间窗口内截至目前已发起的请求数。
  • x-rate-limit-reset 是一个 UNIX 时间戳，表示 15 分钟时间窗口何时重新开始，届时会将 x-rate-limit-remaining 重置为 0。
筛选流端点目前不报告使用数据。若要检查已传递了多少个 Post，你的代码可以实现计量逻辑，以便在需要时衡量并暂停消费。 在承载流式客户端的代码中，只需将传入的 Post 插入先进先出（FIFO）队列或类似的内存结构；应由单独的进程/线程从该队列中消费 Post，用于解析并准备内容以进行存储。采用这种设计，当传入的 Post 量出现剧烈变化时，你可以实现一个能够高效扩展的服务。概念上，可以将其视为通过 HTTP 下载一个无限长的文件。

​
重新连接最佳实践

测试退避策略 测试退避实现的一个好方法是使用无效的授权凭据并观察重连尝试。良好的实现不应收到任何 429 响应。 为多次重连发出警报 如果客户端达到重连间隔时间的上限阈值，应向你发送通知，便于你对影响连接的问题进行排查。 处理 DNS 变更 测试你的客户端进程是否遵循 DNS 生存时间（TTL）。某些技术栈会在进程整个生命周期内缓存已解析的地址，并且不会在规定的 TTL 内采纳 DNS 变更。此类过度缓存会在 X 在不同 IP 地址之间进行负载切换时导致你的客户端发生服务中断。 User Agent 确保你的 user-agent HTTP 头包含客户端的版本信息。这对于诊断 X 端的问题至关重要。如果你的环境无法设置 user-agent 字段，则请设置 x-user-agent 头。