feat(架构): 完善基础架构设计

2025-07-02 16:17:59 +08:00
parent 03e615a8fd
commit 5b4392894f
89 changed files with 18555 additions and 3521 deletions
--- a/internal/shared/metrics/business_metrics.go
+++ b/internal/shared/metrics/business_metrics.go
@@ -0,0 +1,263 @@
+package metrics
+
+import (
+	"context"
+	"sync"
+
+	"go.uber.org/zap"
+
+	"tyapi-server/internal/shared/interfaces"
+)
+
+// BusinessMetrics 业务指标收集器
+type BusinessMetrics struct {
+	metrics interfaces.MetricsCollector
+	logger  *zap.Logger
+	mutex   sync.RWMutex
+
+	// 业务指标缓存
+	userMetrics  map[string]int64
+	orderMetrics map[string]int64
+}
+
+// NewBusinessMetrics 创建业务指标收集器
+func NewBusinessMetrics(metrics interfaces.MetricsCollector, logger *zap.Logger) *BusinessMetrics {
+	bm := &BusinessMetrics{
+		metrics:      metrics,
+		logger:       logger,
+		userMetrics:  make(map[string]int64),
+		orderMetrics: make(map[string]int64),
+	}
+
+	// 注册业务指标
+	bm.registerBusinessMetrics()
+
+	return bm
+}
+
+// registerBusinessMetrics 注册业务指标
+func (bm *BusinessMetrics) registerBusinessMetrics() {
+	// 用户相关指标
+	bm.metrics.RegisterCounter("users_created_total", "Total number of users created", []string{"source"})
+	bm.metrics.RegisterCounter("users_login_total", "Total number of user logins", []string{"method", "status"})
+	bm.metrics.RegisterGauge("users_active_sessions", "Current number of active user sessions", nil)
+
+	// 订单相关指标
+	bm.metrics.RegisterCounter("orders_created_total", "Total number of orders created", []string{"status"})
+	bm.metrics.RegisterCounter("orders_amount_total", "Total order amount in cents", []string{"currency"})
+	bm.metrics.RegisterHistogram("orders_processing_duration_seconds", "Order processing duration", []string{"status"}, []float64{0.1, 0.5, 1, 2, 5, 10, 30})
+
+	// API相关指标
+	bm.metrics.RegisterCounter("api_errors_total", "Total number of API errors", []string{"endpoint", "error_type"})
+	bm.metrics.RegisterHistogram("api_response_size_bytes", "API response size in bytes", []string{"endpoint"}, []float64{100, 1000, 10000, 100000})
+
+	// 缓存相关指标
+	bm.metrics.RegisterCounter("cache_operations_total", "Total number of cache operations", []string{"operation", "result"})
+	bm.metrics.RegisterGauge("cache_memory_usage_bytes", "Cache memory usage in bytes", []string{"cache_type"})
+
+	// 数据库相关指标
+	bm.metrics.RegisterHistogram("database_query_duration_seconds", "Database query duration", []string{"operation", "table"}, []float64{0.001, 0.01, 0.1, 1, 10})
+	bm.metrics.RegisterCounter("database_errors_total", "Total number of database errors", []string{"operation", "error_type"})
+
+	bm.logger.Info("Business metrics registered successfully")
+}
+
+// User相关指标
+
+// RecordUserCreated 记录用户创建
+func (bm *BusinessMetrics) RecordUserCreated(source string) {
+	bm.metrics.IncrementCounter("users_created_total", map[string]string{
+		"source": source,
+	})
+
+	bm.mutex.Lock()
+	bm.userMetrics["created"]++
+	bm.mutex.Unlock()
+
+	bm.logger.Debug("Recorded user created", zap.String("source", source))
+}
+
+// RecordUserLogin 记录用户登录
+func (bm *BusinessMetrics) RecordUserLogin(method, status string) {
+	bm.metrics.IncrementCounter("users_login_total", map[string]string{
+		"method": method,
+		"status": status,
+	})
+
+	bm.logger.Debug("Recorded user login", zap.String("method", method), zap.String("status", status))
+}
+
+// UpdateActiveUserSessions 更新活跃用户会话数
+func (bm *BusinessMetrics) UpdateActiveUserSessions(count float64) {
+	bm.metrics.RecordGauge("users_active_sessions", count, nil)
+}
+
+// Order相关指标
+
+// RecordOrderCreated 记录订单创建
+func (bm *BusinessMetrics) RecordOrderCreated(status string, amount float64, currency string) {
+	bm.metrics.IncrementCounter("orders_created_total", map[string]string{
+		"status": status,
+	})
+
+	// 记录订单金额（以分为单位）
+	amountCents := int64(amount * 100)
+	bm.metrics.IncrementCounter("orders_amount_total", map[string]string{
+		"currency": currency,
+	})
+
+	bm.mutex.Lock()
+	bm.orderMetrics["created"]++
+	bm.orderMetrics["amount"] += amountCents
+	bm.mutex.Unlock()
+
+	bm.logger.Debug("Recorded order created",
+		zap.String("status", status),
+		zap.Float64("amount", amount),
+		zap.String("currency", currency))
+}
+
+// RecordOrderProcessingDuration 记录订单处理时长
+func (bm *BusinessMetrics) RecordOrderProcessingDuration(status string, duration float64) {
+	bm.metrics.RecordHistogram("orders_processing_duration_seconds", duration, map[string]string{
+		"status": status,
+	})
+}
+
+// API相关指标
+
+// RecordAPIError 记录API错误
+func (bm *BusinessMetrics) RecordAPIError(endpoint, errorType string) {
+	bm.metrics.IncrementCounter("api_errors_total", map[string]string{
+		"endpoint":   endpoint,
+		"error_type": errorType,
+	})
+
+	bm.logger.Debug("Recorded API error",
+		zap.String("endpoint", endpoint),
+		zap.String("error_type", errorType))
+}
+
+// RecordAPIResponseSize 记录API响应大小
+func (bm *BusinessMetrics) RecordAPIResponseSize(endpoint string, sizeBytes float64) {
+	bm.metrics.RecordHistogram("api_response_size_bytes", sizeBytes, map[string]string{
+		"endpoint": endpoint,
+	})
+}
+
+// Cache相关指标
+
+// RecordCacheOperation 记录缓存操作
+func (bm *BusinessMetrics) RecordCacheOperation(operation, result string) {
+	bm.metrics.IncrementCounter("cache_operations_total", map[string]string{
+		"operation": operation,
+		"result":    result,
+	})
+}
+
+// UpdateCacheMemoryUsage 更新缓存内存使用量
+func (bm *BusinessMetrics) UpdateCacheMemoryUsage(cacheType string, usageBytes float64) {
+	bm.metrics.RecordGauge("cache_memory_usage_bytes", usageBytes, map[string]string{
+		"cache_type": cacheType,
+	})
+}
+
+// Database相关指标
+
+// RecordDatabaseQuery 记录数据库查询
+func (bm *BusinessMetrics) RecordDatabaseQuery(operation, table string, duration float64) {
+	bm.metrics.RecordHistogram("database_query_duration_seconds", duration, map[string]string{
+		"operation": operation,
+		"table":     table,
+	})
+}
+
+// RecordDatabaseError 记录数据库错误
+func (bm *BusinessMetrics) RecordDatabaseError(operation, errorType string) {
+	bm.metrics.IncrementCounter("database_errors_total", map[string]string{
+		"operation":  operation,
+		"error_type": errorType,
+	})
+
+	bm.logger.Debug("Recorded database error",
+		zap.String("operation", operation),
+		zap.String("error_type", errorType))
+}
+
+// 获取统计信息
+
+// GetUserStats 获取用户统计
+func (bm *BusinessMetrics) GetUserStats() map[string]int64 {
+	bm.mutex.RLock()
+	defer bm.mutex.RUnlock()
+
+	stats := make(map[string]int64)
+	for k, v := range bm.userMetrics {
+		stats[k] = v
+	}
+	return stats
+}
+
+// GetOrderStats 获取订单统计
+func (bm *BusinessMetrics) GetOrderStats() map[string]int64 {
+	bm.mutex.RLock()
+	defer bm.mutex.RUnlock()
+
+	stats := make(map[string]int64)
+	for k, v := range bm.orderMetrics {
+		stats[k] = v
+	}
+	return stats
+}
+
+// GetOverallStats 获取整体统计
+func (bm *BusinessMetrics) GetOverallStats() map[string]interface{} {
+	return map[string]interface{}{
+		"user_stats":  bm.GetUserStats(),
+		"order_stats": bm.GetOrderStats(),
+	}
+}
+
+// Reset 重置统计数据
+func (bm *BusinessMetrics) Reset() {
+	bm.mutex.Lock()
+	defer bm.mutex.Unlock()
+
+	bm.userMetrics = make(map[string]int64)
+	bm.orderMetrics = make(map[string]int64)
+
+	bm.logger.Info("Business metrics reset")
+}
+
+// Context相关方法
+
+// WithContext 创建带上下文的业务指标收集器
+func (bm *BusinessMetrics) WithContext(ctx context.Context) *BusinessMetrics {
+	// 这里可以从context中提取追踪信息，关联指标
+	return bm
+}
+
+// 实现Service接口（如果需要）
+
+// Name 返回服务名称
+func (bm *BusinessMetrics) Name() string {
+	return "business-metrics"
+}
+
+// Initialize 初始化服务
+func (bm *BusinessMetrics) Initialize(ctx context.Context) error {
+	bm.logger.Info("Business metrics service initialized")
+	return nil
+}
+
+// HealthCheck 健康检查
+func (bm *BusinessMetrics) HealthCheck(ctx context.Context) error {
+	// 检查指标收集器是否正常
+	return nil
+}
+
+// Shutdown 关闭服务
+func (bm *BusinessMetrics) Shutdown(ctx context.Context) error {
+	bm.logger.Info("Business metrics service shutdown")
+	return nil
+}
--- a/internal/shared/metrics/prometheus_metrics.go
+++ b/internal/shared/metrics/prometheus_metrics.go
@@ -0,0 +1,353 @@
+package metrics
+
+import (
+	"net/http"
+	"strconv"
+	"sync"
+
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/promhttp"
+	"go.uber.org/zap"
+)
+
+// PrometheusMetrics Prometheus指标收集器
+type PrometheusMetrics struct {
+	logger   *zap.Logger
+	registry *prometheus.Registry
+	mutex    sync.RWMutex
+
+	// 预定义指标
+	httpRequests    *prometheus.CounterVec
+	httpDuration    *prometheus.HistogramVec
+	activeUsers     prometheus.Gauge
+	dbConnections   prometheus.Gauge
+	cacheHits       *prometheus.CounterVec
+	businessMetrics map[string]prometheus.Collector
+}
+
+// NewPrometheusMetrics 创建Prometheus指标收集器
+func NewPrometheusMetrics(logger *zap.Logger) *PrometheusMetrics {
+	registry := prometheus.NewRegistry()
+
+	// HTTP请求计数器
+	httpRequests := prometheus.NewCounterVec(
+		prometheus.CounterOpts{
+			Name: "http_requests_total",
+			Help: "Total number of HTTP requests",
+		},
+		[]string{"method", "path", "status"},
+	)
+
+	// HTTP请求耗时直方图
+	httpDuration := prometheus.NewHistogramVec(
+		prometheus.HistogramOpts{
+			Name:    "http_request_duration_seconds",
+			Help:    "HTTP request duration in seconds",
+			Buckets: prometheus.DefBuckets,
+		},
+		[]string{"method", "path"},
+	)
+
+	// 活跃用户数
+	activeUsers := prometheus.NewGauge(
+		prometheus.GaugeOpts{
+			Name: "active_users_total",
+			Help: "Current number of active users",
+		},
+	)
+
+	// 数据库连接数
+	dbConnections := prometheus.NewGauge(
+		prometheus.GaugeOpts{
+			Name: "database_connections_active",
+			Help: "Current number of active database connections",
+		},
+	)
+
+	// 缓存命中率
+	cacheHits := prometheus.NewCounterVec(
+		prometheus.CounterOpts{
+			Name: "cache_operations_total",
+			Help: "Total number of cache operations",
+		},
+		[]string{"operation", "result"},
+	)
+
+	// 注册指标
+	registry.MustRegister(httpRequests)
+	registry.MustRegister(httpDuration)
+	registry.MustRegister(activeUsers)
+	registry.MustRegister(dbConnections)
+	registry.MustRegister(cacheHits)
+
+	return &PrometheusMetrics{
+		logger:          logger,
+		registry:        registry,
+		httpRequests:    httpRequests,
+		httpDuration:    httpDuration,
+		activeUsers:     activeUsers,
+		dbConnections:   dbConnections,
+		cacheHits:       cacheHits,
+		businessMetrics: make(map[string]prometheus.Collector),
+	}
+}
+
+// RecordHTTPRequest 记录HTTP请求指标
+func (m *PrometheusMetrics) RecordHTTPRequest(method, path string, statusCode int, duration float64) {
+	status := strconv.Itoa(statusCode)
+
+	m.httpRequests.WithLabelValues(method, path, status).Inc()
+	m.httpDuration.WithLabelValues(method, path).Observe(duration)
+
+	m.logger.Debug("Recorded HTTP request metric",
+		zap.String("method", method),
+		zap.String("path", path),
+		zap.String("status", status),
+		zap.Float64("duration", duration))
+}
+
+// RecordHTTPDuration 记录HTTP请求耗时
+func (m *PrometheusMetrics) RecordHTTPDuration(method, path string, duration float64) {
+	m.httpDuration.WithLabelValues(method, path).Observe(duration)
+
+	m.logger.Debug("Recorded HTTP duration metric",
+		zap.String("method", method),
+		zap.String("path", path),
+		zap.Float64("duration", duration))
+}
+
+// IncrementCounter 增加计数器
+func (m *PrometheusMetrics) IncrementCounter(name string, labels map[string]string) {
+	if counter, exists := m.getOrCreateCounter(name, labels); exists {
+		if vec, ok := counter.(*prometheus.CounterVec); ok {
+			vec.With(labels).Inc()
+		}
+	}
+}
+
+// RecordGauge 记录仪表盘值
+func (m *PrometheusMetrics) RecordGauge(name string, value float64, labels map[string]string) {
+	if gauge, exists := m.getOrCreateGauge(name, labels); exists {
+		if vec, ok := gauge.(*prometheus.GaugeVec); ok {
+			vec.With(labels).Set(value)
+		} else if g, ok := gauge.(prometheus.Gauge); ok {
+			g.Set(value)
+		}
+	}
+}
+
+// RecordHistogram 记录直方图值
+func (m *PrometheusMetrics) RecordHistogram(name string, value float64, labels map[string]string) {
+	if histogram, exists := m.getOrCreateHistogram(name, labels); exists {
+		if vec, ok := histogram.(*prometheus.HistogramVec); ok {
+			vec.With(labels).Observe(value)
+		}
+	}
+}
+
+// RegisterCounter 注册计数器
+func (m *PrometheusMetrics) RegisterCounter(name, help string, labels []string) error {
+	m.mutex.Lock()
+	defer m.mutex.Unlock()
+
+	if _, exists := m.businessMetrics[name]; exists {
+		return nil // 已存在
+	}
+
+	var counter prometheus.Collector
+	if len(labels) > 0 {
+		counter = prometheus.NewCounterVec(
+			prometheus.CounterOpts{Name: name, Help: help},
+			labels,
+		)
+	} else {
+		counter = prometheus.NewCounter(
+			prometheus.CounterOpts{Name: name, Help: help},
+		)
+	}
+
+	if err := m.registry.Register(counter); err != nil {
+		return err
+	}
+
+	m.businessMetrics[name] = counter
+	m.logger.Info("Registered counter metric", zap.String("name", name))
+	return nil
+}
+
+// RegisterGauge 注册仪表盘
+func (m *PrometheusMetrics) RegisterGauge(name, help string, labels []string) error {
+	m.mutex.Lock()
+	defer m.mutex.Unlock()
+
+	if _, exists := m.businessMetrics[name]; exists {
+		return nil
+	}
+
+	var gauge prometheus.Collector
+	if len(labels) > 0 {
+		gauge = prometheus.NewGaugeVec(
+			prometheus.GaugeOpts{Name: name, Help: help},
+			labels,
+		)
+	} else {
+		gauge = prometheus.NewGauge(
+			prometheus.GaugeOpts{Name: name, Help: help},
+		)
+	}
+
+	if err := m.registry.Register(gauge); err != nil {
+		return err
+	}
+
+	m.businessMetrics[name] = gauge
+	m.logger.Info("Registered gauge metric", zap.String("name", name))
+	return nil
+}
+
+// RegisterHistogram 注册直方图
+func (m *PrometheusMetrics) RegisterHistogram(name, help string, labels []string, buckets []float64) error {
+	m.mutex.Lock()
+	defer m.mutex.Unlock()
+
+	if _, exists := m.businessMetrics[name]; exists {
+		return nil
+	}
+
+	if buckets == nil {
+		buckets = prometheus.DefBuckets
+	}
+
+	var histogram prometheus.Collector
+	if len(labels) > 0 {
+		histogram = prometheus.NewHistogramVec(
+			prometheus.HistogramOpts{
+				Name:    name,
+				Help:    help,
+				Buckets: buckets,
+			},
+			labels,
+		)
+	} else {
+		histogram = prometheus.NewHistogram(
+			prometheus.HistogramOpts{
+				Name:    name,
+				Help:    help,
+				Buckets: buckets,
+			},
+		)
+	}
+
+	if err := m.registry.Register(histogram); err != nil {
+		return err
+	}
+
+	m.businessMetrics[name] = histogram
+	m.logger.Info("Registered histogram metric", zap.String("name", name))
+	return nil
+}
+
+// GetHandler 获取HTTP处理器
+func (m *PrometheusMetrics) GetHandler() http.Handler {
+	return promhttp.HandlerFor(m.registry, promhttp.HandlerOpts{})
+}
+
+// 内部辅助方法
+
+func (m *PrometheusMetrics) getOrCreateCounter(name string, labels map[string]string) (prometheus.Collector, bool) {
+	m.mutex.RLock()
+	counter, exists := m.businessMetrics[name]
+	m.mutex.RUnlock()
+
+	if !exists {
+		// 自动创建计数器
+		labelNames := make([]string, 0, len(labels))
+		for k := range labels {
+			labelNames = append(labelNames, k)
+		}
+
+		if err := m.RegisterCounter(name, "Auto-created counter", labelNames); err != nil {
+			m.logger.Error("Failed to auto-create counter", zap.String("name", name), zap.Error(err))
+			return nil, false
+		}
+
+		m.mutex.RLock()
+		counter, exists = m.businessMetrics[name]
+		m.mutex.RUnlock()
+	}
+
+	return counter, exists
+}
+
+func (m *PrometheusMetrics) getOrCreateGauge(name string, labels map[string]string) (prometheus.Collector, bool) {
+	m.mutex.RLock()
+	gauge, exists := m.businessMetrics[name]
+	m.mutex.RUnlock()
+
+	if !exists {
+		labelNames := make([]string, 0, len(labels))
+		for k := range labels {
+			labelNames = append(labelNames, k)
+		}
+
+		if err := m.RegisterGauge(name, "Auto-created gauge", labelNames); err != nil {
+			m.logger.Error("Failed to auto-create gauge", zap.String("name", name), zap.Error(err))
+			return nil, false
+		}
+
+		m.mutex.RLock()
+		gauge, exists = m.businessMetrics[name]
+		m.mutex.RUnlock()
+	}
+
+	return gauge, exists
+}
+
+func (m *PrometheusMetrics) getOrCreateHistogram(name string, labels map[string]string) (prometheus.Collector, bool) {
+	m.mutex.RLock()
+	histogram, exists := m.businessMetrics[name]
+	m.mutex.RUnlock()
+
+	if !exists {
+		labelNames := make([]string, 0, len(labels))
+		for k := range labels {
+			labelNames = append(labelNames, k)
+		}
+
+		if err := m.RegisterHistogram(name, "Auto-created histogram", labelNames, nil); err != nil {
+			m.logger.Error("Failed to auto-create histogram", zap.String("name", name), zap.Error(err))
+			return nil, false
+		}
+
+		m.mutex.RLock()
+		histogram, exists = m.businessMetrics[name]
+		m.mutex.RUnlock()
+	}
+
+	return histogram, exists
+}
+
+// UpdateActiveUsers 更新活跃用户数
+func (m *PrometheusMetrics) UpdateActiveUsers(count float64) {
+	m.activeUsers.Set(count)
+}
+
+// UpdateDBConnections 更新数据库连接数
+func (m *PrometheusMetrics) UpdateDBConnections(count float64) {
+	m.dbConnections.Set(count)
+}
+
+// RecordCacheOperation 记录缓存操作
+func (m *PrometheusMetrics) RecordCacheOperation(operation, result string) {
+	m.cacheHits.WithLabelValues(operation, result).Inc()
+}
+
+// GetStats 获取指标统计
+func (m *PrometheusMetrics) GetStats() map[string]interface{} {
+	m.mutex.RLock()
+	defer m.mutex.RUnlock()
+
+	return map[string]interface{}{
+		"registered_metrics": len(m.businessMetrics),
+	}
+}