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/topic、GCP 3000+ msg/s/region)。発行側では重複排除を行いません。

ガイドライン

• トピックとサブスクリプションはパッケージレベルの変数として宣言する必要があります。
• サブスクリプションハンドラーは冪等でなければなりません (デフォルトでは at-least-once 配信です)。
• サブスクリプションハンドラーは context.Context とイベントポインターを受け取ります。トピックのリトライポリシーに従ってリトライするには error を返します。
• Publish の呼び出し元で重い同期処理を行わないでください — Publish はメッセージがキューに入った時点で戻ります。