@dangao/bun-server 1.2.0 → 1.4.0

package/src/microservice/config-center/nacos-decorators.ts

@@ -0,0 +1,34 @@
+import 'reflect-metadata';
+import { ConfigCenterValue } from './decorators';
+import type { Constructor } from '../../core/types';
+
+/**
+ * NacosValue 装饰器
+ * Nacos 特定的配置值注入装饰器
+ * 这是 @ConfigCenterValue 的便捷别名，专门用于 Nacos
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * class MyService {
+ *   @NacosValue('my-config', 'DEFAULT_GROUP')
+ *   public configValue: string = '';
+ *
+ *   @NacosValue('app-name', 'DEFAULT_GROUP', { defaultValue: 'MyApp' })
+ *   public appName: string = '';
+ * }
+ * ```
+ */
+export function NacosValue(
+  dataId: string,
+  groupName: string = 'DEFAULT_GROUP',
+  options?: {
+    namespaceId?: string;
+    defaultValue?: string;
+    watch?: boolean;
+  },
+): PropertyDecorator {
+  // 直接使用 ConfigCenterValue，因为 NacosConfigCenter 实现了 ConfigCenter 接口
+  return ConfigCenterValue(dataId, groupName, options);
+}
+

package/src/microservice/config-center/types.ts

@@ -0,0 +1,80 @@
+/**
+ * 配置中心抽象接口
+ * 定义配置中心的核心能力，不依赖具体实现
+ */
+export interface ConfigCenter {
+  /**
+   * 获取配置
+   * @param dataId - 配置 ID
+   * @param groupName - 配置分组
+   * @param namespaceId - 命名空间
+   * @returns 配置内容
+   */
+  getConfig(
+    dataId: string,
+    groupName: string,
+    namespaceId?: string,
+  ): Promise<ConfigResult>;
+
+  /**
+   * 监听配置变更
+   * @param dataId - 配置 ID
+   * @param groupName - 配置分组
+   * @param listener - 变更监听器
+   * @param namespaceId - 命名空间（可选）
+   * @returns 取消监听的函数
+   */
+  watchConfig(
+    dataId: string,
+    groupName: string,
+    listener: ConfigChangeListener,
+    namespaceId?: string,
+  ): () => void;
+
+  /**
+   * 关闭配置中心连接
+   */
+  close(): Promise<void>;
+}
+
+/**
+ * 配置查询结果
+ */
+export interface ConfigResult {
+  /**
+   * 配置内容
+   */
+  content: string;
+
+  /**
+   * 配置 MD5 值（用于判断配置是否变更）
+   */
+  md5: string;
+
+  /**
+   * 最后修改时间（时间戳）
+   */
+  lastModified: number;
+
+  /**
+   * 内容类型
+   */
+  contentType: string;
+}
+
+/**
+ * 配置变更监听器
+ */
+export interface ConfigChangeListener {
+  /**
+   * 配置变更回调
+   * @param result - 新的配置结果
+   */
+  (result: ConfigResult): void;
+}
+
+/**
+ * ConfigCenter Token（用于依赖注入）
+ */
+export const CONFIG_CENTER_TOKEN = Symbol('CONFIG_CENTER_TOKEN');
+

package/src/microservice/governance/circuit-breaker.ts

