@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/internal/core/database/read_replica.go

@@ -0,0 +1,520 @@
+package database
+
+import (
+	"context"
+	"fmt"
+	"sync"
+	"time"
+
+	"go.uber.org/zap"
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+	"gorm.io/gorm/schema"
+
+	"{{module}}/internal/core/config"
+)
+
+// ═══════════════════════════════════════════════════════════════
+// 配置
+// ═══════════════════════════════════════════════════════════════
+
+const (
+	defaultReplicaPoolMax       = 10
+	defaultReplicaPoolMin       = 2
+	defaultPoolAcquireTimeoutMs = 10000
+	defaultPoolIdleTimeoutMs    = 60000
+	defaultPostgresPort         = 5432
+	defaultHealthCheckInterval  = 30 * time.Second
+)
+
+// ReplicaConfig 副本数据库连接配置
+type ReplicaConfig struct {
+	// 数据库主机
+	Host string
+	// 数据库端口
+	Port int
+	// 数据库用户名
+	Username string
+	// 数据库密码
+	Password string
+	// 数据库名称
+	Database string
+}
+
+// ConnectionPoolConfig 连接池配置
+type ConnectionPoolConfig struct {
+	// 最大连接数
+	Max int
+	// 最小空闲连接数
+	Min int
+	// 连接获取超时（毫秒）
+	AcquireTimeoutMs int
+	// 空闲超时（毫秒）
+	IdleTimeoutMs int
+}
+
+// ConnectionHealthStatus 连接健康状态
+type ConnectionHealthStatus struct {
+	Primary ConnectionStatus
+	Replica *ConnectionStatus
+}
+
+// ConnectionStatus 单个连接的状态
+type ConnectionStatus struct {
+	Connected bool
+	Host      string
+	Port      int
+}
+
+// ReadReplicaConfig 读写分离服务配置（通过环境变量或 Config 注入）
+type ReadReplicaConfig struct {
+	// 副本数据库主机（为空则不启用副本）
+	ReplicaHost string
+	// 副本数据库端口
+	ReplicaPort int
+	// 副本数据库用户名（为空时复用主库）
+	ReplicaUsername string
+	// 副本数据库密码（为空时复用主库）
+	ReplicaPassword string
+	// 副本数据库名称（为空时复用主库）
+	ReplicaName string
+	// 连接池最大连接数
+	PoolMax int
+	// 连接池最小空闲连接数
+	PoolMin int
+	// 健康检查间隔
+	HealthCheckInterval time.Duration
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 读写分离服务
+// ═══════════════════════════════════════════════════════════════
+
+// ReadReplicaService 读写分离数据库服务
+//
+// 管理主库（写）和副本库（读）的数据库连接，实现读写分离模式。
+// 该服务通过将读查询路由到副本实例，写操作路由到主实例，
+// 实现数据库读取的水平扩展。
+//
+// 功能特性：
+//   - 主库和副本库的自动连接池管理
+//   - 副本库不可用时自动回退到主库
+//   - 双连接健康监控
+//   - 定期健康检查和自动故障转移
+type ReadReplicaService struct {
+	logger          *zap.Logger
+	dbConfig        *config.DatabaseConfig
+	replicaConfig   *ReadReplicaConfig
+	primaryDB       *gorm.DB
+	replicaDB       *gorm.DB
+	replicaEnabled  bool
+	mu              sync.RWMutex
+	healthCheckDone chan struct{}
+}
+
+// NewReadReplicaService 创建读写分离服务
+func NewReadReplicaService(
+	logger *zap.Logger,
+	dbConfig *config.DatabaseConfig,
+	replicaCfg *ReadReplicaConfig,
+) *ReadReplicaService {
+	return &ReadReplicaService{
+		logger:          logger.Named("ReadReplica"),
+		dbConfig:        dbConfig,
+		replicaConfig:   replicaCfg,
+		healthCheckDone: make(chan struct{}),
+	}
+}
+
+// Initialize 初始化主库和副本库连接
+func (s *ReadReplicaService) Initialize() error {
+	if err := s.initializePrimaryConnection(); err != nil {
+		return fmt.Errorf("initialize primary connection: %w", err)
+	}
+
+	s.initializeReplicaConnection()
+
+	// 启动定期健康检查
+	interval := defaultHealthCheckInterval
+	if s.replicaConfig != nil && s.replicaConfig.HealthCheckInterval > 0 {
+		interval = s.replicaConfig.HealthCheckInterval
+	}
+	go s.healthCheckLoop(interval)
+
+	return nil
+}
+
+// Close 关闭所有数据库连接
+func (s *ReadReplicaService) Close() error {
+	close(s.healthCheckDone)
+
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	var errs []error
+
+	if s.primaryDB != nil {
+		sqlDB, err := s.primaryDB.DB()
+		if err == nil {
+			if closeErr := sqlDB.Close(); closeErr != nil {
+				s.logger.Error("error closing primary connection", zap.Error(closeErr))
+				errs = append(errs, closeErr)
+			}
+		}
+		s.primaryDB = nil
+	}
+
+	if s.replicaDB != nil {
+		sqlDB, err := s.replicaDB.DB()
+		if err == nil {
+			if closeErr := sqlDB.Close(); closeErr != nil {
+				s.logger.Error("error closing replica connection", zap.Error(closeErr))
+				errs = append(errs, closeErr)
+			}
+		}
+		s.replicaDB = nil
+	}
+
+	s.replicaEnabled = false
+	s.logger.Info("all database connections closed")
+
+	if len(errs) > 0 {
+		return fmt.Errorf("errors closing connections: %v", errs)
+	}
+	return nil
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 公共 API
+// ═══════════════════════════════════════════════════════════════
+
+// GetWriteConnection 获取写（主库）数据库连接
+//
+// 用于所有写操作（INSERT、UPDATE、DELETE）以及需要强一致性的事务。
+func (s *ReadReplicaService) GetWriteConnection() (*gorm.DB, error) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	if s.primaryDB == nil {
+		return nil, fmt.Errorf("primary database connection is not initialized")
+	}
+	return s.primaryDB, nil
+}
+
+// GetReadConnection 获取读（副本库）数据库连接
+//
+// 用于读操作（SELECT 查询）。
+// 如果未配置副本库或副本库连接不可用，则回退到主库连接。
+func (s *ReadReplicaService) GetReadConnection() (*gorm.DB, error) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	// 如果副本库可用且健康，返回副本库连接
+	if s.replicaEnabled && s.replicaDB != nil {
+		return s.replicaDB, nil
+	}
+
+	// 回退到主库连接
+	if s.primaryDB != nil {
+		s.logger.Debug("replica unavailable, falling back to primary connection for read")
+		return s.primaryDB, nil
+	}
+
+	return nil, fmt.Errorf("no database connection available")
+}
+
+// IsReplicaEnabled 检查副本库连接是否已启用且处于活动状态
+func (s *ReadReplicaService) IsReplicaEnabled() bool {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	return s.replicaEnabled && s.replicaDB != nil
+}
+
+// GetHealthStatus 获取所有数据库连接的健康状态
+func (s *ReadReplicaService) GetHealthStatus(ctx context.Context) ConnectionHealthStatus {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	status := ConnectionHealthStatus{
+		Primary: ConnectionStatus{
+			Connected: s.checkConnectionHealth(ctx, s.primaryDB),
+			Host:      s.dbConfig.Host,
+			Port:      s.dbConfig.Port,
+		},
+	}
+
+	if s.replicaEnabled && s.replicaConfig != nil {
+		replicaStatus := ConnectionStatus{
+			Connected: s.checkConnectionHealth(ctx, s.replicaDB),
+			Host:      s.replicaConfig.ReplicaHost,
+			Port:      s.replicaConfig.ReplicaPort,
+		}
+		status.Replica = &replicaStatus
+	}
+
+	return status
+}
+
+// Reconnect 手动重新连接数据库
+func (s *ReadReplicaService) Reconnect() error {
+	s.logger.Info("reconnecting to databases...")
+
+	s.mu.Lock()
+	// 关闭现有连接
+	if s.primaryDB != nil {
+		if sqlDB, err := s.primaryDB.DB(); err == nil {
+			_ = sqlDB.Close()
+		}
+		s.primaryDB = nil
+	}
+	if s.replicaDB != nil {
+		if sqlDB, err := s.replicaDB.DB(); err == nil {
+			_ = sqlDB.Close()
+		}
+		s.replicaDB = nil
+	}
+	s.replicaEnabled = false
+	s.mu.Unlock()
+
+	// 重新初始化
+	if err := s.initializePrimaryConnection(); err != nil {
+		return fmt.Errorf("reconnect primary: %w", err)
+	}
+	s.initializeReplicaConnection()
+
+	s.logger.Info("database reconnection complete")
+	return nil
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 内部方法 — 连接管理
+// ═══════════════════════════════════════════════════════════════
+
+func (s *ReadReplicaService) initializePrimaryConnection() error {
+	poolCfg := s.getPoolConfig()
+
+	dsn := fmt.Sprintf(
+		"host=%s port=%d user=%s password=%s dbname=%s sslmode=%s TimeZone=Asia/Shanghai",
+		s.dbConfig.Host, s.dbConfig.Port, s.dbConfig.Username,
+		s.dbConfig.Password, s.dbConfig.Name, sslMode(s.dbConfig.SSL),
+	)
+
+	db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{
+		Logger:                                   newGORMLogger(s.logger, s.dbConfig.Logging),
+		NamingStrategy:                           schema.NamingStrategy{SingularTable: true},
+		DisableForeignKeyConstraintWhenMigrating: true,
+	})
+	if err != nil {
+		s.logger.Error("failed to connect to primary database", zap.Error(err))
+		return err
+	}
+
+	sqlDB, err := db.DB()
+	if err != nil {
+		return fmt.Errorf("get sql.DB: %w", err)
+	}
+
+	sqlDB.SetMaxOpenConns(poolCfg.Max)
+	sqlDB.SetMaxIdleConns(poolCfg.Min)
+	if poolCfg.IdleTimeoutMs > 0 {
+		sqlDB.SetConnMaxIdleTime(time.Duration(poolCfg.IdleTimeoutMs) * time.Millisecond)
+	}
+
+	s.mu.Lock()
+	s.primaryDB = db
+	s.mu.Unlock()
+
+	s.logger.Info("primary database connection established",
+		zap.String("host", s.dbConfig.Host),
+		zap.Int("port", s.dbConfig.Port),
+	)
+	return nil
+}
+
+func (s *ReadReplicaService) initializeReplicaConnection() {
+	replCfg := s.getReplicaConfig()
+	if replCfg == nil {
+		s.logger.Info("replica database not configured, using primary for all queries")
+		return
+	}
+
+	poolCfg := s.getPoolConfig()
+
+	dsn := fmt.Sprintf(
+		"host=%s port=%d user=%s password=%s dbname=%s sslmode=%s TimeZone=Asia/Shanghai",
+		replCfg.Host, replCfg.Port, replCfg.Username,
+		replCfg.Password, replCfg.Database, sslMode(s.dbConfig.SSL),
+	)
+
+	db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{
+		Logger:                                   newGORMLogger(s.logger, s.dbConfig.Logging),
+		NamingStrategy:                           schema.NamingStrategy{SingularTable: true},
+		DisableForeignKeyConstraintWhenMigrating: true,
+	})
+	if err != nil {
+		s.logger.Warn("failed to connect to replica database, falling back to primary",
+			zap.Error(err))
+		return
+	}
+
+	sqlDB, err := db.DB()
+	if err != nil {
+		s.logger.Warn("failed to get sql.DB from replica", zap.Error(err))
+		return
+	}
+
+	sqlDB.SetMaxOpenConns(poolCfg.Max)
+	sqlDB.SetMaxIdleConns(poolCfg.Min)
+	if poolCfg.IdleTimeoutMs > 0 {
+		sqlDB.SetConnMaxIdleTime(time.Duration(poolCfg.IdleTimeoutMs) * time.Millisecond)
+	}
+
+	s.mu.Lock()
+	s.replicaDB = db
+	s.replicaEnabled = true
+	s.mu.Unlock()
+
+	s.logger.Info("replica database connection established",
+		zap.String("host", replCfg.Host),
+		zap.Int("port", replCfg.Port),
+	)
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 内部方法 — 配置
+// ═══════════════════════════════════════════════════════════════
+
+func (s *ReadReplicaService) getReplicaConfig() *ReplicaConfig {
+	if s.replicaConfig == nil || s.replicaConfig.ReplicaHost == "" {
+		return nil
+	}
+
+	port := s.replicaConfig.ReplicaPort
+	if port == 0 {
+		port = defaultPostgresPort
+	}
+
+	username := s.replicaConfig.ReplicaUsername
+	if username == "" {
+		username = s.dbConfig.Username
+	}
+
+	password := s.replicaConfig.ReplicaPassword
+	if password == "" {
+		password = s.dbConfig.Password
+	}
+
+	database := s.replicaConfig.ReplicaName
+	if database == "" {
+		database = s.dbConfig.Name
+	}
+
+	return &ReplicaConfig{
+		Host:     s.replicaConfig.ReplicaHost,
+		Port:     port,
+		Username: username,
+		Password: password,
+		Database: database,
+	}
+}
+
+func (s *ReadReplicaService) getPoolConfig() ConnectionPoolConfig {
+	cfg := ConnectionPoolConfig{
+		Max:              defaultReplicaPoolMax,
+		Min:              defaultReplicaPoolMin,
+		AcquireTimeoutMs: defaultPoolAcquireTimeoutMs,
+		IdleTimeoutMs:    defaultPoolIdleTimeoutMs,
+	}
+
+	if s.replicaConfig != nil {
+		if s.replicaConfig.PoolMax > 0 {
+			cfg.Max = s.replicaConfig.PoolMax
+		}
+		if s.replicaConfig.PoolMin > 0 {
+			cfg.Min = s.replicaConfig.PoolMin
+		}
+	}
+
+	// 也使用主库配置中的连接池设置
+	if s.dbConfig.MaxOpenConns > 0 {
+		cfg.Max = s.dbConfig.MaxOpenConns
+	}
+	if s.dbConfig.MaxIdleConns > 0 {
+		cfg.Min = s.dbConfig.MaxIdleConns
+	}
+
+	return cfg
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 内部方法 — 健康检查
+// ═══════════════════════════════════════════════════════════════
+
+func (s *ReadReplicaService) checkConnectionHealth(ctx context.Context, db *gorm.DB) bool {
+	if db == nil {
+		return false
+	}
+
+	sqlDB, err := db.DB()
+	if err != nil {
+		return false
+	}
+
+	if err := sqlDB.PingContext(ctx); err != nil {
+		s.logger.Warn("database health check failed", zap.Error(err))
+		return false
+	}
+
+	return true
+}
+
+// healthCheckLoop 定期检查副本健康状态并自动故障转移
+func (s *ReadReplicaService) healthCheckLoop(interval time.Duration) {
+	ticker := time.NewTicker(interval)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-s.healthCheckDone:
+			return
+		case <-ticker.C:
+			s.performHealthCheck()
+		}
+	}
+}
+
+func (s *ReadReplicaService) performHealthCheck() {
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	s.mu.RLock()
+	replicaDB := s.replicaDB
+	replicaEnabled := s.replicaEnabled
+	s.mu.RUnlock()
+
+	if replicaDB == nil {
+		// 如果有副本配置但当前未连接，尝试重新连接
+		if s.replicaConfig != nil && s.replicaConfig.ReplicaHost != "" && !replicaEnabled {
+			s.logger.Debug("attempting to reconnect to replica database")
+			s.initializeReplicaConnection()
+		}
+		return
+	}
+
+	// 检查副本健康
+	if !s.checkConnectionHealth(ctx, replicaDB) {
+		s.mu.Lock()
+		if s.replicaEnabled {
+			s.replicaEnabled = false
+			s.logger.Warn("replica database health check failed, disabling replica")
+		}
+		s.mu.Unlock()
+	} else {
+		s.mu.Lock()
+		if !s.replicaEnabled {
+			s.replicaEnabled = true
+			s.logger.Info("replica database recovered, re-enabling replica")
+		}
+		s.mu.Unlock()
+	}
+}

