background-job
Use when running the full background-job loop: design, TDD, retry, monitor. Trigger words: background job, async processing, Sidekiq, Solid Queue, Active Job, worker.
igmarin · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add igmarin/rails-agent-skills --skill background-job技能说明
name: background-job type: persona tags: [personas] license: MIT description: > Use when running the full background-job loop: design, TDD, retry, monitor. Trigger words: background job, async processing, Sidekiq, Solid Queue, Active Job, worker. metadata: version: 1.0.0 user-invocable: "true" entry_point: "Invoke when implementing background jobs with proper retry/discard strategies and monitoring" phases: "Phase 1: Job Design, Phase 2: TDD Implementation, Phase 3: Retry/Discard Configuration, Phase 4: Testing & Monitoring" hard_gates: "Job Design Complete, Tests Pass, Retry Strategy Configured, Failure Scenarios Tested" dependencies: - source: self skills: [implement-background-job, write-tests] - source: ruby-core-skills skills: [tdd-process] keywords: rails, background-job, async, sidekiq, solid-queue, active-job, retry, monitoring
Background Job Persona
Orchestrates robust background job implementation with TDD discipline, proper retry/discard strategies, comprehensive failure scenario testing, and production monitoring to ensure reliable async processing.
Phase 1: Job Design
Objective: Define job responsibilities, idempotency strategy, and error classification before writing code.
Steps:
- Job Purpose — Define trigger conditions, input parameters, expected output/side effects, and criticality.
- Idempotency — Design job to be safely re-runnable: use unique job keys, status checks, or sentinel timestamps.
- Error Classification — Classify all anticipated errors:
- Transient (network timeouts, rate limits) → retry
- Permanent (invalid data, record not found) → discard
- Configuration (missing credentials) → alert
- Queue & Timeout — Assign queue priority and set execution timeout.
HARD GATE — Job Design Complete:
- Purpose, trigger, input/output defined
- Idempotency strategy specified
- All errors classified as transient/permanent
- Queue and timeout values chosen
If gate fails: Clarify requirements before implementation.
Phase 2: TDD Implementation
Objective: Implement job logic under TDD discipline.
Steps:
- Choose unit vs. integration test approach.
- Write failing tests covering: successful execution, idempotency (run twice = same result), transient error raises, permanent error discards.
- Confirm tests FAIL for the right reason (job not yet implemented).
- Propose implementation approach and wait for explicit user approval.
- Implement job using the structure shown in Phase 3 (retry/discard declarations included from the start); confirm tests PASS.
- Run full test suite — confirm no regressions.
HARD GATE — Tests Pass:
- Tests exist and run
- Tests failed before implementation
- All tests pass after implementation
- Full suite green
Example job test skeleton (for OrderConfirmationEmailJob — see Phase 3 for the matching implementation):
# spec/jobs/order_confirmation_email_job_spec.rb
RSpec.describe OrderConfirmationEmailJob do
let(:order) { create(:order, :completed) }
it 'sends confirmation email' do
expect(EmailService).to receive(:send_confirmation).with(order.id, order.customer_email, order.total)
described_class.perform_now(order.id, order.customer_email, order.total)
end
it 'is idempotent' do
expect(EmailService).to receive(:send_confirmation).once
2.times { described_class.perform_now(order.id, order.customer_email, order.total) }
end
it 'raises on transient errors so retry triggers' do
allow(EmailService).to receive(:send_confirmation).and_raise(EmailService::TimeoutError)
expect { described_class.perform_now(order.id, order.customer_email, order.total) }.to raise_error(EmailService::TimeoutError)
end
it 'logs and re-raises on transient error' do
allow(EmailService).to receive(:send_confirmation).and_raise(EmailService::TimeoutError)
expect(Rails.logger).to receive(:error).with(/transient error/)
expect { described_class.perform_now(order.id, order.customer_email, order.total) }
.to raise_error(EmailService::TimeoutError)
end
it 'discards silently on permanent error' do
allow(EmailService).to receive(:send_confirmation).and_raise(EmailService::InvalidEmailError)
expect { described_class.perform_now(order.id, "bad", order.total) }.not_to raise_error
end
end
Phase 3: Retry/Discard Configuration
Objective: Harden job for production with correct retry backoff, discard rules, timeouts, and monitoring hooks.
Steps:
- Choose backend (Solid Queue for Rails 8+, Sidekiq for high scale) and configure worker concurrency.
- Apply
retry_onwith exponential backoff and a capped attempt count (3–5) for every transient error class. - Apply
discard_onfor every permanent error class; log discards. - Set job execution timeout and queue timeout at the worker/config level.
- Wire error tracking (e.g., Sentry) and metrics (e.g., StatsD/Datadog) in
ApplicationJobcallbacks.
Complete job implementation (matches the test skeleton in Phase 2):
# app/jobs/order_confirmation_email_job.rb
class OrderConfirmationEmailJob < ApplicationJob
queue_as :default
retry_on EmailService::TimeoutError, wait: :exponentially_longer, attempts: 5
retry_on EmailService::RateLimitError, wait: :exponentially_longer, attempts: 3
discard_on ActiveRecord::RecordNotFound
discard_on EmailService::InvalidEmailError
def perform(order_id, customer_email, order_total)
order = Order.find(order_id)
return if order.email_sent_at.present? # idempotency guard
EmailService.send_confirmation(order_id, customer_email, order_total)
order.update!(email_sent_at: Time.current)
rescue EmailService::TimeoutError, EmailService::RateLimitError => e
Rails.logger.error("[#{self.class}] transient error: #{e.message}")
raise
end
end
Solid Queue (Rails 8+) snippet:
#
阅读完整来源 ↗