Back to Details

vtex-io-events-and-workers

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Events, Workers & Async Processing

事件、Worker与异步处理

When this skill applies

适用场景

Use this skill when a VTEX IO app needs to process work asynchronously through events, workers, or other background execution patterns.
  • Consuming broadcasted events from other VTEX services
  • Running background work that should not block HTTP responses
  • Designing retry-safe handlers
  • Processing batches or delayed jobs
  • Building async integrations with external services
Do not use this skill for:
  • defining HTTP route contracts
  • designing GraphQL schemas or resolvers
  • deciding app-level policies
  • low-level client construction
当你的VTEX IO应用需要通过事件、Worker或其他后台执行模式异步处理工作时，可使用本规范：
  • 消费其他VTEX服务广播的事件
  • 运行不应当阻塞HTTP响应的后台任务
  • 设计重试安全的处理程序
  • 处理批处理或延迟作业
  • 构建与外部服务的异步集成
本规范不适用于以下场景：
  • 定义HTTP路由契约
  • 设计GraphQL schema或解析器
  • 制定应用层级策略
  • 底层客户端构建

Decision rules

决策规则

  • Use events or workers when the work is expensive, retry-prone, or not required to complete inside a request-response cycle.
  • VTEX uses an internal event broadcaster to deliver platform and app events to your service. The same broadcaster can route events published by your app to other handlers. Assume at-least-once delivery semantics in both directions: events can be retried or replayed, so handlers must be idempotent and safe under duplicates.
  • Keep event handlers idempotent. The same event may be delivered more than once, so handlers must tolerate replay safely.
  • Persist idempotency and processing state in an appropriate store, such as VBase for keyed markers or Master Data for structured records, so handlers can detect duplicates, completed work, and failures across retries.
  • Declare events and workers explicitly in 
    service.json
    so they are wired into the IO runtime, and keep their input contracts stable and explicit instead of relying on HTTP route assumptions.
  • When you need to notify other apps or fan out work, publish events through the appropriate VTEX IO client or event mechanism instead of creating ad hoc HTTP callbacks just to simulate asynchronous delivery.
  • To publish events through the VTEX IO event bus, apps often need the 
    colossus-fire-event
    policy in 
    manifest.json
    . Add other policies only when the app actually consumes those protected resources as well.
  • Separate event ingestion from business orchestration when a handler grows beyond a small, clear unit of work.
  • Treat retries as expected behavior, not exceptional behavior. Design handlers so repeated execution is safe.
  • Keep background handlers explicit about side effects such as writes, external calls, or status transitions.
  • For batch-oriented handlers, process items in small, explicit units and record status per item so that a single failing element does not hide progress on the rest of the batch.
  • 当任务开销高、易重试，或不需要在请求-响应周期内完成时，使用事件或Worker。
  • VTEX使用内部事件广播器向你的服务交付平台和应用事件，同一个广播器也可以将你的应用发布的事件路由到其他处理程序。双向都默认遵循至少一次交付语义：事件可能会被重试或重放，因此处理程序必须是幂等的，在重复投递场景下也能安全运行。
  • 确保事件处理程序具备幂等性。同一个事件可能会被投递多次，因此处理程序必须能够安全应对重放场景。
  • 将幂等性和处理状态持久化到合适的存储中，比如用VBase存储键标识、用Master Data存储结构化记录，这样处理程序可以在重试过程中识别重复事件、已完成的工作和失败任务。
  • 在
    service.json
    中显式声明事件和Worker，这样它们才能被接入IO运行时，同时要保持输入契约稳定清晰，不要依赖HTTP路由的隐含假设。
  • 当你需要通知其他应用或者分发任务时，通过合适的VTEX IO客户端或事件机制发布事件，不要为了模拟异步投递自行实现临时HTTP回调。
  • 要通过VTEX IO事件总线发布事件，应用通常需要在
    manifest.json
    中配置
    colossus-fire-event
    权限。仅当应用确实需要使用受保护的资源时，再添加其他权限。
  • 当处理程序的逻辑超出单一清晰的工作单元时，将事件接收与业务编排逻辑拆分。
  • 将重试视为预期行为而非异常情况，设计处理程序时要保证重复执行是安全的。
  • 后台处理程序要显式处理副作用，比如写入操作、外部调用或状态流转。
  • 对于面向批处理的处理程序，以小型明确的单元处理条目，并记录每个条目的状态，避免单个元素失败导致整个批次的进度无法追踪。

