处理断线

​

什么是断开连接？

与流式 API 建立连接意味着发起一个生命周期极长的 HTTPS 请求，并以增量方式解析响应。连接到“过滤的流”endpoint 时，你应当构造一个 HTTPS 请求，并在可行的时间范围内持续消费返回的 stream。除非发生服务器端错误、客户端严重滞后、网络问题、例行服务器维护或重复登录，否则我们的服务器将无限期保持连接打开。对于与流式 endpoints 的连接，断开连接是很可能且应当预期的，因此需要实现重连逻辑。  

​

为什么 stream 连接可能会断开

你的 stream 可能会因多种原因断开。请检查 stream 返回的错误信息以了解失败原因。可能的断开原因包括：

• 身份验证错误（例如使用了错误的令牌或错误的身份验证方法）。
• X 侧的流式服务器重启。这通常与代码部署相关，应当预期并在设计中加以考虑。
• 客户端未能跟上 stream 传递的 Posts 数量，或读取速度过慢。每个流式连接背后都有一个向客户端发送消息的队列。如果该队列随时间增长过大，连接将被关闭。
• 你的账户超过了每日/每月的 Posts 配额。
• 活跃的冗余连接过多。
• 客户端突然停止读取数据。如果从 stream 读取 Posts 的速率骤降，连接将被关闭。
• 服务器与客户端之间存在潜在的网络问题。
• 临时的服务器端问题、计划性维护和更新。（请查看状态页）  

​

常见的断线错误包括：

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

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

​

预判断连与重新连接

在流式传输 Posts 时，目标是尽可能长时间保持连接，同时也要意识到断连可能发生。该 endpoint 提供 20 秒的保活心跳（表现为一个换行符）。使用此信号检测是否已被断开。

1. 你的代码应检测新内容和心跳何时停止到达。
2. 如果发生这种情况，应触发重连逻辑。某些客户端和语言允许你指定读取超时，你可以将其设置为 20 秒。
3. 你的服务应检测到这些断连并尽快重连。

一旦已建立的连接中断，应立即尝试重连。如果重连失败，请根据所遇错误类型放缓重连节奏：

• 对于 TCP/IP 层面的网络错误采用线性退避。这类问题通常是暂时的，且往往很快恢复。每次重连尝试将延迟增加 250ms，最高至 16 秒。
• 对于适合重连的 HTTP 错误采用指数退避。先等待 5 秒，每次尝试将等待时间加倍，最高至 320 秒。
• 对于 HTTP 429 错误（请求速率限制超出）采用指数退避。先等待 1 分钟，并在每次尝试时将等待时间加倍。请注意，每收到一次 HTTP 429 都会增加你必须等待的时间，直到你的帐户不再受到请求速率限制的影响。  

​

恢复丢失的 data

如果确实发生断开连接，您可以采用多种策略，确保获取到可能错过的全部 data。我们在集成指南的数据恢复章节中记录了若干关键步骤，帮助您找回遗漏的 data。   

​

请求速率限制与使用

要检查连接限制，响应会返回三个响应头。这有助于了解你可以调用 rule endpoint 的次数，以及 streaming endpoint 允许的重连尝试次数。

• x-rate-limit-limit 表示在 15 分钟时间窗内你的客户端可发起的请求配额数。

• x-rate-limit-remaining 表示在该 15 分钟时间窗内截至目前剩余的可用请求数。

• x-rate-limit-reset 是一个 UNIX 时间戳，表示该 15 分钟时间窗何时重置，并将 x-rate-limit-remaining 重置为 0。

filter stream endpoint 目前不报告使用数据。若要检查已投递的 Post 数量，你的代码可以实现计量逻辑，以便在需要时衡量并暂停消费。

承载 stream 客户端的代码只需将传入的 Post 插入先进先出（FIFO）队列或类似的内存结构；一个单独的进程/线程应从该队列中消费 Post，进行解析并准备入库。通过这种设计，你可以实现一个即使在传入 Post 量剧烈变化时也能高效扩展的服务。概念上，你可以将其视为通过 HTTP 下载一份无限长的文件。

​

重新连接最佳实践

测试退避策略

测试退避实现的一个有效方法是使用无效的授权凭据，并观察重新连接的尝试。良好的实现不应收到任何 429 响应。

针对多次重新连接发出告警

如果客户端达到其两次重新连接间隔的上限阈值，应向你发送通知，便于你及时排查影响连接的问题。

处理 DNS 变更

测试你的客户端进程是否遵循 DNS 的生存时间（TTL）。某些协议栈会在进程生命周期内缓存已解析的地址，无法在规定的 TTL 内获取 DNS 变更。此类过度缓存会在 X 在不同 IP 地址之间进行负载切换时导致你的客户端服务中断。

User Agent

确保你的 user-agent HTTP 头包含客户端的版本信息。这对于定位 X 端的问题至关重要。如果你的环境无法设置 user-agent 字段，请改为设置 x-user-agent 头。