@dangao/bun-server 1.2.0 → 1.4.0

package/src/microservice/governance/retry-strategy.ts

@@ -0,0 +1,74 @@
+import type { RetryStrategy } from './types';
+
+/**
+ * 重试策略实现
+ */
+export class RetryStrategyImpl {
+  private readonly options: Required<Pick<RetryStrategy, 'maxRetries' | 'retryDelay' | 'exponentialBackoff' | 'baseDelay' | 'maxDelay'>> & {
+    shouldRetry?: RetryStrategy['shouldRetry'];
+  };
+
+  public constructor(options: RetryStrategy = {}) {
+    this.options = {
+      maxRetries: options.maxRetries ?? 3,
+      retryDelay: options.retryDelay ?? 1000,
+      exponentialBackoff: options.exponentialBackoff ?? false,
+      baseDelay: options.baseDelay ?? 1000,
+      maxDelay: options.maxDelay ?? 30000,
+      shouldRetry: options.shouldRetry,
+    };
+  }
+
+  /**
+   * 执行带重试的请求
+   */
+  public async execute<T>(fn: () => Promise<T>): Promise<T> {
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt <= this.options.maxRetries; attempt++) {
+      try {
+        return await fn();
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+
+        // 检查是否应该重试
+        if (attempt >= this.options.maxRetries) {
+          break;
+        }
+
+        if (this.options.shouldRetry && !this.options.shouldRetry(lastError)) {
+          break;
+        }
+
+        // 计算延迟时间
+        const delay = this.calculateDelay(attempt);
+
+        // 等待重试
+        await this.sleep(delay);
+      }
+    }
+
+    throw lastError ?? new Error('Retry failed');
+  }
+
+  /**
+   * 计算重试延迟
+   */
+  private calculateDelay(attempt: number): number {
+    if (!this.options.exponentialBackoff) {
+      return this.options.retryDelay;
+    }
+
+    // 指数退避：baseDelay * 2^attempt
+    const delay = this.options.baseDelay * Math.pow(2, attempt);
+    return Math.min(delay, this.options.maxDelay);
+  }
+
+  /**
+   * 休眠
+   */
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+

package/src/microservice/governance/types.ts

