@dangao/bun-server 1.2.0 → 1.4.0

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

@@ -0,0 +1,20 @@
+export { ServiceRegistryModule } from './service-registry-module';
+export type { ServiceRegistryModuleOptions, ServiceRegistryProvider, NacosServiceRegistryOptions } from './service-registry-module';
+export { NacosServiceRegistry } from './nacos-service-registry';
+export { SERVICE_REGISTRY_TOKEN } from './types';
+export type { GetInstancesOptions, InstancesChangeListener, ServiceInstance, ServiceRegistry } from './types';
+export {
+  ServiceRegistry as ServiceRegistryDecorator,
+  getServiceRegistryMetadata,
+  registerServiceInstance,
+  deregisterServiceInstance,
+} from './decorators';
+export {
+  ServiceDiscovery,
+  getServiceDiscoveryMetadata,
+  initializeServiceDiscovery,
+  type ServiceDiscoveryMetadata,
+} from './discovery-decorators';
+export { ServiceRegistryHealthIntegration } from './health-integration';
+export type { ServiceRegistryMetadata } from './decorators';
+

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

@@ -0,0 +1,259 @@
+import { NacosClient, NacosServiceClient } from '@dangao/nacos-client';
+import type {
+  ServiceInstance,
+  GetInstancesOptions,
+  InstancesChangeListener,
+  ServiceRegistry,
+} from './types';
+
+/**
+ * Nacos 服务注册中心实现
+ * 实现 ServiceRegistry 接口，内部使用 @dangao/nacos-client
+ */
+export class NacosServiceRegistry implements ServiceRegistry {
+  private readonly client: NacosClient;
+  private readonly serviceClient: NacosServiceClient;
+  private readonly watchers: Map<string, { listener: InstancesChangeListener; intervalId: number }> = new Map();
+  private readonly watchInterval: number = 5000; // 默认 5 秒轮询一次
+  private readonly heartbeatInterval: number = 5000; // 默认 5 秒发送一次心跳
+  private heartbeatTimers: Map<string, number> = new Map();
+
+  public constructor(
+    client: NacosClient,
+    options?: {
+      /**
+       * 服务实例变更监听轮询间隔（毫秒）
+       * @default 5000
+       */
+      watchInterval?: number;
+
+      /**
+       * 心跳间隔（毫秒）
+       * @default 5000
+       */
+      heartbeatInterval?: number;
+    },
+  ) {
+    this.client = client;
+    this.serviceClient = new NacosServiceClient(client);
+    this.watchInterval = options?.watchInterval ?? 5000;
+    this.heartbeatInterval = options?.heartbeatInterval ?? 5000;
+  }
+
+  /**
+   * 注册服务实例
+   */
+  public async register(instance: ServiceInstance): Promise<void> {
+    await this.serviceClient.registerInstance({
+      serviceName: instance.serviceName,
+      ip: instance.ip,
+      port: instance.port,
+      weight: instance.weight,
+      enabled: instance.enabled,
+      metadata: instance.metadata,
+      clusterName: instance.clusterName,
+      namespaceId: instance.namespaceId,
+      groupName: instance.groupName,
+      heartBeat: false,
+    });
+
+    // 启动心跳机制
+    this.startHeartbeat(instance);
+  }
+
+  /**
+   * 注销服务实例
+   */
+  public async deregister(instance: ServiceInstance): Promise<void> {
+    // 停止心跳
+    this.stopHeartbeat(instance);
+
+    await this.serviceClient.deregisterInstance(instance.serviceName, instance.ip, instance.port, {
+      namespaceId: instance.namespaceId,
+      groupName: instance.groupName,
+      clusterName: instance.clusterName,
+    });
+  }
+
+  /**
+   * 续约服务实例（心跳）
+   */
+  public async renew(instance: ServiceInstance): Promise<void> {
+    await this.serviceClient.registerInstance({
+      serviceName: instance.serviceName,
+      ip: instance.ip,
+      port: instance.port,
+      weight: instance.weight,
+      enabled: instance.enabled,
+      metadata: instance.metadata,
+      clusterName: instance.clusterName,
+      namespaceId: instance.namespaceId,
+      groupName: instance.groupName,
+      heartBeat: true,
+    });
+  }
+
+  /**
+   * 查询服务实例列表
+   */
+  public async getInstances(
+    serviceName: string,
+    options?: GetInstancesOptions,
+  ): Promise<ServiceInstance[]> {
+    const instances = await this.serviceClient.getInstances({
+      serviceName,
+      namespaceId: options?.namespaceId,
+      groupName: options?.groupName,
+      clusterName: options?.clusterName,
+      healthyOnly: options?.healthyOnly,
+    });
+
+    return instances.map((instance) => ({
+      serviceName: instance.serviceName,
+      ip: instance.ip,
+      port: instance.port,
+      weight: instance.weight,
+      healthy: instance.healthy,
+      enabled: instance.enabled,
+      metadata: instance.metadata,
+      clusterName: instance.clusterName,
+      namespaceId: instance.namespaceId,
+      groupName: instance.groupName,
+    }));
+  }
+
+  /**
+   * 监听服务实例变更
+   * 通过轮询实现服务实例变更监听（Nacos 3.X 移除 UDP 推送）
+   */
+  public watchInstances(
+    serviceName: string,
+    listener: InstancesChangeListener,
+    options?: GetInstancesOptions,
+  ): () => void {
+    const key = this.getWatchKey(serviceName, options);
+
+    // 如果已经存在监听器，先取消
+    const existing = this.watchers.get(key);
+    if (existing) {
+      clearInterval(existing.intervalId);
+    }
+
+    const intervalId = setInterval(async () => {
+      try {
+        const instances = await this.getInstances(serviceName, options);
+        listener(instances);
+      } catch (error) {
+        // 监听错误不抛出，避免影响其他监听器
+        console.error(`[NacosServiceRegistry] Failed to watch instances ${serviceName}:`, error);
+      }
+    }, this.watchInterval) as unknown as number;
+
+    // 立即获取一次实例列表
+    this.getInstances(serviceName, options)
+      .then((instances) => {
+        listener(instances);
+      })
+      .catch((error) => {
+        console.error(`[NacosServiceRegistry] Failed to get initial instances ${serviceName}:`, error);
+      });
+
+    this.watchers.set(key, { listener, intervalId });
+
+    // 返回取消监听的函数
+    return () => {
+      const watcher = this.watchers.get(key);
+      if (watcher) {
+        clearInterval(watcher.intervalId);
+        this.watchers.delete(key);
+      }
+    };
+  }
+
+  /**
+   * 关闭注册中心连接
+   */
+  public async close(): Promise<void> {
+    // 清除所有监听器
+    for (const watcher of this.watchers.values()) {
+      clearInterval(watcher.intervalId);
+    }
+    this.watchers.clear();
+
+    // 清除所有心跳定时器
+    for (const timerId of this.heartbeatTimers.values()) {
+      clearInterval(timerId);
+    }
+    this.heartbeatTimers.clear();
+  }
+
+  /**
+   * 启动心跳机制
+   */
+  private startHeartbeat(instance: ServiceInstance): void {
+    const key = this.getInstanceKey(instance);
+
+    // 如果已经存在心跳，先停止
+    const existing = this.heartbeatTimers.get(key);
+    if (existing) {
+      clearInterval(existing);
+    }
+
+    const timerId = setInterval(async () => {
+      try {
+        await this.renew(instance);
+      } catch (error) {
+        console.error(`[NacosServiceRegistry] Failed to send heartbeat for ${instance.serviceName}:`, error);
+        // 心跳失败时，尝试重新注册
+        try {
+          await this.register(instance);
+        } catch (registerError) {
+          console.error(`[NacosServiceRegistry] Failed to re-register ${instance.serviceName}:`, registerError);
+        }
+      }
+    }, this.heartbeatInterval) as unknown as number;
+
+    this.heartbeatTimers.set(key, timerId);
+  }
+
+  /**
+   * 停止心跳机制
+   */
+  private stopHeartbeat(instance: ServiceInstance): void {
+    const key = this.getInstanceKey(instance);
+    const timerId = this.heartbeatTimers.get(key);
+    if (timerId) {
+      clearInterval(timerId);
+      this.heartbeatTimers.delete(key);
+    }
+  }
+
+  /**
+   * 生成监听器 key
+   */
+  private getWatchKey(serviceName: string, options?: GetInstancesOptions): string {
+    const parts = [
+      options?.namespaceId ?? 'default',
+      options?.groupName ?? 'DEFAULT_GROUP',
+      options?.clusterName ?? 'DEFAULT',
+      serviceName,
+    ];
+    return parts.join(':');
+  }
+
+  /**
+   * 生成实例 key
+   */
+  private getInstanceKey(instance: ServiceInstance): string {
+    const parts = [
+      instance.namespaceId ?? 'default',
+      instance.groupName ?? 'DEFAULT_GROUP',
+      instance.clusterName ?? 'DEFAULT',
+      instance.serviceName,
+      instance.ip,
+      instance.port.toString(),
+    ];
+    return parts.join(':');
+  }
+}
+

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

