encore-go-pubsub

Encore Go Pub/Sub

说明

Pub/Sub 用于服务之间的异步消息传递。生产者向 Topic 发布事件；消费者附加 Subscription 以作出响应。资源必须声明为包级变量，绝不能在函数内声明。

主题

package events

import "encore.dev/pubsub"

type OrderCreatedEvent struct {
    OrderID string `json:"order_id"`
    UserID  string `json:"user_id"`
    Total   int    `json:"total"`
}

// Package level declaration
var OrderCreated = pubsub.NewTopic[*OrderCreatedEvent]("order-created", pubsub.TopicConfig{
    DeliveryGuarantee: pubsub.AtLeastOnce,
})

发布

msgID, err := events.OrderCreated.Publish(ctx, &events.OrderCreatedEvent{
    OrderID: "123",
    UserID:  "user-456",
    Total:   9999,
})

订阅

package notifications

import (
    "context"
    "myapp/events"
    "encore.dev/pubsub"
)

var _ = pubsub.NewSubscription(events.OrderCreated, "send-confirmation-email",
    pubsub.SubscriptionConfig[*events.OrderCreatedEvent]{
        Handler: sendConfirmationEmail,
    },
)

func sendConfirmationEmail(ctx context.Context, event *events.OrderCreatedEvent) error {
    // Send email...
    return nil
}

主题引用

在将主题访问权限传递给库代码的同时，保留静态分析：

// Create a reference with publish permission
ref := pubsub.TopicRef[pubsub.Publisher[*OrderCreatedEvent]](OrderCreated)

// Use the reference in library code
func publishEvent(ref pubsub.Publisher[*OrderCreatedEvent], event *OrderCreatedEvent) error {
    _, err := ref.Publish(ctx, event)
    return err
}

投递保证

• pubsub.AtLeastOnce（默认）：可能会重复投递 → 处理程序必须具备幂等性。
• pubsub.ExactlyOnce：保证更严格，但吞吐量受限（AWS 每个主题 300 msg/s，GCP 每个区域 3000+ msg/s）。发布端不会进行去重。

指南

• 主题和订阅必须声明为包级变量。
• 订阅处理程序必须具备幂等性（默认采用至少一次投递）。
• 订阅处理程序会接收 context.Context 和事件指针；返回 error 时，会根据主题的重试策略进行重试。
• 不要在 Publish 调用方中执行耗时的同步工作——Publish 会在消息入队后立即返回。