Hard constraints

硬性约束

Constraint: Event handlers must be idempotent

约束：事件处理程序必须具备幂等性

Every event or background handler MUST tolerate duplicate execution without creating inconsistent side effects.
Why this matters
Async systems retry. Without idempotency, duplicate deliveries can create duplicated records, repeated partner calls, or invalid state transitions.
Detection
If the handler performs writes or external side effects without checking whether the work was already completed, STOP and add idempotency protection before proceeding.
Correct
typescript
export async function handleOrderCreated(ctx: Context) {
  const { orderId } = ctx.body
  const alreadyProcessed = await ctx.clients.statusStore.hasProcessed(orderId)

  if (alreadyProcessed) {
    return
  }

  await ctx.clients.partnerApi.sendOrder(orderId)
  await ctx.clients.statusStore.markProcessed(orderId)
}
Wrong
typescript
export async function handleOrderCreated(ctx: Context) {
  await ctx.clients.partnerApi.sendOrder(ctx.body.orderId)
}
所有事件或后台处理程序必须能够容忍重复执行，且不会产生不一致的副作用。
重要性
异步系统会触发重试。如果不具备幂等性，重复投递可能会导致记录重复、合作方接口重复调用，或者无效的状态流转。
检查规则
如果处理程序在执行写入操作或产生外部副作用前，没有检查任务是否已经完成，请立即停止开发，先添加幂等性保护逻辑再继续。
正确示例
typescript
export async function handleOrderCreated(ctx: Context) {
  const { orderId } = ctx.body
  const alreadyProcessed = await ctx.clients.statusStore.hasProcessed(orderId)

  if (alreadyProcessed) {
    return
  }

  await ctx.clients.partnerApi.sendOrder(orderId)
  await ctx.clients.statusStore.markProcessed(orderId)
}
错误示例
typescript
export async function handleOrderCreated(ctx: Context) {
  await ctx.clients.partnerApi.sendOrder(ctx.body.orderId)
}

Constraint: Background work must not rely on request-only assumptions

约束：后台任务不能依赖仅请求链路存在的隐含假设

Workers and event handlers MUST not depend on HTTP-only assumptions such as route params, immediate user interaction, or request-bound mutable state.
Why this matters
Async handlers run outside the route lifecycle. Reusing HTTP assumptions leads to missing context, brittle behavior, and accidental coupling between sync and async paths.
Detection
If an event handler expects request headers, route params, or a route-specific state shape, STOP and redesign the input contract so the handler receives explicit async data.
Correct
typescript
export async function handleImport(ctx: Context) {
  const { importId, account } = ctx.body
  await ctx.clients.importApi.process(importId, account)
}
Wrong
typescript
export async function handleImport(ctx: Context) {
  await ctx.clients.importApi.process(ctx.vtex.route.params.id, ctx.request.header.account)
}
Worker和事件处理程序不得依赖仅HTTP场景下存在的隐含假设，比如路由参数、即时用户交互，或者绑定到请求的可变状态。
重要性
异步处理程序运行在路由生命周期之外。复用HTTP场景的假设会导致上下文缺失、行为脆弱，以及同步和异步链路之间的意外耦合。
检查规则
如果事件处理程序依赖请求头、路由参数或者特定路由的状态结构，请立即停止开发，重新设计输入契约，确保处理程序接收显式的异步数据。
正确示例
typescript
export async function handleImport(ctx: Context) {
  const { importId, account } = ctx.body
  await ctx.clients.importApi.process(importId, account)
}
错误示例
typescript
export async function handleImport(ctx: Context) {
  await ctx.clients.importApi.process(ctx.vtex.route.params.id, ctx.request.header.account)
}

Constraint: Expensive async flows must surface partial failure clearly

约束：高开销异步流程必须清晰暴露部分失败的情况

