@dangao/bun-server 1.2.0 → 1.4.0

package/src/microservice/service-client/types.ts

@@ -0,0 +1,186 @@
+import type { ServiceInstance } from '../service-registry/types';
+
+/**
+ * 负载均衡策略类型
+ */
+export type LoadBalanceStrategy = 'random' | 'roundRobin' | 'weightedRoundRobin' | 'consistentHash' | 'leastActive';
+
+/**
+ * 负载均衡器接口
+ */
+export interface LoadBalancer {
+  /**
+   * 选择服务实例
+   * @param instances - 服务实例列表
+   * @param key - 用于一致性哈希的键（可选）
+   * @returns 选中的服务实例
+   */
+  select(instances: ServiceInstance[], key?: string): ServiceInstance | null;
+}
+
+/**
+ * 服务调用选项
+ */
+export interface ServiceCallOptions {
+  /**
+   * 服务名
+   */
+  serviceName: string;
+
+  /**
+   * HTTP 方法
+   */
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+
+  /**
+   * 请求路径
+   */
+  path: string;
+
+  /**
+   * 请求头（可选）
+   */
+  headers?: Record<string, string>;
+
+  /**
+   * 请求体（可选）
+   */
+  body?: string | object;
+
+  /**
+   * 查询参数（可选）
+   */
+  query?: Record<string, string | number | boolean>;
+
+  /**
+   * 超时时间（毫秒）
+   * @default 5000
+   */
+  timeout?: number;
+
+  /**
+   * 重试次数
+   * @default 0
+   */
+  retryCount?: number;
+
+  /**
+   * 重试延迟（毫秒）
+   * @default 1000
+   */
+  retryDelay?: number;
+
+  /**
+   * 负载均衡策略
+   * @default 'roundRobin'
+   */
+  loadBalanceStrategy?: LoadBalanceStrategy;
+
+  /**
+   * 用于一致性哈希的键（可选）
+   */
+  consistentHashKey?: string;
+
+  /**
+   * 服务实例查询选项（可选）
+   */
+  instanceOptions?: {
+    namespaceId?: string;
+    groupName?: string;
+    clusterName?: string;
+    healthyOnly?: boolean;
+  };
+
+  /**
+   * 是否启用熔断器（可选）
+   * @default false
+   */
+  enableCircuitBreaker?: boolean;
+
+  /**
+   * 熔断器降级处理函数（可选）
+   */
+  fallback?: () => Promise<unknown> | unknown;
+
+  /**
+   * 是否启用限流（可选）
+   * @default false
+   */
+  enableRateLimit?: boolean;
+
+  /**
+   * 限流键（可选，默认使用服务名）
+   */
+  rateLimitKey?: string;
+
+  /**
+   * 是否流式响应（用于 Server-Sent Events 等）
+   * @default false
+   */
+  stream?: boolean;
+}
+
+/**
+ * 服务调用响应
+ */
+export interface ServiceCallResponse<T = unknown> {
+  /**
+   * HTTP 状态码
+   */
+  status: number;
+
+  /**
+   * 响应头
+   */
+  headers: Record<string, string>;
+
+  /**
+   * 响应体
+   */
+  data: T;
+
+  /**
+   * 使用的服务实例
+   */
+  instance: ServiceInstance;
+}
+
+/**
+ * 服务请求拦截器接口
+ */
+export interface ServiceRequestInterceptor {
+  /**
+   * 拦截请求
+   * @param options - 服务调用选项
+   * @returns 修改后的选项或 Promise
+   */
+  intercept(options: ServiceCallOptions): ServiceCallOptions | Promise<ServiceCallOptions>;
+}
+
+/**
+ * 服务响应拦截器接口
+ */
+export interface ServiceResponseInterceptor {
+  /**
+   * 拦截响应
+   * @param response - 服务调用响应
+   * @returns 修改后的响应或 Promise
+   */
+  intercept<T>(response: ServiceCallResponse<T>): ServiceCallResponse<T> | Promise<ServiceCallResponse<T>>;
+}
+
+/**
+ * 服务调用错误
+ */
+export class ServiceCallError extends Error {
+  public constructor(
+    message: string,
+    public readonly status?: number,
+    public readonly response?: unknown,
+    public readonly instance?: ServiceInstance,
+  ) {
+    super(message);
+    this.name = 'ServiceCallError';
+  }
+}
+

