跳转到主要内容

​
构建用于消费流式数据的客户端

使用流式端点时，为了更好地利用资源，有一些通用的最佳实践需要注意。    

​
客户端设计

在使用过滤流端点构建解决方案时，您需要一个客户端能够执行以下操作：
  1. 与过滤流端点建立 HTTPS 流式连接。
  2. 以异步方式向过滤流规则端点发送 POST 请求，在流中添加或删除规则。
  3. 处理低数据量——保持流式连接，检测 Post 对象和保活信号。
  4. 处理高数据量——使用异步流程将流接入与后续处理解耦，并确保客户端缓冲区定期刷新。
  5. 在客户端管理用量消耗的跟踪。
  6. 检测流中断，评估后自动重新连接到流。  

​
连接到流式端点

与 X API v2 的流式端点建立连接，意味着发起一个长时间保持的 HTTP 请求，并持续增量解析响应。从概念上讲，可以将其看作通过 HTTP 下载一个“无限长”的文件。一旦连接建立，在连接保持打开的情况下，X 服务器会通过该连接持续传递 Post 事件。  

​
消费数据

请注意，JSON 对象的各字段没有固定顺序，且并非在所有情况下都会包含所有字段。同样，独立的活动不会以排序的顺序传递，且可能会遇到重复消息。请记住，随着时间推移，新的消息类型可能会被添加并通过流发送。 因此，你的客户端必须能够容错：
  • 字段以任意顺序出现
  • 意外或缺失的字段
  • 未排序的 Post
  • 重复的消息
  • 任何时间通过流传来的新的任意消息类型
除相关的 Post 数据和请求的 fields 参数外，通过流连接还可能传递以下类型的消息。请注意，此列表可能并不完整——流中可能会引入其他对象。请确保你的解析器能够容忍意外的消息格式。  

​
缓冲

流式端点会在数据可用时尽快将其发送给你，这在许多情况下会产生高数据量。如果 X 服务器无法立即向流中写入新数据（例如你的客户端读取速度不够快，详见处理断线），它会在其端对内容进行缓冲，以便你的客户端追上进度。然而，当该缓冲区已满时，会触发强制断开以中止连接，已缓冲的 Posts 将被丢弃且不会重发。详见下文。 识别你的应用是否出现滞后的一个方法，是将收到的 Posts 的时间戳与当前时间进行比较，并持续跟踪这一差异。 尽管由于公共互联网的潜在延迟和抖动，流阻塞无法被完全消除，但通过正确配置你的应用，基本可以避免。为尽量减少阻塞的发生：
  • 确保你的客户端以足够快的速度读取流。通常不应在读取流的同时进行实际处理工作。应先读取流，再将处理交给其他线程/进程/数据存储异步完成。
  • 确保你的数据中心具备足够的入站带宽，既能承载大规模的持续数据量，也能应对显著更大的峰值（例如为正常量的 5–10 倍）。对于过滤流，你端所需的流量和相应带宽完全取决于你的规则匹配到哪些 Posts。  

​
使用情况跟踪与规则管理

鉴于各开发者对其流的“正常”数据量预期并不一致，我们无法就具体的百分比增减或时间周期给出通用建议。 请监控流的数据量是否出现异常波动。数据量下降可能反映的是不同于流断开的其他问题。在这种情况下，流仍会接收保活信号，并可能继续收到部分新的活动数据。但如果 Post 数量显著减少，应调查是否存在导致你的应用或网络入站数据量下降的因素，并查看状态页是否有相关公告。 为实现此类监控，你可以在设定的时间窗口内跟踪预期出现的新 Post 数量。如果某个流的数据量大幅低于指定阈值，且在设定期限内未恢复，则应触发告警和通知。你也应监控数据量的显著增长，尤其是在你修改过滤流中的规则时，或发生导致 Post 活动激增的事件时。 需要注意的是，通过过滤流传递的 Post 会计入每月的 Post 总量，你应跟踪并调整消耗以实现优化。如果量很高，考虑为每条规则添加 sample: 运算符，将匹配率从 100% 降至必要时的 sample:50 或 sample:25。 此外，我们鼓励你在应用内实现相关措施：当数据量超过预设阈值时提醒你的团队，并在必要时引入其他手段，例如自动删除引入过多数据的规则，或在极端情况下完全断开与流的连接。  

​
响应系统消息

Keep-alive 信号 流会至少每 20 秒通过已打开的连接发送一个 keep-alive 信号（心跳），其形式为一个 \r\n 回车，以防止客户端超时。你的客户端应用应能容忍流中的 \r\n 字符。 如果你的客户端在 HTTP 库中正确实现了读取超时，你的应用就可以依赖 HTTP 协议和所用的 HTTP 库在该时段内未读取到 data 时触发事件，而无需显式监控 \r\n 字符。 该事件通常表现为抛出异常，或视所用 HTTP 库而定的其他事件。强烈建议为你的 HTTP 方法添加错误/事件处理程序以检测这些超时。发生超时时，你的应用应尝试重新连接。 错误消息 v2 流式端点也可能在流中传递错误消息。下面提供了这些消息的基本格式以及一些示例。请注意，传递的消息可能会发生变化，且可能引入新消息。客户端应用需要能够适应系统消息负载的变化。 请注意，错误消息会链接到文档，说明如何解决该 Problem。 消息格式： 
	"errors": [{
		"title": "operational-disconnect",
		"disconnect_type": "UpstreamOperationalDisconnect",
		"detail": "该数据流因运维原因已在上游断开连接。",
		"type": "https://api.x.com/2/problems/operational-disconnect"
	}]
}
请注意，指示因缓冲区已满而被强制断开的错误消息，可能永远无法到达你的客户端——触发强制断开的积压本身可能会阻止消息送达。因此，你的应用不应依赖这些消息来发起重新连接。