@@ -0,0 +1,105 @@
+import { Module, MODULE_METADATA_KEY, type ModuleProvider } from '../../di/module';
+import { NacosClient } from '@dangao/nacos-client';
+import type { NacosClientOptions } from '@dangao/nacos-client';
+import { NacosServiceRegistry } from './nacos-service-registry';
+import { SERVICE_REGISTRY_TOKEN, type ServiceRegistry } from './types';
+
+/**
+ * 服务注册中心 Provider 类型
+ */
+export type ServiceRegistryProvider = 'nacos' | 'consul' | 'eureka' | 'etcd';
+
+/**
+ * Nacos 服务注册中心选项
+ */
+export interface NacosServiceRegistryOptions {
+  /**
+   * Nacos 客户端配置
+   */
+  client: NacosClientOptions;
+
+  /**
+   * 服务实例变更监听轮询间隔（毫秒）
+   * @default 5000
+   */
+  watchInterval?: number;
+
+  /**
+   * 心跳间隔（毫秒）
+   * @default 5000
+   */
+  heartbeatInterval?: number;
+}
+
+/**
+ * 服务注册中心模块选项
+ */
+export interface ServiceRegistryModuleOptions {
+  /**
+   * Provider 类型
+   */
+  provider: ServiceRegistryProvider;
+
+  /**
+   * Nacos 配置（当 provider 为 'nacos' 时使用）
+   */
+  nacos?: NacosServiceRegistryOptions;
+
+  // 未来可以添加其他 provider 的配置
+  // consul?: ConsulServiceRegistryOptions;
+  // eureka?: EurekaServiceRegistryOptions;
+}
+
+/**
+ * 服务注册中心模块
+ */
+@Module({
+  providers: [],
+})
+export class ServiceRegistryModule {
+  /**
+   * 创建服务注册中心模块
+   * @param options - 模块配置
+   */
+  public static forRoot(options: ServiceRegistryModuleOptions): typeof ServiceRegistryModule {
+    const providers: ModuleProvider[] = [];
+
+    let serviceRegistry: ServiceRegistry;
+
+    switch (options.provider) {
+      case 'nacos':
+        if (!options.nacos) {
+          throw new Error('Nacos configuration is required when provider is "nacos"');
+        }
+
+        const nacosClient = new NacosClient(options.nacos.client);
+        serviceRegistry = new NacosServiceRegistry(nacosClient, {
+          watchInterval: options.nacos.watchInterval,
+          heartbeatInterval: options.nacos.heartbeatInterval,
+        });
+        break;
+
+      default:
+        throw new Error(`Unsupported service registry provider: ${options.provider}`);
+    }
+
+    providers.push({
+      provide: SERVICE_REGISTRY_TOKEN,
+      useValue: serviceRegistry,
+    });
+
+    const existingMetadata = Reflect.getMetadata(MODULE_METADATA_KEY, ServiceRegistryModule) || {};
+    const metadata = {
+      ...existingMetadata,
+      providers: [...(existingMetadata.providers || []), ...providers],
+      exports: [
+        ...(existingMetadata.exports || []),
+        SERVICE_REGISTRY_TOKEN,
+      ],
+    };
+    Reflect.defineMetadata(MODULE_METADATA_KEY, metadata, ServiceRegistryModule);
+
+    return ServiceRegistryModule;
+  }
+}
+

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