package/src/microservice/service-registry/decorators.ts

@@ -0,0 +1,238 @@
+import 'reflect-metadata';
+import type { ServiceRegistry, ServiceInstance } from './types';
+import { SERVICE_REGISTRY_TOKEN } from './types';
+import { ControllerRegistry } from '../../controller/controller';
+import { ServiceRegistryHealthIntegration } from './health-integration';
+import type { Constructor } from '../../core/types';
+
+/**
+ * 服务注册装饰器元数据键
+ */
+const SERVICE_REGISTRY_METADATA_KEY = Symbol('service-registry:metadata');
+
+/**
+ * 服务注册元数据
+ */
+export interface ServiceRegistryMetadata {
+  /**
+   * 服务名
+   */
+  serviceName: string;
+
+  /**
+   * 服务 IP（可选，默认从 Application 获取）
+   */
+  ip?: string;
+
+  /**
+   * 服务端口（可选，默认从 Application 获取）
+   */
+  port?: number;
+
+  /**
+   * 服务权重（可选）
+   */
+  weight?: number;
+
+  /**
+   * 是否启用（可选）
+   */
+  enabled?: boolean;
+
+  /**
+   * 元数据（可选）
+   */
+  metadata?: Record<string, string>;
+
+  /**
+   * 集群名（可选）
+   */
+  clusterName?: string;
+
+  /**
+   * 命名空间（可选）
+   */
+  namespaceId?: string;
+
+  /**
+   * 分组名（可选）
+   */
+  groupName?: string;
+
+  /**
+   * 是否健康（可选）
+   */
+  healthy?: boolean;
+}
+
+/**
+ * ServiceRegistry 装饰器
+ * 用于自动注册服务到注册中心
+ *
+ * @example
+ * ```typescript
+ * @ServiceRegistry('my-service', { port: 3000 })
+ * @Controller('/api')
+ * class MyController {
+ *   // 服务会在应用启动时自动注册
+ * }
+ * ```
+ */
+export function ServiceRegistry(
+  serviceName: string,
+  options?: {
+    ip?: string;
+    port?: number;
+    weight?: number;
+    enabled?: boolean;
+    metadata?: Record<string, string>;
+    clusterName?: string;
+    namespaceId?: string;
+    groupName?: string;
+    healthy?: boolean;
+  },
+): ClassDecorator {
+  return function (target: Constructor<unknown> | Function) {
+    const targetClass = target as Constructor<unknown>;
+    const metadata: ServiceRegistryMetadata = {
+      serviceName,
+      ip: options?.ip,
+      port: options?.port,
+      weight: options?.weight,
+      enabled: options?.enabled,
+      metadata: options?.metadata,
+      clusterName: options?.clusterName,
+      namespaceId: options?.namespaceId,
+      groupName: options?.groupName,
+      healthy: options?.healthy ?? true,
+    };
+
+    Reflect.defineMetadata(SERVICE_REGISTRY_METADATA_KEY, metadata, targetClass);
+  };
+}
+
+/**
+ * 获取服务注册元数据
+ */
+export function getServiceRegistryMetadata(
+  target: Constructor<unknown>,
+): ServiceRegistryMetadata | undefined {
+  return Reflect.getMetadata(SERVICE_REGISTRY_METADATA_KEY, target);
+}
+
+// 全局健康检查集成器实例（每个应用一个）
+let healthIntegration: ServiceRegistryHealthIntegration | undefined;
+
+/**
+ * 注册服务实例
+ */
+export async function registerServiceInstance(
+  target: Constructor<unknown>,
+  appPort?: number,
+  appHost?: string,
+): Promise<void> {
+  const metadata = getServiceRegistryMetadata(target);
+  if (!metadata) {
+    return;
+  }
+
+  const container = ControllerRegistry.getInstance().getContainer();
+  const serviceRegistry = container.resolve<ServiceRegistry>(
+    SERVICE_REGISTRY_TOKEN,
+  );
+
+  if (!serviceRegistry) {
+    console.warn(
+      `[ServiceRegistry] ServiceRegistry not found, skipping registration for ${metadata.serviceName}`,
+    );
+    return;
+  }
+
+  const instance: ServiceInstance = {
+    serviceName: metadata.serviceName,
+    ip: metadata.ip ?? appHost ?? '127.0.0.1',
+    port: metadata.port ?? appPort ?? 3000,
+    weight: metadata.weight,
+    enabled: metadata.enabled ?? true,
+    metadata: metadata.metadata,
+    clusterName: metadata.clusterName,
+    namespaceId: metadata.namespaceId,
+    groupName: metadata.groupName,
+    healthy: metadata.healthy ?? true,
+  };
+
+  try {
+    // 如果启用了健康检查集成，使用集成器注册
+    const hasHealthModule = container.isRegistered(
+      Symbol('@dangao/bun-server:health:indicators'),
+    );
+
+    if (hasHealthModule) {
+      if (!healthIntegration) {
+        healthIntegration = new ServiceRegistryHealthIntegration();
+      }
+      await healthIntegration.registerWithHealthCheck(instance);
+    } else {
+      // 普通注册
+      await serviceRegistry.register(instance);
+    }
+
+    console.log(
+      `[ServiceRegistry] Service ${metadata.serviceName} registered successfully at ${instance.ip}:${instance.port}`,
+    );
+  } catch (error) {
+    console.error(
+      `[ServiceRegistry] Failed to register service ${metadata.serviceName}:`,
+      error,
+    );
+  }
+}
+
+/**
+ * 注销服务实例
+ */
+export async function deregisterServiceInstance(
+  target: Constructor<unknown>,
+  appPort?: number,
+  appHost?: string,
+): Promise<void> {
+  const metadata = getServiceRegistryMetadata(target);
+  if (!metadata) {
+    return;
+  }
+
+  const container = ControllerRegistry.getInstance().getContainer();
+  const serviceRegistry = container.resolve<ServiceRegistry>(
+    SERVICE_REGISTRY_TOKEN,
+  );
+
+  if (!serviceRegistry) {
+    return;
+  }
+
+  const instance: ServiceInstance = {
+    serviceName: metadata.serviceName,
+    ip: metadata.ip ?? appHost ?? '127.0.0.1',
+    port: metadata.port ?? appPort ?? 3000,
+  };
+
+  try {
+    await serviceRegistry.deregister(instance);
+
+    // 停止健康检查更新（如果是最后一个实例）
+    if (healthIntegration) {
+      healthIntegration.stop();
+      healthIntegration = undefined;
+    }
+
+    console.log(
+      `[ServiceRegistry] Service ${metadata.serviceName} deregistered successfully`,
+    );
+  } catch (error) {
+    console.error(
+      `[ServiceRegistry] Failed to deregister service ${metadata.serviceName}:`,
+      error,
+    );
+  }
+}
+

