iii-dead-letter-queues

死信队列

类似于：SQS DLQ、RabbitMQ 死信交换器

核心概念

在适用于任务的情况下使用以下概念。并非每次队列故障都需要手动处理 DLQ。

• 作业在指数退避（backoff_ms * 2^attempt）下用尽 max_retries 后会移至 DLQ
• 每个 DLQ 条目都会保留原始载荷、最后一次错误、时间戳和作业元数据
• 通过内置的 iii::queue::redrive 函数或 iii trigger CLI 命令重新投递
• 重新投递会将尝试计数器重置为零，让作业开始全新的重试周期
• 重新投递前务必调查问题并部署修复方案——盲目重新投递只会重复失败
• Builtin 和 RabbitMQ 适配器均支持 DLQ

架构

队列消费者处理作业失败后，引擎会以指数退避方式重试，最多重试 max_retries 次。重试次数用尽后，消息会移至 DLQ。操作员检查故障、部署修复方案，然后重新投递 DLQ，以重放所有失败的作业。

使用的 iii 原语

原语	用途
trigger({ function_id: 'iii::queue::redrive', payload: { queue } })	重新投递指定队列中的所有 DLQ 作业
trigger({ function_id: 'iii::queue::status', payload: { queue } })	检查队列和 DLQ 状态
iii trigger --function-id='iii::queue::redrive' --payload='{"queue":"name"}'	CLI 重新投递命令（属于引擎二进制文件）
--timeout-ms	用于设置触发器超时时间的 CLI 标志（默认 30s）
iii-config.yaml 中的 queue_configs	配置 max_retries 和 backoff_ms

参考实现

完整的可运行示例见 ../references/dead-letter-queues.js——检查 DLQ 状态，

也提供 Python 版本：../references/dead-letter-queues.py

也提供 Rust 版本：../references/dead-letter-queues.rs 该示例展示如何通过 SDK 和 CLI 重新投递失败作业，以及如何配置重试行为。

常见模式

使用此模式的代码通常会在适用时包含：

• await iii.trigger({ function_id: 'iii::queue::redrive', payload: { queue: 'payment' } }) — 通过 SDK 重新投递
• iii trigger --function-id='iii::queue::redrive' --payload='{"queue": "payment"}' — 通过 CLI 重新投递
• iii trigger --function-id='iii::queue::redrive' --payload='{"queue": "payment"}' --timeout-ms=60000 — 使用自定义超时时间
• 重新投递会返回 { queue: 'payment', redriven: 12 }，表示重放的作业数量
• 在 RabbitMQ UI 的 http://localhost:15672 中检查，找到 iii.__fn_queue::{name}::dlq.queue
• 最佳实践：调查故障、部署修复方案，然后重新投递
• 将 DLQ 深度作为运维告警信号进行监控

调整此模式

在适用于任务的情况下使用以下调整方式。

• 根据对故障的容忍程度，在 queue_configs 中设置 max_retries 和 backoff_ms
• 构建一个调用 iii::queue::redrive 的管理端点，以便进行运维控制
• 使用 iii::queue::status 检查重新投递前后的 DLQ 深度
• 在开发/测试环境中使用较低的重试次数，以便更快发现故障
• 在使用 RabbitMQ 的生产环境中，使用管理 UI 详细检查消息
• 考虑构建一个在 DLQ 深度达到阈值时触发的告警函数

引擎配置

在 iii-config.yaml 的 queue_configs 下，按队列设置 max_retries 和 backoff_ms。完整的带注释配置参考见 ../references/iii-config.yaml。

模式边界

• 对于队列处理模式（入队、并发、FIFO），优先使用 iii-queue-processing。
• 对于队列配置（重试、退避、适配器），优先使用 iii-engine-config。
• 对于函数注册和触发器，优先使用 iii-functions-and-triggers。
• 如果主要问题是检查或重新执行失败的作业，则使用 iii-dead-letter-queues。

适用场景

• 当任务主要涉及 iii 引擎中的 iii-dead-letter-queues 时，使用此技能。
• 当请求直接要求此模式或等效实现时，触发此技能。

边界

• 切勿将此技能用作无关任务的通用备用方案。
• 如果有更具体的 iii 技能更适合，切勿应用此技能。
• 应用此技能中的示例前，务必确认环境和安全约束。