@@ -0,0 +1,229 @@
+import { CircuitBreakerState, type CircuitBreakerOptions, type CircuitBreakerStats } from './types';
+
+export { CircuitBreakerState, type CircuitBreakerOptions, type CircuitBreakerStats } from './types';
+
+/**
+ * 请求记录
+ */
+interface RequestRecord {
+  timestamp: number;
+  success: boolean;
+}
+
+/**
+ * 熔断器实现
+ */
+export class CircuitBreaker {
+  private state: CircuitBreakerState = CircuitBreakerState.CLOSED;
+  private readonly options: Required<CircuitBreakerOptions>;
+  private readonly records: RequestRecord[] = [];
+  private openTime?: number;
+  private halfOpenTestCount: number = 0;
+
+  public constructor(options: CircuitBreakerOptions = {}) {
+    this.options = {
+      failureThreshold: options.failureThreshold ?? 0.5,
+      timeWindow: options.timeWindow ?? 60000,
+      minimumRequests: options.minimumRequests ?? 10,
+      openDuration: options.openDuration ?? 60000,
+      halfOpenRequests: options.halfOpenRequests ?? 3,
+      timeout: options.timeout ?? 5000,
+    };
+  }
+
+  /**
+   * 执行请求（带熔断保护）
+   */
+  public async execute<T>(
+    fn: () => Promise<T>,
+    fallback?: () => Promise<T> | T,
+  ): Promise<T> {
+    // 检查熔断器状态
+    this.updateState();
+
+    if (this.state === CircuitBreakerState.OPEN) {
+      // 熔断器开启，执行降级逻辑
+      if (fallback) {
+        return Promise.resolve(fallback());
+      }
+      throw new Error('Circuit breaker is OPEN');
+    }
+
+    if (this.state === CircuitBreakerState.HALF_OPEN) {
+      // 半开状态，限制请求数
+      if (this.halfOpenTestCount >= this.options.halfOpenRequests) {
+        if (fallback) {
+          return Promise.resolve(fallback());
+        }
+        throw new Error('Circuit breaker is HALF_OPEN, test requests limit reached');
+      }
+      this.halfOpenTestCount++;
+    }
+
+    const startTime = Date.now();
+    let success = false;
+
+    try {
+      // 执行请求（带超时）
+      const result = await Promise.race([
+        fn(),
+        this.createTimeoutPromise(),
+      ]);
+
+      success = true;
+      this.recordRequest(success);
+      return result as T;
+    } catch (error) {
+      success = false;
+      this.recordRequest(success);
+      throw error;
+    } finally {
+      // 更新状态
+      this.updateState();
+    }
+  }
+
+  /**
+   * 记录请求
+   */
+  private recordRequest(success: boolean): void {
+    const now = Date.now();
+    this.records.push({
+      timestamp: now,
+      success,
+    });
+
+    // 清理过期记录
+    this.cleanupRecords(now);
+  }
+
+  /**
+   * 清理过期记录
+   */
+  private cleanupRecords(now: number): void {
+    const cutoff = now - this.options.timeWindow;
+    while (this.records.length > 0 && this.records[0]!.timestamp < cutoff) {
+      this.records.shift();
+    }
+  }
+
+  /**
+   * 更新熔断器状态
+   */
+  private updateState(): void {
+    const now = Date.now();
+
+    switch (this.state) {
+      case CircuitBreakerState.CLOSED:
+        // 检查是否需要开启熔断
+        if (this.shouldOpen()) {
+          this.state = CircuitBreakerState.OPEN;
+          this.openTime = now;
+        }
+        break;
+
+      case CircuitBreakerState.OPEN:
+        // 检查是否可以进入半开状态
+        if (this.openTime && now - this.openTime >= this.options.openDuration) {
+          this.state = CircuitBreakerState.HALF_OPEN;
+          this.halfOpenTestCount = 0;
+          this.openTime = undefined;
+        }
+        break;
+
+      case CircuitBreakerState.HALF_OPEN:
+        // 半开状态下，根据测试结果决定状态
+        if (this.shouldClose()) {
+          this.state = CircuitBreakerState.CLOSED;
+          this.halfOpenTestCount = 0;
+        } else if (this.shouldOpen()) {
+          this.state = CircuitBreakerState.OPEN;
+          this.openTime = now;
+          this.halfOpenTestCount = 0;
+        }
+        break;
+    }
+  }
+
+  /**
+   * 判断是否应该开启熔断
+   */
+  private shouldOpen(): boolean {
+    if (this.records.length < this.options.minimumRequests) {
+      return false;
+    }
+
+    const failureCount = this.records.filter((r) => !r.success).length;
+    const failureRate = failureCount / this.records.length;
+
+    return failureRate >= this.options.failureThreshold;
+  }
+
+  /**
+   * 判断是否应该关闭熔断（半开状态下）
+   */
+  private shouldClose(): boolean {
+    if (this.halfOpenTestCount === 0) {
+      return false;
+    }
+
+    // 检查最近的测试请求是否都成功
+    const recentRecords = this.records.slice(-this.halfOpenTestCount);
+    return recentRecords.every((r) => r.success);
+  }
+
+  /**
+   * 创建超时 Promise
+   */
+  private createTimeoutPromise(): Promise<never> {
+    return new Promise((_, reject) => {
+      setTimeout(() => {
+        reject(new Error(`Request timeout after ${this.options.timeout}ms`));
+      }, this.options.timeout);
+    });
+  }
+
+  /**
+   * 获取当前状态
+   */
+  public getState(): CircuitBreakerState {
+    this.updateState();
+    return this.state;
+  }
+
+  /**
+   * 获取统计信息
+   */
+  public getStats(): CircuitBreakerStats {
+    const now = Date.now();
+    this.cleanupRecords(now);
+
+    const totalRequests = this.records.length;
+    const failureRequests = this.records.filter((r) => !r.success).length;
+    const successRequests = totalRequests - failureRequests;
+    const failureRate = totalRequests > 0 ? failureRequests / totalRequests : 0;
+
+    const lastFailure = this.records.findLast((r) => !r.success);
+
+    return {
+      state: this.state,
+      totalRequests,
+      successRequests,
+      failureRequests,
+      failureRate,
+      lastFailureTime: lastFailure?.timestamp,
+      openTime: this.openTime,
+    };
+  }
+
+  /**
+   * 重置熔断器
+   */
+  public reset(): void {
+    this.state = CircuitBreakerState.CLOSED;
+    this.records.length = 0;
+    this.openTime = undefined;
+    this.halfOpenTestCount = 0;
+  }
+}
+