package/dist/resources/templates/go-backend/internal/core/database/transaction.go

@@ -0,0 +1,170 @@
+package database
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"sync"
+	"sync/atomic"
+
+	"gorm.io/gorm"
+)
+
+type ctxTxKey struct{}
+
+// TransactionCompletionOutcome 表示最外层数据库事务的最终结果。
+type TransactionCompletionOutcome string
+
+const (
+	TransactionCompletionCommitted  TransactionCompletionOutcome = "committed"
+	TransactionCompletionRolledBack TransactionCompletionOutcome = "rolled_back"
+)
+
+// TransactionCompletionCallback 在事务真正提交或回滚后执行，不得继续使用已结束的事务连接。
+type TransactionCompletionCallback func(context.Context, TransactionCompletionOutcome) error
+
+type transactionCompletionRegistration struct {
+	active   atomic.Bool
+	callback TransactionCompletionCallback
+}
+
+type transactionContext struct {
+	db           *gorm.DB
+	active       atomic.Bool
+	completionMu sync.Mutex
+	completions  []*transactionCompletionRegistration
+}
+
+// TransactionManager 事务管理器，提供上下文传递的事务支持
+// 对标 Kratos Transaction / Spring PlatformTransactionManager
+type TransactionManager struct {
+	db *gorm.DB
+}
+
+// NewTransactionManager 创建事务管理器
+func NewTransactionManager(db *gorm.DB) *TransactionManager {
+	return &TransactionManager{db: db}
+}
+
+// WithTransaction REQUIRED 传播 — 加入已有事务或创建新事务
+// ctx 中已有事务则直接执行（加入），否则创建新事务
+func (tm *TransactionManager) WithTransaction(ctx context.Context, fn func(ctx context.Context) error) error {
+	// REQUIRED：已有事务则加入
+	if txContext, ok := transactionFromContext(ctx); ok && txContext.active.Load() {
+		return fn(ctx)
+	}
+
+	return tm.executeTransaction(ctx, fn)
+}
+
+// RequireTransaction 要求调用链已进入事务边界
+// 跨模块原子写入必须显式拒绝非事务上下文，避免各模块独立提交形成部分成功。
+func RequireTransaction(ctx context.Context) error {
+	txContext, ok := transactionFromContext(ctx)
+	if !ok || !txContext.active.Load() {
+		return errors.New("database transaction context is required")
+	}
+	return nil
+}
+
+// WithNewTransaction REQUIRES_NEW 传播 — 始终创建独立事务
+// 忽略 ctx 中已有事务，用途：审计日志、幂等键记录等必须独立持久化的场景
+func (tm *TransactionManager) WithNewTransaction(ctx context.Context, fn func(ctx context.Context) error, opts ...*sql.TxOptions) error {
+	return tm.executeTransaction(ctx, fn, opts...)
+}
+
+// RegisterTransactionCompletion 将外部副作用的提交确认或回滚补偿绑定到当前最外层事务。
+// 返回 registered=false 表示调用链当前不在活动事务内，调用方必须自行处理生命周期。
+func RegisterTransactionCompletion(
+	ctx context.Context,
+	callback TransactionCompletionCallback,
+) (cancel func(), registered bool) {
+	if callback == nil {
+		return func() {}, false
+	}
+	txContext, ok := transactionFromContext(ctx)
+	if !ok || !txContext.active.Load() {
+		return func() {}, false
+	}
+
+	registration := &transactionCompletionRegistration{callback: callback}
+	registration.active.Store(true)
+	txContext.completionMu.Lock()
+	defer txContext.completionMu.Unlock()
+	if !txContext.active.Load() {
+		registration.active.Store(false)
+		return func() {}, false
+	}
+	txContext.completions = append(txContext.completions, registration)
+	return func() {
+		registration.active.Store(false)
+	}, true
+}
+
+// GetDB 从 context 提取事务 DB，若不在事务中则返回普通 DB
+// Repository 中获取 DB 的唯一方式，禁止直接使用 r.db.WithContext(ctx)
+func GetDB(ctx context.Context, db *gorm.DB) *gorm.DB {
+	if txContext, ok := transactionFromContext(ctx); ok {
+		// 已结束的事务仍交给驱动返回明确错误，禁止静默降级为事务外写入。
+		return txContext.db
+	}
+	return db.WithContext(ctx)
+}
+
+func (tm *TransactionManager) executeTransaction(
+	ctx context.Context,
+	fn func(context.Context) error,
+	opts ...*sql.TxOptions,
+) (returnErr error) {
+	var txContext *transactionContext
+	panicked := true
+	defer func() {
+		if txContext == nil {
+			return
+		}
+		txContext.active.Store(false)
+		outcome := TransactionCompletionRolledBack
+		if !panicked && returnErr == nil {
+			outcome = TransactionCompletionCommitted
+		}
+		completionErr := txContext.complete(transactionCompletionContext(ctx), outcome)
+		if !panicked && completionErr != nil {
+			returnErr = errors.Join(returnErr, completionErr)
+		}
+	}()
+
+	returnErr = tm.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		txContext = &transactionContext{db: tx}
+		txContext.active.Store(true)
+		return fn(context.WithValue(ctx, ctxTxKey{}, txContext))
+	}, opts...)
+	panicked = false
+	return returnErr
+}
+
+func (c *transactionContext) complete(ctx context.Context, outcome TransactionCompletionOutcome) error {
+	c.completionMu.Lock()
+	registrations := c.completions
+	c.completions = nil
+	c.completionMu.Unlock()
+
+	var completionErr error
+	// 补偿按注册逆序执行，与外部副作用的创建顺序形成栈式回滚。
+	for index := len(registrations) - 1; index >= 0; index-- {
+		registration := registrations[index]
+		if !registration.active.CompareAndSwap(true, false) {
+			continue
+		}
+		completionErr = errors.Join(completionErr, registration.callback(ctx, outcome))
+	}
+	return completionErr
+}
+
+func transactionCompletionContext(ctx context.Context) context.Context {
+	return context.WithValue(context.WithoutCancel(ctx), ctxTxKey{}, (*transactionContext)(nil))
+}
+
+func transactionFromContext(ctx context.Context) (*transactionContext, bool) {
+	txContext, ok := ctx.Value(ctxTxKey{}).(*transactionContext)
+	return txContext, ok && txContext != nil && txContext.db != nil
+}