@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/internal/core/eventbus/eventbus.go

@@ -0,0 +1,667 @@
+package eventbus
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"sort"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"github.com/google/uuid"
+	"go.uber.org/zap"
+)
+
+// ═══════════════════════════════════════════════════════════════
+// 事件定义
+// ═══════════════════════════════════════════════════════════════
+
+// EventMetadata 事件元数据
+type EventMetadata struct {
+	// 触发事件的用户 ID
+	UserID int64 `json:"user_id,omitempty"`
+	// 请求追踪 ID
+	TraceID string `json:"trace_id,omitempty"`
+	// 租户/产品 ID
+	TenantID string `json:"tenant_id,omitempty"`
+	// 自定义元数据（对应 CloudEvents extensions / Stripe Events request envelope）。
+	// 由发布方填入非强类型上下文（IP / UA / DeviceID / RequestID / ProductCode 等），
+	// any 是必需的 —— extension 字段集合随业务演进扩展，不应固化成具体类型。
+	Extra map[string]any `json:"extra,omitempty"`
+}
+
+// 审计追踪相关的 Extra 字段键名约定
+const (
+	ExtraKeyClientIP    = "client_ip"
+	ExtraKeyUserAgent   = "user_agent"
+	ExtraKeyRequestID   = "request_id"
+	ExtraKeyProductCode = "product_code"
+	// ExtraKeyDeviceID 设备指纹哈希 — 反欺诈信号（设备聚类、同设备多账号检测）。
+	// 与 Stripe Events `request.client_user_agent` 同属请求信封元数据，跨聚合根
+	// 异步传递给反欺诈链路（email register → UserCreated → referral redeem）。
+	ExtraKeyDeviceID = "device_id"
+)
+
+// contextKey 用于在 context.Context 中存储 EventMetadata
+type contextKey struct{}
+
+// ContextWithMetadata 将 EventMetadata 存入 context（供中间件调用）
+func ContextWithMetadata(ctx context.Context, meta *EventMetadata) context.Context {
+	return context.WithValue(ctx, contextKey{}, meta)
+}
+
+// MetadataFromContext 从 context 中提取 EventMetadata（供 Service 层 Publish 时使用）
+// 返回 nil 表示当前请求无 HTTP 上下文（如 Worker/Cron 场景）
+func MetadataFromContext(ctx context.Context) *EventMetadata {
+	if meta, ok := ctx.Value(contextKey{}).(*EventMetadata); ok {
+		return meta
+	}
+	return nil
+}
+
+// NewDomainEventFromContext 创建领域事件并自动从 context 提取 EventMetadata
+// 用于 Service 层替代 NewDomainEvent(..., nil)，自动携带 HTTP 上下文
+func NewDomainEventFromContext(ctx context.Context, eventName, aggregateID string) DomainEvent {
+	return NewDomainEvent(eventName, aggregateID, MetadataFromContext(ctx))
+}
+
+// WithClientContext 向 EventMetadata 注入客户端上下文信息
+// 供中间件在请求处理链中调用，确保事件携带 HTTP 上下文
+func (m *EventMetadata) WithClientContext(ip, userAgent, deviceID, requestID, productCode string) {
+	if m.Extra == nil {
+		m.Extra = make(map[string]any)
+	}
+	if ip != "" {
+		m.Extra[ExtraKeyClientIP] = ip
+	}
+	if userAgent != "" {
+		m.Extra[ExtraKeyUserAgent] = userAgent
+	}
+	if deviceID != "" {
+		m.Extra[ExtraKeyDeviceID] = deviceID
+	}
+	if requestID != "" {
+		m.Extra[ExtraKeyRequestID] = requestID
+	}
+	if productCode != "" {
+		m.Extra[ExtraKeyProductCode] = productCode
+	}
+}
+
+// MetadataWithProductCode 将事件信封中的产品归属恢复到统一元数据扩展字段。
+func MetadataWithProductCode(metadata *EventMetadata, productCode string) *EventMetadata {
+	productCode = strings.TrimSpace(productCode)
+	if productCode == "" {
+		return metadata
+	}
+	if metadata == nil {
+		metadata = &EventMetadata{}
+	}
+	metadata.WithClientContext("", "", "", "", productCode)
+	return metadata
+}
+
+// DomainEvent 领域事件
+//
+// 结构遵循 CloudEvents 信封模式（AWS CloudTrail / Stripe Events 同款）：
+// - 事件标识和元数据在信封层（根字段）
+// - 业务数据在 Payload（typed struct）
+// - 审计变更快照在 AuditChanges / AuditMeta（信封层，与 Payload 分离）
+//
+// 这样 Payload 可以使用强类型 struct，审计数据不污染业务载荷。
+type DomainEvent struct {
+	// 事件名称（格式: resource.action，如 order.created）
+	EventName string `json:"event_name"`
+	// 事件唯一标识
+	EventID string `json:"event_id"`
+	// 事件发生时间
+	OccurredAt time.Time `json:"occurred_at"`
+	// 聚合根 ID
+	AggregateID string `json:"aggregate_id"`
+	// 事件版本号
+	Version int `json:"version"`
+	// 事件元数据（身份、trace、客户端上下文）
+	Metadata *EventMetadata `json:"metadata,omitempty"`
+	// 事件载荷（业务数据，使用 typed struct）
+	Payload any `json:"payload,omitempty"`
+	// 审计变更快照（可选，仅写操作需要），信封层字段，不在 Payload 内
+	AuditChanges *AuditChangesPayload `json:"audit_changes,omitempty"`
+	// 审计扩展元数据（可选），如操作原因、关联资源等
+	AuditMeta *AuditMetadataPayload `json:"audit_meta,omitempty"`
+}
+
+// AuditChangesPayload 审计变更快照（before/after），嵌入事件信封
+type AuditChangesPayload struct {
+	// Before/After 为任意可 JSON 序列化的业务快照，形状由调用方决定，与
+	// AWS CloudTrail requestParameters / responseElements 同款模式 —— 审计表
+	// 对不同聚合根的变更结构各不相同，any 是必需的开放 schema。
+	Before any `json:"before,omitempty"`
+	After  any `json:"after,omitempty"`
+}
+
+// AuditMetadataPayload 审计扩展元数据，嵌入事件信封
+type AuditMetadataPayload struct {
+	Reason              string                     `json:"reason,omitempty"`
+	ErrorCode           string                     `json:"error_code,omitempty"`
+	GatewayEventID      string                     `json:"gateway_event_id,omitempty"`
+	RelatedResourceID   string                     `json:"related_resource_id,omitempty"`
+	RelatedResourceType string                     `json:"related_resource_type,omitempty"`
+	Actor               *AuditActorSnapshotPayload `json:"actor,omitempty"`
+	Extra               map[string]any             `json:"extra,omitempty"`
+}
+
+// AuditActorSnapshotPayload 固化事件受理时已认证主体的结构化审计证据。
+type AuditActorSnapshotPayload struct {
+	ActorType          string `json:"actor_type"`
+	ActorID            int64  `json:"actor_id"`
+	AuthSubjectType    string `json:"auth_subject_type"`
+	IAMPrincipalID     int64  `json:"iam_principal_id"`
+	CredentialPublicID string `json:"credential_public_id,omitempty"`
+	TokenFingerprint   string `json:"token_fingerprint,omitempty"`
+	AuthMechanism      string `json:"auth_mechanism"`
+}
+
+// NewDomainEvent 创建领域事件
+//
+// EventID 使用完整 UUIDv4（对齐 CloudEvents id 字段与 Stripe Events evt_ 规范），
+// 保证全局唯一性 —— 截断 8 位在高并发下存在冲突概率，且无法作为稳定去重键。
+func NewDomainEvent(eventName, aggregateID string, metadata *EventMetadata) DomainEvent {
+	return DomainEvent{
+		EventName:   eventName,
+		EventID:     uuid.New().String(),
+		OccurredAt:  time.Now(),
+		AggregateID: aggregateID,
+		Version:     1,
+		Metadata:    metadata,
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 事件处理器类型
+// ═══════════════════════════════════════════════════════════════
+
+// Handler 事件处理函数
+type Handler func(ctx context.Context, event DomainEvent) error
+
+// Filter 事件过滤谓词
+type Filter func(event DomainEvent) bool
+
+// ErrorHandler 自定义错误处理
+type ErrorHandler func(err error, event DomainEvent)
+
+// ═══════════════════════════════════════════════════════════════
+// 订阅配置
+// ═══════════════════════════════════════════════════════════════
+
+// SubscribeOptions 订阅配置选项
+type SubscribeOptions struct {
+	// 处理器优先级（数值越高越先执行）
+	Priority int
+	// 事件过滤谓词
+	Filter Filter
+	// 是否捕获错误（默认 true）
+	CatchErrors *bool
+	// 自定义错误处理
+	OnError ErrorHandler
+	// 最大执行次数，达到后自动取消订阅
+	MaxExecutions *int
+}
+
+func defaultCatchErrors() bool { return true }
+
+// Subscription 订阅句柄
+type Subscription struct {
+	// 订阅唯一标识
+	ID string
+	// 监听的事件名称
+	EventName string
+	bus       *EventBus
+}
+
+// Unsubscribe 取消订阅
+func (s *Subscription) Unsubscribe() bool {
+	return s.bus.Unsubscribe(s.ID)
+}
+
+// IsActive 检查订阅是否仍处于活跃状态
+func (s *Subscription) IsActive() bool {
+	s.bus.mu.RLock()
+	defer s.bus.mu.RUnlock()
+	meta, ok := s.bus.subscriptions[s.ID]
+	return ok && meta.active
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 内部订阅元数据
+// ═══════════════════════════════════════════════════════════════
+
+type subscriptionMeta struct {
+	id             string
+	eventName      string
+	handler        Handler
+	priority       int
+	catchErrors    bool
+	filter         Filter
+	onError        ErrorHandler
+	maxExecutions  *int
+	executionCount int64
+	createdAt      time.Time
+	active         bool
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 事件总线
+// ═══════════════════════════════════════════════════════════════
+
+// EventBus 进程内事件总线
+type EventBus struct {
+	logger *zap.Logger
+
+	mu            sync.RWMutex
+	subscriptions map[string]*subscriptionMeta            // id -> meta
+	handlers      map[string]map[string]*subscriptionMeta // eventName -> id -> meta
+	closed        atomic.Bool
+	wg            sync.WaitGroup
+}
+
+// New 创建事件总线
+func New(logger *zap.Logger) *EventBus {
+	return &EventBus{
+		logger:        logger.Named("EventBus"),
+		subscriptions: make(map[string]*subscriptionMeta),
+		handlers:      make(map[string]map[string]*subscriptionMeta),
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 发布
+// ═══════════════════════════════════════════════════════════════
+
+// Publish 同步发布事件，按优先级顺序执行所有处理器
+func (b *EventBus) Publish(ctx context.Context, event DomainEvent) error {
+	if b.closed.Load() {
+		return errors.New("event bus is closed")
+	}
+
+	handlers := b.matchHandlers(event.EventName)
+	if len(handlers) == 0 {
+		b.logger.Debug("no handlers matched for event",
+			zap.String("eventName", event.EventName),
+		)
+		return nil
+	}
+
+	// 按优先级排序（高优先级在前）
+	sort.Slice(handlers, func(i, j int) bool {
+		return handlers[i].priority > handlers[j].priority
+	})
+
+	handlerIDs := make([]string, len(handlers))
+	for i, h := range handlers {
+		handlerIDs[i] = h.id
+	}
+	b.logger.Debug("publishing event to handlers",
+		zap.String("eventName", event.EventName),
+		zap.Int("handlerCount", len(handlers)),
+		zap.Strings("handlers", handlerIDs),
+	)
+
+	for _, meta := range handlers {
+		if err := b.executeHandler(ctx, meta, event); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// PublishAsync 异步发布事件，每个处理器在独立 goroutine 中执行
+func (b *EventBus) PublishAsync(ctx context.Context, event DomainEvent) {
+	if b.closed.Load() {
+		return
+	}
+
+	// 使用 context.WithoutCancel 创建不受 HTTP 请求生命周期影响的独立 context
+	// 保留 trace ID 等值，但不会因请求结束而取消
+	asyncCtx := context.WithoutCancel(ctx)
+
+	handlers := b.matchHandlers(event.EventName)
+	for _, meta := range handlers {
+		b.wg.Add(1)
+		go func(m *subscriptionMeta) {
+			defer b.wg.Done()
+			if err := b.executeHandler(asyncCtx, m, event); err != nil {
+				b.logger.Error("异步 handler 执行失败",
+					zap.String("event", event.EventName),
+					zap.String("handler", m.id),
+					zap.Error(err),
+				)
+			}
+		}(meta)
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 订阅
+// ═══════════════════════════════════════════════════════════════
+
+// Subscribe 订阅事件（支持通配符 user.*）
+func (b *EventBus) Subscribe(eventName string, handler Handler, opts ...SubscribeOptions) *Subscription {
+	var opt SubscribeOptions
+	if len(opts) > 0 {
+		opt = opts[0]
+	}
+
+	catchErrors := defaultCatchErrors()
+	if opt.CatchErrors != nil {
+		catchErrors = *opt.CatchErrors
+	}
+
+	id := fmt.Sprintf("sub_%d_%s", time.Now().UnixNano(), uuid.New().String()[:8])
+
+	meta := &subscriptionMeta{
+		id:            id,
+		eventName:     eventName,
+		handler:       handler,
+		priority:      opt.Priority,
+		catchErrors:   catchErrors,
+		filter:        opt.Filter,
+		onError:       opt.OnError,
+		maxExecutions: opt.MaxExecutions,
+		createdAt:     time.Now(),
+		active:        true,
+	}
+
+	b.mu.Lock()
+	b.subscriptions[id] = meta
+	if b.handlers[eventName] == nil {
+		b.handlers[eventName] = make(map[string]*subscriptionMeta)
+	}
+	b.handlers[eventName][id] = meta
+	b.mu.Unlock()
+
+	return &Subscription{ID: id, EventName: eventName, bus: b}
+}
+
+// SubscribeOnce 订阅事件，首次执行后自动取消
+func (b *EventBus) SubscribeOnce(eventName string, handler Handler, opts ...SubscribeOptions) *Subscription {
+	var opt SubscribeOptions
+	if len(opts) > 0 {
+		opt = opts[0]
+	}
+	maxExec := 1
+	opt.MaxExecutions = &maxExec
+	return b.Subscribe(eventName, handler, opt)
+}
+
+// Unsubscribe 根据订阅 ID 取消订阅
+func (b *EventBus) Unsubscribe(subscriptionID string) bool {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+
+	meta, ok := b.subscriptions[subscriptionID]
+	if !ok || !meta.active {
+		return false
+	}
+
+	meta.active = false
+	delete(b.subscriptions, subscriptionID)
+
+	if group, exists := b.handlers[meta.eventName]; exists {
+		delete(group, subscriptionID)
+		if len(group) == 0 {
+			delete(b.handlers, meta.eventName)
+		}
+	}
+	return true
+}
+
+// UnsubscribeAll 取消特定事件的所有订阅
+func (b *EventBus) UnsubscribeAll(eventName string) int {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+
+	group, exists := b.handlers[eventName]
+	if !exists {
+		return 0
+	}
+
+	count := len(group)
+	for id, meta := range group {
+		meta.active = false
+		delete(b.subscriptions, id)
+	}
+	delete(b.handlers, eventName)
+
+	return count
+}
+
+// WaitFor 等待事件触发（阻塞直到事件到达或超时）
+func (b *EventBus) WaitFor(ctx context.Context, eventName string, timeout time.Duration, filter ...Filter) (DomainEvent, error) {
+	ch := make(chan DomainEvent, 1)
+	errCh := make(chan error, 1)
+
+	var f Filter
+	if len(filter) > 0 {
+		f = filter[0]
+	}
+
+	sub := b.SubscribeOnce(eventName, func(_ context.Context, event DomainEvent) error {
+		ch <- event
+		return nil
+	}, SubscribeOptions{Filter: f})
+
+	var timer *time.Timer
+	if timeout > 0 {
+		timer = time.NewTimer(timeout)
+		defer timer.Stop()
+	}
+
+	select {
+	case event := <-ch:
+		return event, nil
+	case err := <-errCh:
+		sub.Unsubscribe()
+		return DomainEvent{}, err
+	case <-func() <-chan time.Time {
+		if timer != nil {
+			return timer.C
+		}
+		return nil
+	}():
+		sub.Unsubscribe()
+		return DomainEvent{}, fmt.Errorf("timeout waiting for event '%s' after %v", eventName, timeout)
+	case <-ctx.Done():
+		sub.Unsubscribe()
+		return DomainEvent{}, ctx.Err()
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 查询
+// ═══════════════════════════════════════════════════════════════
+
+// HasSubscribers 检查事件是否有活跃订阅
+func (b *EventBus) HasSubscribers(eventName string) bool {
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+
+	group, exists := b.handlers[eventName]
+	if !exists {
+		return false
+	}
+	for _, meta := range group {
+		if meta.active {
+			return true
+		}
+	}
+	return false
+}
+
+// SubscriptionCount 获取活跃订阅总数
+func (b *EventBus) SubscriptionCount() int {
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+
+	count := 0
+	for _, meta := range b.subscriptions {
+		if meta.active {
+			count++
+		}
+	}
+	return count
+}
+
+// Close 关闭事件总线，清理所有订阅
+func (b *EventBus) Close() {
+	b.closed.Store(true)
+	b.wg.Wait()
+	b.mu.Lock()
+	defer b.mu.Unlock()
+
+	for _, meta := range b.subscriptions {
+		meta.active = false
+	}
+	b.subscriptions = make(map[string]*subscriptionMeta)
+	b.handlers = make(map[string]map[string]*subscriptionMeta)
+}
+
+// Drain 等待所有异步事件处理器完成，用于优雅关闭
+func (b *EventBus) Drain() {
+	b.wg.Wait()
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 内部方法
+// ═══════════════════════════════════════════════════════════════
+
+// matchHandlers 匹配事件名称（支持通配符）的所有活跃处理器
+func (b *EventBus) matchHandlers(eventName string) []*subscriptionMeta {
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+
+	var matched []*subscriptionMeta
+
+	for pattern, group := range b.handlers {
+		if matchPattern(pattern, eventName) {
+			for _, meta := range group {
+				if meta.active {
+					matched = append(matched, meta)
+				}
+			}
+		}
+	}
+	return matched
+}
+
+// matchPattern 通配符匹配（支持 user.* 匹配 user.created）
+func matchPattern(pattern, eventName string) bool {
+	if pattern == eventName {
+		return true
+	}
+	if pattern == "**" || pattern == "*" {
+		return true
+	}
+
+	patternParts := strings.Split(pattern, ".")
+	eventParts := strings.Split(eventName, ".")
+
+	if len(patternParts) != len(eventParts) {
+		// 允许 user.* 匹配 user.created 但不匹配 user.status.changed
+		// 除非使用 ** 作为最后一段
+		if len(patternParts) > 0 && patternParts[len(patternParts)-1] == "**" {
+			patternParts = patternParts[:len(patternParts)-1]
+			if len(eventParts) < len(patternParts) {
+				return false
+			}
+			for i, p := range patternParts {
+				if p != "*" && p != eventParts[i] {
+					return false
+				}
+			}
+			return true
+		}
+		return false
+	}
+
+	for i, p := range patternParts {
+		if p == "*" {
+			continue
+		}
+		if p != eventParts[i] {
+			return false
+		}
+	}
+	return true
+}
+
+// executeHandler 执行单个处理器，包含过滤和错误处理
+func (b *EventBus) executeHandler(ctx context.Context, meta *subscriptionMeta, event DomainEvent) error {
+	// 持锁检查活跃状态，避免与 Unsubscribe 并发写产生 data race
+	b.mu.RLock()
+	active := meta.active
+	b.mu.RUnlock()
+	if !active {
+		return nil
+	}
+
+	// 应用过滤器
+	if meta.filter != nil {
+		func() {
+			defer func() {
+				if r := recover(); r != nil {
+					b.logger.Error("filter panic",
+						zap.String("subscriptionId", meta.id),
+						zap.String("panic", fmt.Sprint(r)),
+					)
+				}
+			}()
+			if !meta.filter(event) {
+				return
+			}
+		}()
+		// 重新检查过滤结果
+		if meta.filter != nil && !meta.filter(event) {
+			return nil
+		}
+	}
+
+	// 执行处理器
+	err := func() (handlerErr error) {
+		defer func() {
+			if r := recover(); r != nil {
+				handlerErr = fmt.Errorf("handler panic: %v", r)
+			}
+		}()
+		return meta.handler(ctx, event)
+	}()
+
+	atomic.AddInt64(&meta.executionCount, 1)
+
+	// 检查最大执行次数
+	if meta.maxExecutions != nil {
+		if int(atomic.LoadInt64(&meta.executionCount)) >= *meta.maxExecutions {
+			b.Unsubscribe(meta.id)
+		}
+	}
+
+	if err != nil {
+		// 自定义错误处理
+		if meta.onError != nil {
+			meta.onError(err, event)
+		}
+
+		if meta.catchErrors {
+			b.logger.Error("handler error",
+				zap.String("eventName", event.EventName),
+				zap.String("subscriptionId", meta.id),
+				zap.Error(err),
+			)
+			return nil
+		}
+		return err
+	}
+
+	return nil
+}