package/src/microservice/governance/decorators.ts

@@ -0,0 +1,113 @@
+import 'reflect-metadata';
+import type { CircuitBreakerOptions } from './types';
+import type { Constructor } from '../../core/types';
+
+/**
+ * 熔断器装饰器元数据键
+ */
+const CIRCUIT_BREAKER_METADATA_KEY = Symbol('circuit-breaker:metadata');
+
+/**
+ * 熔断器元数据
+ */
+export interface CircuitBreakerMetadata {
+  /**
+   * 熔断器选项
+   */
+  options?: CircuitBreakerOptions;
+
+  /**
+   * 降级处理函数名（可选）
+   */
+  fallbackMethod?: string;
+}
+
+/**
+ * CircuitBreaker 装饰器
+ * 用于在方法上自动应用熔断保护
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * class MyService {
+ *   @CircuitBreaker({
+ *     failureThreshold: 5,
+ *     resetTimeout: 60000,
+ *   })
+ *   public async callExternalService() {
+ *     // 自动应用熔断保护
+ *   }
+ *
+ *   @CircuitBreaker({
+ *     failureThreshold: 5,
+ *   }, 'fallbackMethod')
+ *   public async callWithFallback() {
+ *     // 自动应用熔断保护，失败时调用 fallbackMethod
+ *   }
+ *
+ *   private async fallbackMethod() {
+ *     return { message: 'Fallback response' };
+ *   }
+ * }
+ * ```
+ */
+export function CircuitBreaker(
+  options?: CircuitBreakerOptions,
+  fallbackMethod?: string,
+): MethodDecorator {
+  return function (
+    target: object,
+    propertyKey: string | symbol,
+    descriptor: PropertyDescriptor,
+  ) {
+    const metadata: CircuitBreakerMetadata = {
+      options,
+      fallbackMethod,
+    };
+
+    // 保存元数据
+    const existingMetadata: Map<string | symbol, CircuitBreakerMetadata> =
+      Reflect.getMetadata(CIRCUIT_BREAKER_METADATA_KEY, target.constructor) ||
+      new Map();
+    existingMetadata.set(propertyKey, metadata);
+    Reflect.defineMetadata(
+      CIRCUIT_BREAKER_METADATA_KEY,
+      existingMetadata,
+      target.constructor,
+    );
+
+    // 保存原始方法
+    const originalMethod = descriptor.value;
+
+    // 包装方法，应用熔断保护
+    descriptor.value = async function (...args: any[]) {
+      // 动态导入 CircuitBreaker（避免循环依赖）
+      const { CircuitBreaker: CircuitBreakerImpl } = await import(
+        './circuit-breaker'
+      );
+
+      const circuitBreaker = new CircuitBreakerImpl(metadata.options);
+
+      const fallback = metadata.fallbackMethod
+        ? (this as any)[metadata.fallbackMethod]?.bind(this)
+        : undefined;
+
+      return circuitBreaker.execute(
+        () => originalMethod.apply(this, args),
+        fallback,
+      );
+    };
+  };
+}
+
+/**
+ * 获取方法的熔断器元数据
+ */
+export function getCircuitBreakerMetadata(
+  target: Constructor<unknown>,
+): Map<string | symbol, CircuitBreakerMetadata> {
+  return (
+    Reflect.getMetadata(CIRCUIT_BREAKER_METADATA_KEY, target) || new Map()
+  );
+}
+

