处理流式数据

​

构建用于消费 stream 数据的客户端

在使用流式 endpoint 时，有一些通用的最佳实践值得遵循，以提升整体效率。    

​

客户端设计

在使用过滤 stream endpoint 构建解决方案时，您需要一个能够执行以下操作的客户端：

1. 建立与过滤 stream endpoint 的 HTTPS 流式连接。
2. 异步向过滤 stream 规则 endpoint 发送 POST 请求，以在 stream 中添加和删除规则。
3. 处理低数据量——保持流式连接，检测 Post 对象和保活信号。
4. 处理高数据量——使用异步流程将 stream 的摄取与后续处理解耦，并确保客户端缓冲区定期刷新。
5. 在客户端管理用量消耗的跟踪。
6. 识别 stream 断开，评估原因并自动重新连接到 stream。  

​

连接到流式 endpoint

与 X API v2 的流式 endpoint 建立连接意味着发起一个长时保持的 HTTP 请求，并以增量方式解析响应。概念上，可以将其看作通过 HTTP 下载一个无限长的文件。建立连接后，只要连接保持打开，X 服务器就会通过该连接持续传递 Post 事件。  

​

数据消费

请注意，JSON 对象的各个字段没有固定顺序，且在不同情况下并非所有字段都会出现。同样，独立的活动不会按排序顺序传递，也可能出现重复消息。请记住，随着时间推移，新的消息类型可能会被添加并通过 stream 发送。

因此，你的客户端必须能够容忍：

• 字段以任意顺序出现
• 意外或缺失的字段
• 未排序的 Posts
• 重复消息
• 在任何时间通过 stream 下发的新的任意消息类型

除了相关的 Post data 和请求的 fields 参数之外，通过 stream 连接还可能传递以下类型的消息。请注意，此列表可能并不完整——stream 中可能会引入其他对象。请确保你的解析器能够容忍意外的消息格式。  

​

缓冲

streaming endpoint 会在数据可用时尽快向你发送 data，这在许多情况下可能导致高数据量。如果 X 服务器无法立即将新数据写入 stream（例如你的客户端读取速度不够快，参见处理断开连接），它会在服务端暂存内容，便于你的客户端追上进度。但当该缓冲区被占满时，将触发强制断开以中止连接，且已缓冲的 Posts 会被丢弃且不会重发。详见下文。

识别你的 App 何时落后的一个方法，是将接收到的 Posts 的时间戳与当前时间进行比较，并持续跟踪这一差值。

尽管由于公共互联网的潜在延迟和抖动，stream 积压无法被彻底避免，但通过正确配置你的 App，基本可以将其消除。要尽量减少积压的发生：

• 确保你的客户端以足够快的速度读取 stream。通常在读取 stream 时不应进行实际的处理工作；应先读取 stream，再将处理工作交由其他线程/进程/数据存储异步执行。
• 确保你的数据中心具备足够的入站带宽，以应对大规模的持续数据量以及显著更大的突发峰值（例如正常量的 5–10 倍）。对于 过滤的流，你这端所需的流量和相应带宽完全取决于你的规则匹配到了哪些 Posts。  

​

使用情况跟踪与规则管理

鉴于开发者对其 stream“正常”数据量的预期各不相同，我们无法就具体的百分比增减或时间周期给出通用建议。

请考虑监控你的 stream 数据量，以发现异常波动。数据量下降可能与 stream 断开属于不同的问题。在这种情况下，stream 仍会接收 keep-alive 信号，并且可能仍会有部分新的活动数据。然而，Post 数量显著减少应促使你调查是否存在导致进入你应用或网络的入站数据量下降的原因，并检查状态页面上是否有相关通知。

要建立此类监控，你可以跟踪在一定时间内预期看到的新 Post 数量。如果某个 stream 的数据量显著低于指定阈值，且在设定时间内未恢复，则应触发告警与通知。你也可能需要监控数据量的大幅增长，尤其是在修改过滤的流中的规则期间，或发生导致 Post 活动激增的事件时。

需要注意，通过过滤的流传递的 Post 会计入每月 Post 总量，你应当跟踪并调整使用量以实现优化。若数据量较高，考虑在每条规则中添加 sample: 运算符，在必要时将匹配率从 100% 降至 sample:50 或 sample:25。

此外，我们鼓励你在 App 中实施相应措施：当数据量超过预设阈值时向团队发出警报；并在必要时引入其他措施，例如自动删除带来过多数据的规则，或在极端情况下完全断开与 stream 的连接。  

​

响应系统消息

Keep-alive 信号 至少每隔 20 秒，stream 会通过已打开的连接以 \r\n 回车符（心跳）的形式发送 keep-alive 信号，防止客户端超时。你的客户端应用应当能够容忍 stream 中的 \r\n 字符。

如果你的客户端在 HTTP 库中正确实现了读取超时，你的 App 将能够依赖 HTTP 协议和 HTTP 库在该时间内未读取到 data 时触发事件，而无需显式监控 \r\n 字符。

此事件通常体现为抛出异常，或因所用 HTTP 库不同而触发其他事件。强烈建议为你的 HTTP 方法添加错误/事件处理程序以检测这些超时。一旦超时，你的应用应尝试重新连接。

错误消息 v2 流式 endpoint 也可能在 stream 中传递错误消息。以下提供了这些消息的基本格式以及一些示例。请注意，传递的消息可能会变化，并可能引入新的消息。客户端应用需要能够容忍系统消息负载的变化。

请注意，错误消息将链接到描述如何解决问题的文档。

消息格式：

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

请注意，如果导致强制断开连接的积压阻止消息送达，那么指示因缓冲区已满而被强制断开的错误消息可能永远无法到达你的客户端。因此，你的 App 不应依赖这些消息来触发重新连接。