package/src/microservice/service-registry/discovery-decorators.ts

@@ -0,0 +1,156 @@
+import 'reflect-metadata';
+import type { ServiceRegistry, ServiceInstance } from './types';
+import { SERVICE_REGISTRY_TOKEN } from './types';
+import { ControllerRegistry } from '../../controller/controller';
+import type { Constructor } from '../../core/types';
+
+/**
+ * 服务发现装饰器元数据键
+ */
+const SERVICE_DISCOVERY_METADATA_KEY = Symbol('service-discovery:metadata');
+
+/**
+ * 服务发现元数据
+ */
+export interface ServiceDiscoveryMetadata {
+  /**
+   * 服务名
+   */
+  serviceName: string;
+
+  /**
+   * 服务实例查询选项
+   */
+  options?: {
+    namespaceId?: string;
+    groupName?: string;
+    clusterName?: string;
+    healthyOnly?: boolean;
+  };
+
+  /**
+   * 属性名（用于注入服务实例列表）
+   */
+  propertyKey?: string | symbol;
+}
+
+/**
+ * ServiceDiscovery 装饰器
+ * 用于自动注入服务实例列表
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * class MyService {
+ *   @ServiceDiscovery('my-service')
+ *   public instances: ServiceInstance[] = [];
+ *
+ *   public async getServiceInstances() {
+ *     // instances 会自动更新
+ *     return this.instances;
+ *   }
+ * }
+ * ```
+ */
+export function ServiceDiscovery(
+  serviceName: string,
+  options?: {
+    namespaceId?: string;
+    groupName?: string;
+    clusterName?: string;
+    healthyOnly?: boolean;
+  },
+): PropertyDecorator {
+  return function (target: object, propertyKey: string | symbol) {
+    const metadata: ServiceDiscoveryMetadata = {
+      serviceName,
+      options,
+      propertyKey,
+    };
+
+    // 保存元数据
+    const existingMetadata: Map<string | symbol, ServiceDiscoveryMetadata> =
+      Reflect.getMetadata(SERVICE_DISCOVERY_METADATA_KEY, target.constructor) ||
+      new Map();
+    existingMetadata.set(propertyKey, metadata);
+    Reflect.defineMetadata(
+      SERVICE_DISCOVERY_METADATA_KEY,
+      existingMetadata,
+      target.constructor,
+    );
+
+    // 定义属性描述符，实现自动注入
+    // 注意：属性 getter 必须是同步的，不能是 async
+    // 实际值通过初始化函数在实例化时预加载
+    let instances: ServiceInstance[] = [];
+
+    Object.defineProperty(target, propertyKey, {
+      get: () => {
+        // 同步返回已加载的实例列表（如果还未加载，返回空数组）
+        return instances;
+      },
+      set: (newInstances: ServiceInstance[]) => {
+        instances = newInstances;
+      },
+      enumerable: true,
+      configurable: true,
+    });
+  };
+}
+
+/**
+ * 获取类的所有服务发现元数据
+ */
+export function getServiceDiscoveryMetadata(
+  target: Constructor<unknown>,
+): Map<string | symbol, ServiceDiscoveryMetadata> {
+  return (
+    Reflect.getMetadata(SERVICE_DISCOVERY_METADATA_KEY, target) || new Map()
+  );
+}
+
+/**
+ * 初始化类的服务发现属性
+ * 在类实例化后调用，自动加载服务实例列表
+ */
+export async function initializeServiceDiscovery(
+  instance: object,
+  target: Constructor<unknown>,
+): Promise<void> {
+  const metadata = getServiceDiscoveryMetadata(target);
+  const container = ControllerRegistry.getInstance().getContainer();
+  const serviceRegistry = container.resolve<ServiceRegistry>(
+    SERVICE_REGISTRY_TOKEN,
+  );
+
+  if (!serviceRegistry) {
+    return;
+  }
+
+  for (const [propertyKey, meta] of metadata.entries()) {
+    try {
+      const instances = await serviceRegistry.getInstances(meta.serviceName, {
+        namespaceId: meta.options?.namespaceId,
+        groupName: meta.options?.groupName,
+        clusterName: meta.options?.clusterName,
+        healthyOnly: meta.options?.healthyOnly ?? true,
+      });
+      (instance as any)[propertyKey] = instances;
+
+      // 设置监听器以自动更新实例列表
+      serviceRegistry.watchInstances(
+        meta.serviceName,
+        (newInstances) => {
+          (instance as any)[propertyKey] = newInstances;
+        },
+        meta.options,
+      );
+    } catch (error) {
+      console.error(
+        `[ServiceDiscovery] Failed to initialize instances for ${meta.serviceName}:`,
+        error,
+      );
+      (instance as any)[propertyKey] = [];
+    }
+  }
+}