@@ -0,0 +1,149 @@
+/**
+ * 服务注册中心抽象接口
+ * 定义服务注册与发现的核心能力，不依赖具体实现
+ */
+export interface ServiceRegistry {
+  /**
+   * 注册服务实例
+   * @param instance - 服务实例信息
+   */
+  register(instance: ServiceInstance): Promise<void>;
+
+  /**
+   * 注销服务实例
+   * @param instance - 服务实例信息
+   */
+  deregister(instance: ServiceInstance): Promise<void>;
+
+  /**
+   * 续约服务实例（心跳）
+   * @param instance - 服务实例信息
+   */
+  renew(instance: ServiceInstance): Promise<void>;
+
+  /**
+   * 查询服务实例列表
+   * @param serviceName - 服务名
+   * @param options - 查询选项
+   * @returns 服务实例列表
+   */
+  getInstances(
+    serviceName: string,
+    options?: GetInstancesOptions,
+  ): Promise<ServiceInstance[]>;
+
+  /**
+   * 监听服务实例变更
+   * @param serviceName - 服务名
+   * @param listener - 变更监听器
+   * @param options - 查询选项（可选）
+   * @returns 取消监听的函数
+   */
+  watchInstances(
+    serviceName: string,
+    listener: InstancesChangeListener,
+    options?: GetInstancesOptions,
+  ): () => void;
+
+  /**
+   * 关闭注册中心连接
+   */
+  close(): Promise<void>;
+}
+
+/**
+ * 服务实例信息
+ */
+export interface ServiceInstance {
+  /**
+   * 服务名
+   */
+  serviceName: string;
+
+  /**
+   * 实例 IP
+   */
+  ip: string;
+
+  /**
+   * 实例端口
+   */
+  port: number;
+
+  /**
+   * 权重（可选）
+   */
+  weight?: number;
+
+  /**
+   * 是否健康（可选）
+   */
+  healthy?: boolean;
+
+  /**
+   * 是否启用（可选）
+   */
+  enabled?: boolean;
+
+  /**
+   * 元数据（可选）
+   */
+  metadata?: Record<string, string>;
+
+  /**
+   * 集群名称（可选）
+   */
+  clusterName?: string;
+
+  /**
+   * 命名空间 ID（可选）
+   */
+  namespaceId?: string;
+
+  /**
+   * 分组名称（可选）
+   */
+  groupName?: string;
+}
+
+/**
+ * 服务实例查询选项
+ */
+export interface GetInstancesOptions {
+  /**
+   * 命名空间 ID（可选）
+   */
+  namespaceId?: string;
+
+  /**
+   * 分组名称（可选）
+   */
+  groupName?: string;
+
+  /**
+   * 集群名称（可选）
+   */
+  clusterName?: string;
+
+  /**
+   * 是否只返回健康实例（可选）
+   */
+  healthyOnly?: boolean;
+}
+
+/**
+ * 服务实例变更监听器
+ */
+export interface InstancesChangeListener {
+  /**
+   * 服务实例变更回调
+   * @param instances - 新的服务实例列表
+   */
+  (instances: ServiceInstance[]): void;
+}
+
+/**
+ * ServiceRegistry Token（用于依赖注入）
+ */
+export const SERVICE_REGISTRY_TOKEN = Symbol('SERVICE_REGISTRY_TOKEN');
+