package/src/microservice/governance/index.ts

@@ -0,0 +1,18 @@
+export { CircuitBreaker } from './circuit-breaker';
+export { CircuitBreakerState } from './types';
+export { RateLimiter } from './rate-limiter';
+export { RedisRateLimiter } from './redis-rate-limiter';
+export { RetryStrategyImpl } from './retry-strategy';
+export {
+  CircuitBreaker as CircuitBreakerDecorator,
+  getCircuitBreakerMetadata,
+} from './decorators';
+export type { CircuitBreakerMetadata } from './decorators';
+export type {
+  CircuitBreakerOptions,
+  CircuitBreakerStats,
+  RateLimiterOptions,
+  RetryStrategy,
+  RedisRateLimiterOptions,
+} from './types';
+

package/src/microservice/governance/rate-limiter.ts

@@ -0,0 +1,72 @@
+import type { RateLimiterOptions } from './types';
+
+/**
+ * 限流器实现（内存版）
+ */
+export class RateLimiter {
+  private readonly options: Required<Pick<RateLimiterOptions, 'requestsPerSecond' | 'timeWindow'>>;
+  private readonly requests: Map<string, number[]> = new Map();
+
+  public constructor(options: RateLimiterOptions = {}) {
+    this.options = {
+      requestsPerSecond: options.requestsPerSecond ?? 100,
+      timeWindow: options.timeWindow ?? 1000,
+    };
+  }
+
+  /**
+   * 检查是否允许请求
+   * @param key - 限流键（如服务名、IP 等）
+   * @returns 是否允许请求
+   */
+  public async allow(key: string): Promise<boolean> {
+    const now = Date.now();
+    const cutoff = now - this.options.timeWindow;
+
+    // 获取该键的请求记录
+    let timestamps = this.requests.get(key) ?? [];
+
+    // 清理过期记录
+    timestamps = timestamps.filter((ts) => ts > cutoff);
+
+    // 检查是否超过限制
+    if (timestamps.length >= this.options.requestsPerSecond) {
+      // 更新记录
+      this.requests.set(key, timestamps);
+      return false;
+    }
+
+    // 添加新请求记录
+    timestamps.push(now);
+    this.requests.set(key, timestamps);
+
+    return true;
+  }
+
+  /**
+   * 获取剩余请求数
+   * @param key - 限流键
+   * @returns 剩余请求数
+   */
+  public getRemaining(key: string): number {
+    const now = Date.now();
+    const cutoff = now - this.options.timeWindow;
+
+    const timestamps = this.requests.get(key) ?? [];
+    const validTimestamps = timestamps.filter((ts) => ts > cutoff);
+
+    return Math.max(0, this.options.requestsPerSecond - validTimestamps.length);
+  }
+
+  /**
+   * 重置限流器
+   */
+  public reset(key?: string): void {
+    if (key) {
+      this.requests.delete(key);
+    } else {
+      this.requests.clear();
+    }
+  }
+}
+