package/src/microservice/service-registry/health-integration.ts

@@ -0,0 +1,146 @@
+import type { ServiceRegistry, ServiceInstance } from './types';
+import { SERVICE_REGISTRY_TOKEN } from './types';
+import { HEALTH_INDICATORS_TOKEN } from '../../health/types';
+import type { HealthIndicator } from '../../health/types';
+import { ControllerRegistry } from '../../controller/controller';
+
+/**
+ * 健康检查与服务注册集成器
+ * 根据健康检查状态自动更新服务注册的健康状态
+ */
+export class ServiceRegistryHealthIntegration {
+  private serviceRegistry?: ServiceRegistry;
+  private healthIndicators: HealthIndicator[] = [];
+  private updateInterval?: ReturnType<typeof setInterval>;
+  private registeredInstances: Map<string, ServiceInstance> = new Map();
+
+  /**
+   * 注册服务实例并启动健康检查集成
+   */
+  public async registerWithHealthCheck(
+    instance: ServiceInstance,
+  ): Promise<void> {
+    // 保存实例信息
+    this.registeredInstances.set(
+      `${instance.serviceName}:${instance.ip}:${instance.port}`,
+      instance,
+    );
+
+    // 获取 ServiceRegistry
+    try {
+      const container = ControllerRegistry.getInstance().getContainer();
+      this.serviceRegistry = container.resolve<ServiceRegistry>(
+        SERVICE_REGISTRY_TOKEN,
+      );
+      this.healthIndicators = container.resolve<HealthIndicator[]>(
+        HEALTH_INDICATORS_TOKEN,
+      ) || [];
+    } catch (error) {
+      console.warn(
+        '[ServiceRegistryHealthIntegration] ServiceRegistry or HealthIndicators not found',
+      );
+    }
+
+    if (!this.serviceRegistry) {
+      return;
+    }
+
+    // 初始注册
+    await this.serviceRegistry.register(instance);
+
+    // 启动定期健康检查更新
+    this.startHealthCheckUpdates(instance);
+  }
+
+  /**
+   * 启动健康检查更新
+   */
+  private startHealthCheckUpdates(instance: ServiceInstance): void {
+    // 如果已经有更新任务在运行，不重复启动
+    if (this.updateInterval) {
+      return;
+    }
+
+    // 定期更新健康状态（每 30 秒）
+    this.updateInterval = setInterval(async () => {
+      await this.updateHealthStatus();
+    }, 30000);
+
+    // 立即执行一次
+    this.updateHealthStatus().catch((error) => {
+      console.error('[ServiceRegistryHealthIntegration] Failed to update health status:', error);
+    });
+  }
+
+  /**
+   * 更新所有注册服务的健康状态
+   */
+  private async updateHealthStatus(): Promise<void> {
+    if (!this.serviceRegistry) {
+      return;
+    }
+
+    // 检查健康状态
+    const isHealthy = await this.checkHealth();
+
+    // 更新所有注册实例的健康状态
+    for (const instance of this.registeredInstances.values()) {
+      if (instance.healthy !== isHealthy) {
+        try {
+          // 更新实例的健康状态
+          const updatedInstance: ServiceInstance = {
+            ...instance,
+            healthy: isHealthy,
+          };
+
+          // 通过续约更新健康状态
+          await this.serviceRegistry.renew(updatedInstance);
+
+          console.log(
+            `[ServiceRegistryHealthIntegration] Updated health status for ${instance.serviceName} to ${isHealthy ? 'healthy' : 'unhealthy'}`,
+          );
+        } catch (error) {
+          console.error(
+            `[ServiceRegistryHealthIntegration] Failed to update health status for ${instance.serviceName}:`,
+            error,
+          );
+        }
+      }
+    }
+  }
+
+  /**
+   * 检查应用健康状态
+   */
+  private async checkHealth(): Promise<boolean> {
+    if (this.healthIndicators.length === 0) {
+      // 如果没有健康检查指示器，默认认为健康
+      return true;
+    }
+
+    try {
+      // 检查所有健康指示器
+      for (const indicator of this.healthIndicators) {
+        const result = await Promise.resolve(indicator.check());
+        if (result.status !== 'up') {
+          return false;
+        }
+      }
+      return true;
+    } catch (error) {
+      console.error('[ServiceRegistryHealthIntegration] Health check failed:', error);
+      return false;
+    }
+  }
+
+  /**
+   * 停止健康检查更新
+   */
+  public stop(): void {
+    if (this.updateInterval) {
+      clearInterval(this.updateInterval);
+      this.updateInterval = undefined;
+    }
+  }
+}
+