package/src/microservice/tracing/collectors.ts

@@ -0,0 +1,50 @@
+import type { Span, TraceCollector } from './types';
+
+/**
+ * 控制台追踪收集器（用于调试）
+ */
+export class ConsoleTraceCollector implements TraceCollector {
+  public collect(span: Span): void {
+    console.log('[Trace]', {
+      traceId: span.context.traceId,
+      spanId: span.context.spanId,
+      name: span.name,
+      duration: span.duration,
+      status: span.status,
+      tags: span.tags,
+    });
+  }
+}
+
+/**
+ * 内存追踪收集器（用于测试和开发）
+ */
+export class MemoryTraceCollector implements TraceCollector {
+  private readonly spans: Span[] = [];
+
+  public collect(span: Span): void {
+    this.spans.push(span);
+  }
+
+  /**
+   * 获取所有收集的 Span
+   */
+  public getSpans(): Span[] {
+    return [...this.spans];
+  }
+
+  /**
+   * 清空收集的 Span
+   */
+  public clear(): void {
+    this.spans.length = 0;
+  }
+
+  /**
+   * 获取指定 Trace ID 的所有 Span
+   */
+  public getSpansByTraceId(traceId: string): Span[] {
+    return this.spans.filter((span) => span.context.traceId === traceId);
+  }
+}
+

package/src/microservice/tracing/index.ts

@@ -0,0 +1,15 @@
+export { Tracer } from './tracer';
+export { ConsoleTraceCollector, MemoryTraceCollector } from './collectors';
+export {
+  SpanStatus,
+  SpanKind,
+  type TraceId,
+  type SpanId,
+  type SpanContext,
+  type Span,
+  type SpanTags,
+  type SpanEvent,
+  type TracingOptions,
+  type TraceCollector,
+} from './types';
+