package/src/microservice/governance/redis-rate-limiter.ts

@@ -0,0 +1,154 @@
+import type { RateLimiterOptions } from './types';
+
+/**
+ * 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;
+}
+
+/**
+ * Redis 限流器实现（分布式限流）
+ * 支持多个服务实例共享限流状态
+ */
+export class RedisRateLimiter {
+  private readonly client: RedisRateLimiterOptions['client'];
+  private readonly keyPrefix: string;
+  private readonly options: Required<
+    Pick<RateLimiterOptions, 'requestsPerSecond' | 'timeWindow'>
+  >;
+
+  public constructor(
+    redisOptions: RedisRateLimiterOptions,
+    rateLimiterOptions: RateLimiterOptions = {},
+  ) {
+    this.client = redisOptions.client;
+    this.keyPrefix = redisOptions.keyPrefix ?? 'ratelimit:';
+    this.options = {
+      requestsPerSecond: rateLimiterOptions.requestsPerSecond ?? 100,
+      timeWindow: rateLimiterOptions.timeWindow ?? 1000,
+    };
+  }
+
+  /**
+   * 检查是否允许请求
+   * @param key - 限流键（如服务名、IP 等）
+   * @returns 是否允许请求
+   */
+  public async allow(key: string): Promise<boolean> {
+    const redisKey = this.getKey(key);
+    const windowSeconds = Math.ceil(this.options.timeWindow / 1000);
+
+    try {
+      // 使用 Redis INCR 原子操作递增计数器
+      const count = await this.client.incr(redisKey);
+
+      // 如果是第一次请求，设置过期时间
+      if (count === 1) {
+        await this.client.expire(redisKey, windowSeconds);
+      }
+
+      // 检查是否超过限制
+      return count <= this.options.requestsPerSecond;
+    } catch (error) {
+      console.error('[RedisRateLimiter] Failed to check rate limit:', error);
+      // 如果 Redis 操作失败，默认允许请求（fail-open 策略）
+      return true;
+    }
+  }
+
+  /**
+   * 获取剩余请求数
+   * @param key - 限流键
+   * @returns 剩余请求数
+   */
+  public async getRemaining(key: string): Promise<number> {
+    const redisKey = this.getKey(key);
+
+    try {
+      const countStr = await this.client.get(redisKey);
+      if (!countStr) {
+        return this.options.requestsPerSecond;
+      }
+
+      const count = parseInt(countStr, 10);
+      return Math.max(0, this.options.requestsPerSecond - count);
+    } catch (error) {
+      console.error('[RedisRateLimiter] Failed to get remaining:', error);
+      return this.options.requestsPerSecond;
+    }
+  }
+
+  /**
+   * 重置限流器
+   * @param key - 限流键（可选，如果不提供则重置所有）
+   */
+  public async reset(key?: string): Promise<void> {
+    if (key) {
+      const redisKey = this.getKey(key);
+      try {
+        await this.client.del(redisKey);
+      } catch (error) {
+        console.error('[RedisRateLimiter] Failed to reset:', error);
+      }
+    } else {
+      // 注意：重置所有键需要遍历所有匹配的键，这在生产环境中可能很慢
+      // 建议使用具体的 key 进行重置
+      console.warn(
+        '[RedisRateLimiter] Resetting all keys is not supported. Please provide a specific key.',
+      );
+    }
+  }
+
+  /**
+   * 生成 Redis 键
+   */
+  private getKey(key: string): string {
+    return `${this.keyPrefix}${key}`;
+  }
+}
+