Async handlers MUST make partial failures visible through state, logs, or durable markers instead of silently swallowing them.
Why this matters
Background failures are harder to see than route failures. Without explicit failure signaling, operations teams cannot tell whether work was skipped, retried, or partially completed.
Detection
If the handler catches errors without recording failure state, logging enough context, or rethrowing when appropriate, STOP and make failure handling explicit.
Correct
typescript
export async function handleSync(ctx: Context) {
  try {
    await ctx.clients.partnerApi.syncCatalog(ctx.body.catalogId)
    await ctx.clients.statusStore.markSuccess(ctx.body.catalogId)
  } catch (error) {
    await ctx.clients.statusStore.markFailure(ctx.body.catalogId)
    throw error
  }
}
Wrong
typescript
export async function handleSync(ctx: Context) {
  try {
    await ctx.clients.partnerApi.syncCatalog(ctx.body.catalogId)
  } catch (_) {
    return
  }
}
异步处理程序必须通过状态、日志或持久化标记让部分失败的情况可见，不能静默吞掉错误。
重要性
后台失败比路由失败更难被发现。如果没有显式的失败信号，运维团队无法判断任务是被跳过、正在重试还是部分完成。
检查规则
如果处理程序捕获错误后没有记录失败状态、没有打印足够的上下文信息，也没有在合适的时机重新抛出错误，请立即停止开发，显式实现失败处理逻辑。
正确示例
typescript
export async function handleSync(ctx: Context) {
  try {
    await ctx.clients.partnerApi.syncCatalog(ctx.body.catalogId)
    await ctx.clients.statusStore.markSuccess(ctx.body.catalogId)
  } catch (error) {
    await ctx.clients.statusStore.markFailure(ctx.body.catalogId)
    throw error
  }
}
错误示例
typescript
export async function handleSync(ctx: Context) {
  try {
    await ctx.clients.partnerApi.syncCatalog(ctx.body.catalogId)
  } catch (_) {
    return
  }
}

Preferred pattern

推荐模式

Recommended file layout:
text
node/
├── events/
│   ├── index.ts
│   ├── catalog.ts
│   └── orders.ts
└── workers/
    └── sync.ts
Minimal async handler pattern:
typescript
export async function handleCatalogChanged(ctx: Context) {
  const { skuId } = ctx.body
  const alreadyDone = await ctx.clients.syncState.isProcessed(skuId)

  if (alreadyDone) {
    return
  }

  await ctx.clients.catalogSync.syncSku(skuId)
  await ctx.clients.syncState.markProcessed(skuId)
}
Illustrative event publishing pattern:
typescript
export async function broadcast(ctx: Context, next: () => Promise<void>) {
  const {
    clients: { events },
    body: { payload, senderAppId, clientAppId },
  } = ctx

  for (const row of payload as unknown[]) {
    await events.sendEvent(clientAppId, 'my-app.event-name', {
      data: row,
      senderAppId,
    })
  }

  await next()
}
Minimal manifest policy for event publishing:
json
{
  "policies": [
    {
      "name": "colossus-fire-event"
    }
  ]
}
Use routes to acknowledge or trigger work, and use events or workers to perform slow, repeatable, and failure-aware processing.
Use storage intentionally for async state:
  • VBase for simple idempotency markers keyed by an external identifier
  • Master Data for structured processing records with status and timestamps
Treat the async payload as its own contract instead of reusing route-only assumptions from an HTTP request.
For fan-out or cross-app notifications, publish a small, well-defined event containing IDs and minimal metadata, then let downstream handlers fetch full details from the source of truth when needed instead of embedding large payloads or relying on custom callback URLs.
In development, use the Broadcaster app's 
Notify Target Workspace
setting in Admin to route events to a specific workspace instead of inventing ad hoc public routes or test-only delivery flows. Handlers should still behave correctly regardless of which workspace receives the event.
推荐的文件结构：
text
node/
├── events/
│   ├── index.ts
│   ├── catalog.ts
│   └── orders.ts
└── workers/
    └── sync.ts
