PGQueuer v0.21.0版本发布：强化队列监听与执行可靠性

PGQueuer是一个基于PostgreSQL的轻量级任务队列系统，它利用PostgreSQL的NOTIFY/LISTEN机制实现高效的任务分发。该系统特别适合需要高可靠性和事务性保证的应用场景，如金融交易处理、订单系统等。

版本核心改进

本次v0.21.0版本主要围绕系统可靠性进行了多项重要改进，同时也移除了一些过时的API接口。这些变更虽然带来了少量兼容性问题，但显著提升了系统的稳定性和可维护性。

监听器健康检查机制

新版本引入了监听器健康检查功能，这是本次更新最重要的改进之一。系统现在会定期（默认每10秒）发送HealthCheckEvent事件，并期望监听器能够正确响应。如果监听器未能及时响应，系统将抛出FailingListenerError异常。

这一机制解决了长期存在的"静默失败"问题。在之前的版本中，如果监听器意外停止工作，系统可能继续运行但无法接收新任务，导致任务积压而不被发现。现在，开发者可以选择让系统在检测到监听器故障时自动关闭，便于监控系统及时发现并重启服务。

启用方式有两种：

1. 通过命令行参数：

pgqueuer run ... --shutdown-on-listener-failure

2. 在代码中显式设置：

await qm.run(..., shutdown_on_listener_failure=True)

SQL执行重试机制优化

任务执行过程中的重试逻辑得到了显著增强。新版本确保重试操作会严格遵循两个关键配置参数：

• serialized_dispatch：控制任务是否按顺序执行
• concurrency_limit：限制并发任务数量

这一改进使得系统在面对临时性数据库问题时表现更加稳定，特别是在高负载场景下，避免了因重试导致的任务堆积或执行顺序混乱。

不兼容变更与迁移指南

工厂函数路径语法变更

移除了旧式的"点分隔"工厂路径语法（如pkg.mod.factory），统一使用冒号分隔形式（pkg.mod:factory）。这一变更简化了语法解析逻辑，提高了代码可读性。

迁移示例：

- pgqueuer run myapp.factories.build
+ pgqueuer run myapp.factories:build

执行器配置方式变更

移除了所有executor=参数，统一使用executor_factory=。这一变更使得执行器创建逻辑更加灵活，可以基于运行时上下文动态创建执行器实例。

迁移示例：

- @qm.entrypoint("resize", executor=MyExecutor)
+ @qm.entrypoint("resize", executor_factory=lambda _: MyExecutor)

日志级别处理标准化

命令行工具的--log-level参数现在会自动将输入值转换为大写，消除了之前因大小写不一致导致的配置问题。这一改进使得在各种环境下（如不同操作系统）的日志配置行为更加一致。

运维建议

1. 监控配置调整：如果启用了监听器快速失败功能，需要确保监控系统能够检测到进程退出并自动重启服务。对于使用systemd的场景，可以配置Restart=on-failure；在Kubernetes环境中，则需要配置适当的liveness probe。

2. 重试策略评估：由于SQL重试机制的改进，建议重新评估现有任务的max_retries配置，确保其与业务需求匹配。对于关键任务，可能需要增加重试次数；而非关键任务则可以适当减少以避免资源浪费。

3. 日志收集适配：日志级别处理的变更可能影响现有的日志收集和分析管道，特别是那些依赖精确字符串匹配的过滤规则。建议检查并更新相关配置。

总结

PGQueuer v0.21.0通过引入监听器健康检查、优化重试机制等改进，显著提升了系统的可靠性。虽然带来了一些不兼容变更，但迁移成本相对较低，且这些变更有助于代码的长期维护。对于生产环境用户，特别是那些对系统可靠性要求较高的场景，建议尽快评估并升级到新版本。