SuperAPI AI 工具集

implement-background-job

编程与开发

查看项目

更新于 10-27 13:02

技能介绍

用途

该技能用于在 Rails 应用中添加、配置或审查后台任务,覆盖 Active Job、Sidekiq 和 Solid Queue worker。触发词包括 background job、Active Job、Sidekiq、Solid Queue 等。

主要能力

  • 强制测试先行:每个任务必须先编写并验证测试(幂等性、重试、错误处理),确认测试失败后再实现任务类。
  • 定义 perform 契约:每个 perform 方法只做三件事——按传入 ID 加载记录、做幂等或永久无操作守卫、把副作用或编排委托给服务对象。若 perform 需要更多逻辑,应抽取服务对象。
  • 要求副作用前有幂等检查:任何执行副作用(扣款、发邮件、调用 API)的任务,都必须在副作用之前做幂等检查。
  • 核心规则:参数传 ID 而非对象;瞬时错误用 retry_on 并显式指定 attempts;永久错误用 discard_on;Rails 8 使用数据库驱动的 Solid Queue(无需 Redis),Rails 7 及更早使用 Sidekiq + Redis 应对高吞吐;周期性任务在 config/recurring.yml(Solid Queue)或 cron/sidekiq-cron 中定义。
  • 反模式清单:禁止用 ActiveRecord 对象作为参数;禁止在生产环境使用 :inline/:async;禁止在 perform 中写业务逻辑。

使用方式

核心流程:

  1. 先写任务测试(幂等、重试、错误处理),运行并确认失败。
  2. 按 perform 契约编写任务类。
  3. 添加带显式 attempts 限制的 retry_on,以及至少一个永久错误的 discard_on。
  4. 运行完整测试套件。
  5. 将任务入队或执行两次,确认第二次为无操作。
  6. 周期性任务在 config/recurring.yml(Rails 8)或所选调度器配置中定义。

示例(薄任务 + 幂等 + 重试):

class SendInvoiceReminderJob < ApplicationJob
  queue_as :default
  retry_on Net::OpenTimeout, wait: :polynomially_longer, attempts: 5
  discard_on ActiveRecord::RecordNotFound

  def perform(invoice_id)
    invoice = Invoice.find(invoice_id)
    return if invoice.reminder_sent_at?

    InvoiceReminders::Send.call(invoice:)
  end
end

服务对象负责副作用与状态更新:

module InvoiceReminders
  class Send
    def self.call(invoice:)
      InvoiceMailer.overdue(invoice).deliver_now
      invoice.update!(reminder_sent_at: Time.current)
    end
  end
end

适用场景

  • 在 Rails 应用中新增后台任务。
  • 审查现有后台任务的幂等性、重试与错误处理。
  • 在 Rails 7 与 Rails 8 之间选择后台任务后端。
  • 配置周期性任务。
  • 需要多步编排或批量任务模式时,可加载 assets/job_patterns.md;需要针对特定错误类配置 retry_on/discard_on 时,可加载 assets/retry_examples.md。

限制

  • 该技能面向 Rails 应用,未提供其他语言或框架的用法。
  • 未提供具体安装命令、收费或价格信息。
  • 未提供官方文档或外部链接。
  • 输出检查清单要求:说明后端选型(Rails 版本/规模 → Solid Queue 或 Sidekiq);先展示任务测试、运行命令并确认实现前失败;perform 接收 ID、加载记录、守卫幂等、委托服务;retry_on 带 attempts 限制且 discard_on 处理永久错误;双次运行验证第二次为无操作;周期性任务(如有)定义在 config/recurring.yml 或调度器配置中;若需要运维文档,在 process_log.md 中记录后端、重试、周期调度和幂等决策。
  • 集成建议:与 review-migration 链式使用(Solid Queue 使用数据库表,需安全添加迁移);与 security-check 链式使用(任务接收序列化输入,需像任何入口点一样校验);与 write-tests 链式使用(TDD 门禁:实现前写任务测试,使用 perform_enqueued_jobs);与 create-service-object 链式使用(保持 perform 精简,业务逻辑调用服务对象)。