用途:面向生产环境的 Clay 数据增强管线可靠性模式。因 Clay 采用异步增强、按信用计费并依赖 150+ 外部数据源,需专门设计容错策略,包括信用预算熔断、Webhook 投递追踪、失败批次死信队列,以及 Clay 不可用时的优雅降级。
前置条件:已处于生产或预生产的 Clay 集成、用于状态追踪的 Redis 或类似存储、理解 Clay 异步增强模型、监控基础设施(见 clay-observability)。
主要能力:
- 信用预算熔断器 CreditCircuitBreaker:closed/open/half-open 三态,超过每日信用上限或连续失败达阈值时停止处理,冷却后进入 half-open 试探,恢复成功则回到 closed。
- 死信队列 ClayDLQ:将失败行连同错误、webhook、失败时间、重试次数入队,retryAll 按 maxRetries 重试并限速 500ms,超限计为永久失败,getStats 统计待处理量与按错误分类。
- Webhook 健康监控 WebhookHealthMonitor:记录成功/失败,按 5 分钟窗口计算健康分,>95 健康、>80 降级、否则不健康。
- 优雅降级 ClayWithFallback:先请求 Clay,失败后依次尝试缓存、离线队列、最小本地增强(由域名推断公司名),drainOfflineQueue 在恢复后排空队列。
- 组合管线 reliableEnrich:先查熔断器,通过后请求 webhook,成功记录信用与健康,失败则记录熔断并写入 DLQ。
使用方式:按步骤引入各模块,配置 dailyLimit、failureThreshold、cooldownMinutes、FallbackConfig 等参数,并组合成可靠管线调用。输出可靠性回执,含工作负载范围、幂等键、队列/DLQ 状态、熔断与信用状态、重试次数、健康结果、操作员决定与恢复证据。
限制:需 Redis 等状态存储与监控设施;本地降级能力有限;示例代码与阈值需按实际情况调整,避免编造实际费率或效果。