Best Practices
1. Keep Workflows Simple
Workflows should be thin orchestration layers that coordinate tasks. Put complex business logic, calculations, and external interactions inside tasks, not in the workflow itself. This keeps your workflow deterministic and makes individual pieces easier to test and reuse.
Good: Simple orchestration logic
1#[workflow(name = "process_order", version = "1.0.0")]2pub async fn process_order(ctx: WorkflowContext, order_id: String) -> Result<String> {3 ctx.execute_task(validate, order_id.clone()).await?;4 ctx.execute_task(charge, order_id.clone()).await?;5 ctx.execute_task(fulfill, order_id).await?;6 Ok("Done".to_string())7}Bad: Complex business logic in workflow
1#[workflow(name = "complex_order", version = "1.0.0")]2pub async fn complex_order(ctx: WorkflowContext, order_id: String) -> Result<String> {3 // Don't put complex calculations in workflows — they must be deterministic4 // and this logic is harder to test in isolation5 let tax = calculate_complex_tax(&order_id)?;6 let discount = apply_promotional_rules(&order_id)?;7 // ... more complex logic8 Ok("Done".to_string())9}2. Use Descriptive Names
Task and workflow names appear in logs, dashboards, and the execution history. Clear names make debugging and monitoring significantly easier. Choose names that describe the action being performed, not generic labels.
1// Good: Clear intent — you know exactly what each step does2ctx.execute_task(charge_credit_card, payment_info).await?;3ctx.execute_task(send_confirmation_email, email_data).await?;45// Bad: Vague names — impossible to debug from logs6ctx.execute_task(task1, data).await?;7ctx.execute_task(process, info).await?;3. Handle Errors Explicitly
Don't let errors silently propagate. If a step fails, decide whether to retry, compensate, or fail the workflow. Explicit error handling makes your workflow's behavior predictable and makes failures easier to diagnose.
1let result = ctx.execute_task(risky_operation, data).await;23match result {4 Ok(value) => {5 // Handle success6 }7 Err(e) => {8 // Run compensation or retry logic9 ctx.execute_task(rollback, data).await?;10 }11}4. Use Timeouts
Always set timeouts on wait_for_event calls. Without a timeout, a workflow waiting for an event that never arrives will remain suspended forever. Timeouts give you a way to handle the "no response" case — sending a reminder, escalating, or failing gracefully.
Durable sleeps are also useful for implementing retry delays, rate limiting, and scheduled actions.
1use std::time::Duration;23// Set reasonable timeouts for external events4ctx.wait_for_event_with_timeout("approval", Duration::from_secs(86400)).await?;56// Use sleep for durable delays7ctx.sleep(Duration::from_secs(3600)).await?;5. Make Tasks Idempotent
Idempotent means "safe to execute more than once with the same effect." While Orcher's journaling prevents duplicate execution during normal replay, tasks can be retried due to transient failures (network timeouts, worker crashes). If a task makes an external API call, use idempotency keys to ensure the external system doesn't process the request twice.
1#[task(name = "charge_card", retry = 3)]2pub async fn charge_card(_ctx: TaskContext, input: PaymentInput) -> Result<ChargeResult> {3 // Use idempotency keys for external APIs4 stripe::Charge::create(&stripe_client, ChargeParams {5 idempotency_key: Some(format!("charge_{}", input.order_id)),6 amount: input.amount,7 // ...8 }).await?;9}Next Steps
Tasks
Learn how to define and execute tasks within workflows
Use Cases
Explore real-world workflow patterns and examples
Related Guides
- Tasks - Define durable task implementations
- State Management - Manage workflow state
- Error Handling - Handle failures gracefully
- Saga Pattern - Distributed transactions