@@ -0,0 +1,247 @@
+/**
+ * 熔断器状态
+ */
+export enum CircuitBreakerState {
+  /**
+   * 关闭状态：正常处理请求
+   */
+  CLOSED = 'CLOSED',
+
+  /**
+   * 开启状态：拒绝请求，直接返回错误
+   */
+  OPEN = 'OPEN',
+
+  /**
+   * 半开状态：允许少量请求通过，用于测试服务是否恢复
+   */
+  HALF_OPEN = 'HALF_OPEN',
+}
+
+/**
+ * 熔断器配置选项
+ */
+export interface CircuitBreakerOptions {
+  /**
+   * 失败率阈值（0-1）
+   * 当失败率超过此值时，熔断器开启
+   * @default 0.5
+   */
+  failureThreshold?: number;
+
+  /**
+   * 时间窗口（毫秒）
+   * 在此时间窗口内统计失败率
+   * @default 60000
+   */
+  timeWindow?: number;
+
+  /**
+   * 最小请求数
+   * 在时间窗口内至少需要这么多请求才会触发熔断
+   * @default 10
+   */
+  minimumRequests?: number;
+
+  /**
+   * 熔断持续时间（毫秒）
+   * 熔断器开启后，持续多长时间才进入半开状态
+   * @default 60000
+   */
+  openDuration?: number;
+
+  /**
+   * 半开状态下的测试请求数
+   * 在半开状态下允许通过的请求数
+   * @default 3
+   */
+  halfOpenRequests?: number;
+
+  /**
+   * 超时时间（毫秒）
+   * 请求超过此时间视为失败
+   * @default 5000
+   */
+  timeout?: number;
+}
+
+/**
+ * 熔断器统计信息
+ */
+export interface CircuitBreakerStats {
+  /**
+   * 当前状态
+   */
+  state: CircuitBreakerState;
+
+  /**
+   * 总请求数
+   */
+  totalRequests: number;
+
+  /**
+   * 成功请求数
+   */
+  successRequests: number;
+
+  /**
+   * 失败请求数
+   */
+  failureRequests: number;
+
+  /**
+   * 当前失败率
+   */
+  failureRate: number;
+
+  /**
+   * 最后失败时间
+   */
+  lastFailureTime?: number;
+
+  /**
+   * 熔断开启时间
+   */
+  openTime?: number;
+}
+
+/**
+ * 限流器配置选项
+ */
+export interface RateLimiterOptions {
+  /**
+   * 每秒允许的请求数
+   * @default 100
+   */
+  requestsPerSecond?: number;
+
+  /**
+   * 时间窗口（毫秒）
+   * @default 1000
+   */
+  timeWindow?: number;
+
+  /**
+   * 是否使用分布式限流（需要 Redis）
+   * @default false
+   */
+  distributed?: boolean;
+
+  /**
+   * Redis 配置（分布式限流时使用）
+   */
+  redis?: {
+    host: string;
+    port: number;
+    password?: string;
+  };
+}
+
+/**
+ * 重试策略配置
+ */
+export interface RetryStrategy {
+  /**
+   * 最大重试次数
+   * @default 3
+   */
+  maxRetries?: number;
+
+  /**
+   * 重试延迟（毫秒）
+   * @default 1000
+   */
+  retryDelay?: number;
+
+  /**
+   * 是否使用指数退避
+   * @default false
+   */
+  exponentialBackoff?: boolean;
+
+  /**
+   * 指数退避的基础延迟（毫秒）
+   * @default 1000
+   */
+  baseDelay?: number;
+
+  /**
+   * 指数退避的最大延迟（毫秒）
+   * @default 30000
+   */
+  maxDelay?: number;
+
+  /**
+   * 重试条件：哪些错误应该重试
+   * @param error - 错误对象
+   * @returns 是否应该重试
+   */
+  shouldRetry?: (error: Error) => boolean;
+}
+
+/**
+ * 重试决策
+ */
+export interface RetryDecision {
+  /**
+   * 是否重试
+   */
+  retry: boolean;
+
+  /**
+   * 延迟时间（毫秒）
+   */
+  delay: number;
+}
+
+/**
+ * Redis 限流器选项
+ */
+export interface RedisRateLimiterOptions {
+  /**
+   * Redis 客户端（需要用户提供）
+   * 支持任何兼容的 Redis 客户端接口
+   */
+  client: {
+    /**
+     * 获取键值
+     */
+    get(key: string): Promise<string | null>;
+
+    /**
+     * 设置键值（带过期时间）
+     */
+    set(
+      key: string,
+      value: string,
+      options?: { PX?: number; EX?: number },
+    ): Promise<void>;
+
+    /**
+     * 删除键
+     */
+    del(key: string): Promise<void>;
+
+    /**
+     * 递增键值（原子操作）
+     */
+    incr(key: string): Promise<number>;
+
+    /**
+     * 设置键的过期时间
+     */
+    expire(key: string, seconds: number): Promise<void>;
+
+    /**
+     * 检查键是否存在
+     */
+    exists(key: string): Promise<number>;
+  };
+
+  /**
+   * 键前缀
+   * @default 'ratelimit:'
+   */
+  keyPrefix?: string;
+}
+

package/src/microservice/index.ts

@@ -0,0 +1,12 @@
+export * from './config-center';
+export * from './service-registry';
+export * from './service-client';
+export * from './governance';
+export * from './tracing';
+export * from './monitoring';
+
+// 导出新增的装饰器
+export { NacosValue } from './config-center';
+export { ServiceDiscovery, type ServiceDiscoveryMetadata } from './service-registry';
+export { ServiceCall, type ServiceCallMetadata } from './service-client';
+

package/src/microservice/monitoring/index.ts

@@ -0,0 +1,8 @@
+export { ServiceMetricsCollector } from './metrics-collector';
+export { ServiceMetricsIntegration } from './metrics-integration';
+export type {
+  ServiceCallMetrics,
+  ServiceInstanceHealth,
+  MonitoringOptions,
+} from './types';
+

package/src/microservice/monitoring/metrics-collector.ts