最简异步处理程序模式：
typescript
export async function handleCatalogChanged(ctx: Context) {
  const { skuId } = ctx.body
  const alreadyDone = await ctx.clients.syncState.isProcessed(skuId)

  if (alreadyDone) {
    return
  }

  await ctx.clients.catalogSync.syncSku(skuId)
  await ctx.clients.syncState.markProcessed(skuId)
}
事件发布示例模式：
typescript
export async function broadcast(ctx: Context, next: () => Promise<void>) {
  const {
    clients: { events },
    body: { payload, senderAppId, clientAppId },
  } = ctx

  for (const row of payload as unknown[]) {
    await events.sendEvent(clientAppId, 'my-app.event-name', {
      data: row,
      senderAppId,
    })
  }

  await next()
}
事件发布所需的最小manifest权限配置：
json
{
  "policies": [
    {
      "name": "colossus-fire-event"
    }
  ]
}
使用路由来确认或触发任务，使用事件或Worker来执行缓慢、可重复、支持失败处理的任务。
合理使用存储来保存异步状态：
  • 用VBase存储基于外部标识的简单幂等性标记
  • 用Master Data存储包含状态和时间戳的结构化处理记录
将异步 payload 视为独立的契约，不要复用HTTP请求中仅路由场景适用的隐含假设。
对于扇出场景或跨应用通知，发布包含ID和最小元数据的小型明确事件，让下游处理程序在需要时从可信源拉取完整详情，不要嵌入大型payload或者依赖自定义回调URL。
开发过程中，使用Admin中Broadcaster应用的
Notify Target Workspace
设置将事件路由到指定工作区，不要自行实现临时公开路由或者仅测试用的投递流程。无论哪个工作区接收到事件，处理程序都应该正常运行。

Common failure modes

常见故障模式

  • Treating event delivery as exactly-once instead of at-least-once.
  • Reusing HTTP route assumptions inside workers or event handlers.
  • Swallowing background errors without explicit failure state.
  • Letting one event handler orchestrate too many unrelated side effects.
  • Performing expensive work synchronously in routes instead of moving it to async processing.
  • Logging full event payloads with secrets or tokens instead of using IDs and metadata for correlation.
  • 将事件投递视为恰好一次而非至少一次
  • 在Worker或事件处理程序中复用HTTP路由的隐含假设
  • 静默吞掉后台错误，没有显式记录失败状态
  • 单个事件处理程序编排了太多不相关的副作用
  • 在路由中同步执行高开销任务，没有转移到异步处理流程
  • 打印包含密钥或令牌的完整事件payload，没有使用ID和元数据来做关联

Review checklist

评审检查清单

  • Is async processing the right mechanism for this work?
  • Is the handler idempotent under duplicate delivery?
  • Is idempotency or processing state stored in an appropriate backend such as VBase or Master Data?
  • Are events and workers declared explicitly in 
    service.json
    ?
  • Are background inputs explicit and independent from HTTP route assumptions?
  • Are failures surfaced clearly enough for retry and troubleshooting?
  • For batch processing, is status visible per item or per small unit of work?
  • Should large handlers be split into smaller async units or orchestration steps?
  • 异步处理是不是当前任务的合适实现机制？
  • 处理程序在重复投递场景下是否具备幂等性？
  • 幂等性或处理状态是否存储在合适的后端（比如VBase或Master Data）中？
  • 事件和Worker是否在
    service.json
    中显式声明？
  • 后台输入是否是显式的，且不依赖HTTP路由的隐含假设？
  • 失败情况是否清晰暴露，支持重试和故障排查？
  • 对于批处理场景，是否可以查看每个条目或每个小型工作单元的状态？
  • 大型处理程序是否需要拆分为更小的异步单元或编排步骤？

Related skills

相关技能

  • vtex-io-data-access-patterns
     - Use when choosing where idempotency keys, sync state, or processing records should live
  • vtex-io-observability-and-ops
     - Use when the main question is how async failures should be logged, measured, and monitored
  • vtex-io-data-access-patterns
     - 适用于选择幂等键、同步状态或处理记录的存储位置的场景
  • vtex-io-observability-and-ops
     - 适用于需要确定异步失败的日志、度量和监控方式的场景

Reference

参考资料

  • Service - Event declaration and service execution model
  • Node Builder - Backend file structure for services
  • Broadcaster - Internal event delivery context and the 
    Notify Target Workspace
    setting for development
  • Service - 事件声明和服务执行模型
  • Node Builder - 服务的后端文件结构
  • Broadcaster - 内部事件交付上下文和开发用的
    Notify Target Workspace
    设置