implement-background-job

实现后台任务

当任务是添加、配置或审查 Rails 应用中的后台任务时，使用本技能。

HARD-GATE

EVERY job MUST have its test written and validated BEFORE implementation:
  1. Write the job spec (idempotency, retry, error handling)
  2. Run the spec — verify it fails
  3. ONLY THEN write the job class

The authoritative perform contract — EVERY perform method does exactly three things:
  1. Load the record from the passed ID
  2. Guard for idempotency / permanent no-op conditions
  3. Delegate the side effect or orchestration to a service object

If perform needs more than that, extract a service.
EVERY job that performs a side effect (charge, email, API call) MUST have
an idempotency check BEFORE the side effect.

核心规则

方面	规则
参数	传递 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. 按照 HARD-GATE 中的 perform 契约编写任务类。
3. 添加带显式 attempts: 限制的 retry_on，以及针对至少一个永久性错误的 discard_on。
4. 运行完整测试套件。
5. 将任务入队或执行两次 — 确认第二次运行为空操作。
6. 对于周期性任务，在 config/recurring.yml（Rails 8）或所选调度器配置中定义它们。

扩展资源

Rails 8 与 Rails 7

方面	Rails 7 及更早版本	Rails 8
默认	无默认值；设置 queue_adapter（通常是 Sidekiq）	Solid Queue（基于数据库）
开发/测试	:async 或 :inline	相同
周期性任务	外部（cron、sidekiq-cron）	config/recurring.yml
仪表板	第三方（Sidekiq Web）	Mission Control Jobs

示例

具有幂等性和重试的精简任务：

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

• BACKENDS.md — Solid Queue 与 Sidekiq 的设置、配置细节以及 Redis 要求。 仅在需要其特定内容时加载这些文件：

• assets/job_patterns.md — 在实现多步骤编排或批量任务模式时使用

• assets/retry_examples.md — 在为上述基本模式之外的特定错误类配置 retry_on/discard_on 时使用

输出检查清单

• 已说明后端决策（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 精简；调用服务对象处理业务逻辑