@@ -0,0 +1,223 @@
+import type { ServiceCallMetrics, ServiceInstanceHealth, MonitoringOptions } from './types';
+import { ServiceMetricsIntegration } from './metrics-integration';
+
+/**
+ * 请求记录
+ */
+interface RequestRecord {
+  timestamp: number;
+  success: boolean;
+  latency: number;
+}
+
+/**
+ * 服务监控指标收集器
+ */
+export class ServiceMetricsCollector {
+  private readonly options: Required<MonitoringOptions>;
+  private readonly metrics: Map<string, ServiceCallMetrics> = new Map();
+  private readonly healthStatus: Map<string, ServiceInstanceHealth> = new Map();
+  private readonly requestRecords: Map<string, RequestRecord[]> = new Map();
+  private readonly maxRecordsPerInstance: number = 1000;
+  private metricsIntegration?: ServiceMetricsIntegration;
+
+  public constructor(options: MonitoringOptions = {}) {
+    this.options = {
+      enabled: options.enabled ?? true,
+      collectionInterval: options.collectionInterval ?? 60000,
+      autoReportToMetrics: options.autoReportToMetrics ?? true,
+    };
+
+    // 如果启用自动上报，创建集成器
+    if (this.options.autoReportToMetrics) {
+      this.metricsIntegration = new ServiceMetricsIntegration(this);
+      // 延迟启动，确保 MetricsModule 已注册
+      setTimeout(() => {
+        this.metricsIntegration?.start(this.options.collectionInterval);
+      }, 1000);
+    }
+  }
+
+  /**
+   * 记录服务调用
+   */
+  public recordCall(
+    serviceName: string,
+    instance: string,
+    success: boolean,
+    latency: number,
+  ): void {
+    if (!this.options.enabled) {
+      return;
+    }
+
+    const key = this.getKey(serviceName, instance);
+
+    // 记录请求
+    const records = this.requestRecords.get(key) ?? [];
+    records.push({
+      timestamp: Date.now(),
+      success,
+      latency,
+    });
+
+    // 限制记录数量
+    if (records.length > this.maxRecordsPerInstance) {
+      records.shift();
+    }
+    this.requestRecords.set(key, records);
+
+    // 更新指标
+    this.updateMetrics(serviceName, instance);
+
+    // 更新健康状态
+    this.updateHealthStatus(serviceName, instance, success);
+  }
+
+  /**
+   * 获取服务指标
+   */
+  public getMetrics(serviceName: string, instance?: string): ServiceCallMetrics[] {
+    const result: ServiceCallMetrics[] = [];
+
+    for (const [key, metrics] of this.metrics.entries()) {
+      if (metrics.serviceName === serviceName && (!instance || metrics.instance === instance)) {
+        result.push(metrics);
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * 获取所有指标
+   */
+  public getAllMetrics(): ServiceCallMetrics[] {
+    return Array.from(this.metrics.values());
+  }
+
+  /**
+   * 获取服务实例健康状态
+   */
+  public getHealthStatus(serviceName: string, instance?: string): ServiceInstanceHealth[] {
+    const result: ServiceInstanceHealth[] = [];
+
+    for (const [key, health] of this.healthStatus.entries()) {
+      if (health.serviceName === serviceName && (!instance || health.instance === instance)) {
+        result.push(health);
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * 获取所有健康状态
+   */
+  public getAllHealthStatus(): ServiceInstanceHealth[] {
+    return Array.from(this.healthStatus.values());
+  }
+
+  /**
+   * 更新指标
+   */
+  private updateMetrics(serviceName: string, instance: string): void {
+    const key = this.getKey(serviceName, instance);
+    const records = this.requestRecords.get(key) ?? [];
+
+    if (records.length === 0) {
+      return;
+    }
+
+    const totalRequests = records.length;
+    const successRequests = records.filter((r) => r.success).length;
+    const failureRequests = totalRequests - successRequests;
+    const errorRate = totalRequests > 0 ? failureRequests / totalRequests : 0;
+
+    const latencies = records.map((r) => r.latency);
+    const averageLatency = latencies.reduce((sum, l) => sum + l, 0) / latencies.length;
+    const minLatency = Math.min(...latencies);
+    const maxLatency = Math.max(...latencies);
+
+    const metrics: ServiceCallMetrics = {
+      serviceName,
+      instance,
+      totalRequests,
+      successRequests,
+      failureRequests,
+      averageLatency,
+      minLatency,
+      maxLatency,
+      errorRate,
+      lastUpdateTime: Date.now(),
+    };
+
+    this.metrics.set(key, metrics);
+  }
+
+  /**
+   * 更新健康状态
+   */
+  private updateHealthStatus(serviceName: string, instance: string, success: boolean): void {
+    const key = this.getKey(serviceName, instance);
+    const now = Date.now();
+
+    let health = this.healthStatus.get(key);
+    if (!health) {
+      health = {
+        serviceName,
+        instance,
+        healthy: true,
+        checkTime: now,
+        consecutiveFailures: 0,
+      };
+    }
+
+    if (success) {
+      health.healthy = true;
+      health.consecutiveFailures = 0;
+      health.lastSuccessTime = now;
+    } else {
+      health.consecutiveFailures++;
+      health.lastFailureTime = now;
+      // 连续失败 3 次以上认为不健康
+      if (health.consecutiveFailures >= 3) {
+        health.healthy = false;
+      }
+    }
+
+    health.checkTime = now;
+    this.healthStatus.set(key, health);
+  }
+
+  /**
+   * 生成键
+   */
+  private getKey(serviceName: string, instance: string): string {
+    return `${serviceName}:${instance}`;
+  }
+
+  /**
+   * 重置指标
+   */
+  public reset(serviceName?: string, instance?: string): void {
+    if (serviceName && instance) {
+      const key = this.getKey(serviceName, instance);
+      this.metrics.delete(key);
+      this.healthStatus.delete(key);
+      this.requestRecords.delete(key);
+    } else {
+      this.metrics.clear();
+      this.healthStatus.clear();
+      this.requestRecords.clear();
+    }
+  }
+
+  /**
+   * 停止指标收集和上报
+   */
+  public stop(): void {
+    this.metricsIntegration?.stop();
+  }
+}
+

package/src/microservice/monitoring/metrics-integration.ts

@@ -0,0 +1,154 @@
+import { MetricsCollector, METRICS_SERVICE_TOKEN } from '../../metrics';
+import { ControllerRegistry } from '../../controller/controller';
+import { ServiceMetricsCollector } from './metrics-collector';
+import type { ServiceCallMetrics, ServiceInstanceHealth } from './types';
+
+/**
+ * 服务监控指标集成器
+ * 将 ServiceMetricsCollector 的指标自动上报到 MetricsModule
+ */
+export class ServiceMetricsIntegration {
+  private metricsCollector?: MetricsCollector;
+  private serviceMetricsCollector: ServiceMetricsCollector;
+  private updateInterval?: ReturnType<typeof setInterval>;
+
+  public constructor(serviceMetricsCollector: ServiceMetricsCollector) {
+    this.serviceMetricsCollector = serviceMetricsCollector;
+  }
+
+  /**
+   * 启动指标上报
+   */
+  public start(intervalMs: number = 60000): void {
+    // 获取 MetricsCollector
+    try {
+      const container = ControllerRegistry.getInstance().getContainer();
+      this.metricsCollector = container.resolve<MetricsCollector>(
+        METRICS_SERVICE_TOKEN,
+      );
+    } catch (error) {
+      console.warn(
+        '[ServiceMetricsIntegration] MetricsCollector not found, skipping integration',
+      );
+      return;
+    }
+
+    if (!this.metricsCollector) {
+      return;
+    }
+
+    // 立即上报一次
+    this.reportMetrics();
+
+    // 定期上报
+    this.updateInterval = setInterval(() => {
+      this.reportMetrics();
+    }, intervalMs);
+  }
+
+  /**
+   * 停止指标上报
+   */
+  public stop(): void {
+    if (this.updateInterval) {
+      clearInterval(this.updateInterval);
+      this.updateInterval = undefined;
+    }
+  }
+
+  /**
+   * 上报指标到 MetricsCollector
+   */
+  private reportMetrics(): void {
+    if (!this.metricsCollector) {
+      return;
+    }
+
+    try {
+      const allMetrics = this.serviceMetricsCollector.getAllMetrics();
+      const allHealthStatus = this.serviceMetricsCollector.getAllHealthStatus();
+
+      // 上报服务调用指标
+      for (const metrics of allMetrics) {
+        const labels = {
+          service: metrics.serviceName,
+          instance: metrics.instance,
+        };
+
+        // 总请求数（counter）
+        this.metricsCollector.incrementCounter(
+          'service_calls_total',
+          labels,
+          metrics.totalRequests,
+        );
+
+        // 成功请求数（counter）
+        this.metricsCollector.incrementCounter(
+          'service_calls_success_total',
+          labels,
+          metrics.successRequests,
+        );
+
+        // 失败请求数（counter）
+        this.metricsCollector.incrementCounter(
+          'service_calls_failure_total',
+          labels,
+          metrics.failureRequests,
+        );
+
+        // 平均延迟（gauge）
+        this.metricsCollector.setGauge(
+          'service_call_latency_avg_ms',
+          labels,
+          metrics.averageLatency,
+        );
+
+        // 最小延迟（gauge）
+        this.metricsCollector.setGauge(
+          'service_call_latency_min_ms',
+          labels,
+          metrics.minLatency,
+        );
+
+        // 最大延迟（gauge）
+        this.metricsCollector.setGauge(
+          'service_call_latency_max_ms',
+          labels,
+          metrics.maxLatency,
+        );
+
+        // 错误率（gauge）
+        this.metricsCollector.setGauge(
+          'service_call_error_rate',
+          labels,
+          metrics.errorRate,
+        );
+      }
+
+      // 上报健康状态指标
+      for (const health of allHealthStatus) {
+        const labels = {
+          service: health.serviceName,
+          instance: health.instance,
+        };
+
+        // 健康状态（gauge: 1=健康, 0=不健康）
+        this.metricsCollector.setGauge(
+          'service_instance_healthy',
+          labels,
+          health.healthy ? 1 : 0,
+        );
+
+        // 连续失败次数（gauge）
+        this.metricsCollector.setGauge(
+          'service_instance_consecutive_failures',
+          labels,
+          health.consecutiveFailures,
+        );
+      }
+    } catch (error) {
+      console.error('[ServiceMetricsIntegration] Failed to report metrics:', error);
+    }
+  }
+}
+