encore-pubsub

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Encore Pub/Sub

Instructions

使用说明

Pub/Sub is for asynchronous messaging between services. Producers publish events to a

Topic

; consumers attach

Subscription

s to react. Resources must be declared at package level — never inside functions.

Pub/Sub用于服务间的异步消息传递。生产者将事件发布到

Topic

；消费者通过附加

Subscription

来响应事件。资源必须在包级别声明——绝不能在函数内部声明。

Topics

主题（Topics）

typescript

import { Topic } from "encore.dev/pubsub";

interface OrderCreatedEvent {
  orderId: string;
  userId: string;
  total: number;
}

// Package level declaration
export const orderCreated = new Topic<OrderCreatedEvent>("order-created", {
  deliveryGuarantee: "at-least-once",
});

typescript

import { Topic } from "encore.dev/pubsub";

interface OrderCreatedEvent {
  orderId: string;
  userId: string;
  total: number;
}

// 包级别声明
export const orderCreated = new Topic<OrderCreatedEvent>("order-created", {
  deliveryGuarantee: "at-least-once",
});

Publishing

发布消息（Publishing）

typescript

await orderCreated.publish({
  orderId: "123",
  userId: "user-456",
  total: 99.99,
});

typescript

await orderCreated.publish({
  orderId: "123",
  userId: "user-456",
  total: 99.99,
});

Subscriptions

订阅（Subscriptions）

typescript

import { Subscription } from "encore.dev/pubsub";

const _ = new Subscription(orderCreated, "send-confirmation-email", {
  handler: async (event) => {
    await sendEmail(event.userId, event.orderId);
  },
});

typescript

import { Subscription } from "encore.dev/pubsub";

const _ = new Subscription(orderCreated, "send-confirmation-email", {
  handler: async (event) => {
    await sendEmail(event.userId, event.orderId);
  },
});

Message Attributes

消息属性（Message Attributes）

Use

Attribute<T>

for fields that should be treated as message attributes (for filtering/ordering):

typescript

import { Topic, Attribute } from "encore.dev/pubsub";

interface CartEvent {
  cartId: Attribute<string>;  // Used for ordering
  userId: string;
  action: "add" | "remove";
  productId: string;
}

// Ordered topic: events with same cartId delivered in order
export const cartEvents = new Topic<CartEvent>("cart-events", {
  deliveryGuarantee: "at-least-once",
  orderingAttribute: "cartId",
});

使用

Attribute<T>

标记应被视为消息属性的字段（用于过滤/排序）：

typescript

import { Topic, Attribute } from "encore.dev/pubsub";

interface CartEvent {
  cartId: Attribute<string>;  // 用于排序
  userId: string;
  action: "add" | "remove";
  productId: string;
}

// 有序主题：具有相同cartId的事件按顺序传递
export const cartEvents = new Topic<CartEvent>("cart-events", {
  deliveryGuarantee: "at-least-once",
  orderingAttribute: "cartId",
});

Topic References

主题引用（Topic References）

Pass topic access to other code while maintaining static analysis:

typescript

import { Publisher } from "encore.dev/pubsub";

const publisherRef = orderCreated.ref<Publisher>();

async function notifyOrder(ref: typeof publisherRef, orderId: string) {
  await ref.publish({ orderId, userId: "123", total: 99.99 });
}

在保持静态分析能力的同时，将主题访问权限传递给其他代码：

typescript

import { Publisher } from "encore.dev/pubsub";

const publisherRef = orderCreated.ref<Publisher>();

async function notifyOrder(ref: typeof publisherRef, orderId: string) {
  await ref.publish({ orderId, userId: "123", total: 99.99 });
}

Delivery Guarantees

交付保障（Delivery Guarantees）

```
at-least-once
```
(default): may deliver duplicates → handlers must be idempotent.
```
exactly-once
```
: stricter, capped throughput (AWS 300 msg/s/topic, GCP 3000+ msg/s/region). Does not deduplicate on the publish side.

```
at-least-once
```
（默认）：可能会传递重复消息 → 处理器必须具备幂等性。
```
exactly-once
```
：保障更严格，但吞吐量受限（AWS 300条消息/秒/主题，GCP 3000+条消息/秒/区域）。不会在发布端进行去重。

Guidelines

指导原则（Guidelines）

Topics and subscriptions must be declared at package level.
Subscription handlers must be idempotent (at-least-once delivery is the default).
Use
```
Attribute<T>
```
for fields meant for filtering/ordering, not for arbitrary metadata.
Don't do heavy synchronous work in
```
publish
```
callers —
```
publish
```
returns once the message is queued.

主题和订阅必须在包级别声明。
订阅处理器必须具备幂等性（默认交付保障为至少一次）。
仅对用于过滤/排序的字段使用
```
Attribute<T>
```
，不要用于任意元数据。
不要在
```
publish
```
调用方中执行繁重的同步工作——
```
publish
```
在消息入队后立即返回。