imean-service-engine 2.3.0 → 2.4.0

package/dist/index.d.mts

@@ -1090,7 +1090,7 @@ interface SchedulePluginOptions {
      * Etcd3 客户端实例
      * 如果未提供且 useMockEtcd 为 false，插件将不会启动调度任务
      */
-    etcdClient?: Etcd3;
+    etcdClient?: Etcd3$1;
     /**
      * 是否使用 Mock Etcd（用于测试和本地开发）
      * 当设置为 true 时，将使用内置的 MockEtcd3，始终选举自己作为 leader
@@ -1102,20 +1102,26 @@ interface SchedulePluginOptions {
 }
 /**
  * Etcd3 类型定义（避免直接依赖 etcd3 包）
+ * 这些类型定义与 etcd3@1.1.2 的实际类型兼容
  */
-interface Etcd3 {
+interface Etcd3$1 {
     election(key: string, ttl: number): Election;
+    close(): void;
+    delete(): any;
+    get(key: string): any;
 }
 interface Election {
     observe(): Promise<Observer>;
     campaign(candidate: string): Campaign;
 }
 interface Observer {
-    on(event: "change", callback: (leader: string) => void): void;
+    on(event: "change", callback: (leader: string | undefined) => void): Observer;
+    on(event: "disconnected", callback: (error: Error) => void): Observer;
+    on(event: "error", callback: (error: Error) => void): Observer;
 }
 interface Campaign {
-    on(event: "error", callback: (error: any) => void): void;
-    on(event: "elected", callback: () => void): void;
+    on(event: "error", callback: (error: any) => void): Campaign;
+    on(event: "elected", callback: () => void): Campaign;
     resign(): Promise<void>;
 }
 
@@ -1173,7 +1179,7 @@ declare class Scheduler {
     private campaigns;
     private timers;
     private isLeader;
-    constructor(etcdClient: Etcd3);
+    constructor(etcdClient: Etcd3$1);
     /**
      * 启动调度任务
      */
@@ -1197,9 +1203,12 @@ declare class Scheduler {
  * 用于测试和本地开发，模拟 etcd 的选举机制
  * 始终选举第一个参与选举的候选者作为 leader
  */
-declare class MockEtcd3 implements Etcd3 {
+declare class MockEtcd3 implements Etcd3$1 {
     private elections;
     election(key: string, ttl: number): Election;
+    close(): void;
+    delete(): any;
+    get(key: string): any;
     getElection(key: string): MockElection | undefined;
     clearElections(): void;
 }
@@ -1339,6 +1348,518 @@ declare function convertHandlersToModuleInfoWithMetadata(handlers: HandlerMetada
     name: string;
 } | undefined): Record<string, ModuleInfo>;
 
+/**
+ * 配置项元数据
+ *
+ * 定义配置的基本信息，包括键、描述、Schema、默认值等
+ */
+interface ConfigMetadata {
+    /**
+     * 配置键（用于 etcd 存储）
+     */
+    key: string;
+    /**
+     * 配置描述
+     */
+    description?: string;
+    /**
+     * 配置的 Zod Schema（用于运行时验证）
+     */
+    schema?: z.ZodTypeAny;
+    /**
+     * 默认值
+     */
+    defaultValue?: any;
+    /**
+     * 是否为敏感信息（日志中脱敏）
+     */
+    sensitive?: boolean;
+}
+/**
+ * 动态配置装饰器选项
+ *
+ * 扩展 ConfigMetadata，添加 onChange 回调支持
+ *
+ * 配置优先级：ETCD > 环境变量 > defaultValue
+ * 环境变量名由 key 自动转换（kebab-case -> UPPER_SNAKE_CASE）
+ *
+ * 💡 **推荐**：直接使用 UPPER_SNAKE_CASE 格式作为 key，与环境变量名保持一致
+ *
+ * @example
+ * ```typescript
+ * // 推荐：使用 UPPER_SNAKE_CASE 格式 + 属性装饰器
+ * @Config({
+ *   key: "MAX_CONNECTIONS",  // 直接对应环境变量 MAX_CONNECTIONS
+ *   defaultValue: 100,
+ * })
+ * maxConnections!: number;  // TypeScript 完美推断类型
+ *
+ * // 也支持：使用 kebab-case 格式（自动转换）
+ * @Config({
+ *   key: "max-connections",  // 自动转换为环境变量 MAX_CONNECTIONS
+ *   defaultValue: 100,
+ * })
+ * maxConnections!: number;
+ * ```
+ */
+interface DynamicConfigOptions extends ConfigMetadata {
+    /**
+     * 配置变更回调（可选）
+     *
+     * 当配置值发生变化时，会触发此回调函数
+     *
+     * @param newValue 新的配置值
+     * @param oldValue 旧的配置值
+     */
+    onChange?: (newValue: any, oldValue: any) => void | Promise<void>;
+}
+/**
+ * 插件配置选项
+ *
+ * 定义 DynamicConfigPlugin 的初始化选项
+ */
+interface DynamicConfigPluginOptions {
+    /**
+     * Etcd3 客户端实例
+     * 如果未提供且 useMockEtcd 为 false，插件将使用默认配置
+     */
+    etcdClient?: Etcd3;
+    /**
+     * 是否使用 Mock Etcd（用于测试和本地开发）
+     * @default false
+     */
+    useMockEtcd?: boolean;
+    /**
+     * etcd 配置键前缀
+     * @default "/config"
+     */
+    etcdPrefix?: string;
+    /**
+     * 是否启用配置缓存（缓存到 MySQL）
+     * @default false
+     */
+    enablePersistence?: boolean;
+    /**
+     * MySQL 数据库配置（当 enablePersistence 为 true 时需要）
+     */
+    mysql?: {
+        host: string;
+        port: number;
+        user: string;
+        password: string;
+        database: string;
+    };
+    /**
+     * 配置同步间隔（毫秒）
+     * 从 MySQL 同步配置到 etcd 的间隔
+     * @default 30000 (30秒)
+     */
+    syncInterval?: number;
+}
+/**
+ * 配置存储接口
+ *
+ * 定义配置存储的标准操作，支持 etcd 和内存两种实现
+ */
+interface ConfigStorage {
+    /**
+     * 获取配置
+     */
+    get(key: string): Promise<any>;
+    /**
+     * 设置配置
+     */
+    set(key: string, value: any, metadata?: ConfigMetadata): Promise<void>;
+    /**
+     * 删除配置
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * 获取所有配置
+     */
+    getAll(prefix?: string): Promise<Map<string, any>>;
+    /**
+     * 监听配置变化
+     */
+    watch(key: string, callback: (newValue: any, oldValue: any) => void): () => void;
+    /**
+     * 同步获取缓存的配置（不访问 etcd）
+     * 用于 configProxy 的同步访问
+     */
+    getCached?(key: string): any;
+}
+/**
+ * 配置项（用于前端管理界面）
+ *
+ * 包含配置的详细信息，用于前端展示和编辑
+ */
+interface ConfigItem {
+    /**
+     * 配置键
+     */
+    key: string;
+    /**
+     * 配置值
+     */
+    value: any;
+    /**
+     * 配置描述
+     */
+    description?: string;
+    /**
+     * 配置类型
+     */
+    type: string;
+    /**
+     * 是否为敏感信息
+     */
+    sensitive: boolean;
+    /**
+     * 创建时间
+     */
+    createdAt: Date;
+    /**
+     * 更新时间
+     */
+    updatedAt: Date;
+    /**
+     * 创建人
+     */
+    createdBy?: string;
+    /**
+     * 更新人
+     */
+    updatedBy?: string;
+}
+/**
+ * 配置变更历史
+ *
+ * 记录配置的每次变更，用于审计和回滚
+ */
+interface ConfigHistory {
+    /**
+     * 历史 ID
+     */
+    id: string;
+    /**
+     * 配置键
+     */
+    key: string;
+    /**
+     * 旧值
+     */
+    oldValue: any;
+    /**
+     * 新值
+     */
+    newValue: any;
+    /**
+     * 变更时间
+     */
+    changedAt: Date;
+    /**
+     * 变更人
+     */
+    changedBy: string;
+    /**
+     * 变更原因
+     */
+    reason?: string;
+}
+/**
+ * Module 配置选项
+ *
+ * 用于 @Module 装饰器的 options 参数
+ */
+interface DynamicConfigModuleOptions {
+    /**
+     * 配置命名空间（用于区分不同模块的配置）
+     *
+     * 默认使用模块名
+     */
+    configNamespace?: string;
+}
+/**
+ * Etcd3 类型定义
+ *
+ * 避免直接依赖 etcd3 包，提供最小化的类型定义
+ */
+interface Etcd3 {
+    get(key: string): {
+        string(): Promise<string | null>;
+    };
+    put(key: string): {
+        value(value: string): Promise<void>;
+    };
+    delete(): {
+        key(key: string): Promise<void>;
+    };
+    getAll(): {
+        prefix(prefix: string): {
+            strings(): Promise<Record<string, string>>;
+        };
+    };
+    watch(): Watch;
+}
+interface Watch {
+    key(key: string): WatchBuilder;
+}
+interface WatchBuilder {
+    create(): Promise<Watcher>;
+}
+interface Watcher {
+    on(event: "put", callback: (kv: {
+        key: Buffer;
+        value: Buffer;
+    }) => void): void;
+    on(event: "delete", callback: (kv: {
+        key: Buffer;
+    }) => void): void;
+    cancel(): void;
+}
+
+/**
+ * DynamicConfigPlugin - 动态配置插件
+ *
+ * 提供基于 etcd 的动态配置功能，支持：
+ * - 装饰器驱动的配置定义 (@Config)
+ * - 实时配置热更新（通过 etcd watch 机制）
+ * - 类型安全（Zod Schema 运行时验证）
+ * - 完美的 TypeScript 类型推断
+ * - 自动预加载配置到缓存
+ * - 配置变更回调
+ * - 同步访问配置
+ *
+ * @example
+ * ```typescript
+ * // 基础用法
+ * const plugin = new DynamicConfigPlugin({
+ *   etcdClient: etcdInstance,
+ *   etcdPrefix: "/config",
+ * });
+ *
+ * @Module("user-service")
+ * class UserService {
+ *   @Config({
+ *     key: "MAX_LOGIN_ATTEMPTS",
+ *     defaultValue: 5,
+ *     schema: z.number().min(1).max(10),
+ *   })
+ *   maxLoginAttempts!: number;
+ * }
+ * ```
+ */
+declare class DynamicConfigPlugin implements Plugin<DynamicConfigModuleOptions> {
+    readonly name = "dynamic-config-plugin";
+    readonly priority = PluginPriority.BUSINESS;
+    private engine;
+    private storage;
+    private configHandlers;
+    private unwatchFunctions;
+    constructor(options?: DynamicConfigPluginOptions);
+    /**
+     * 声明 Module 配置 Schema
+     */
+    getModuleOptionsSchema(): PluginModuleOptionsSchema<DynamicConfigModuleOptions>;
+    /**
+     * 引擎初始化钩子
+     */
+    onInit(engine: Microservice): void;
+    /**
+     * Handler 加载钩子：收集所有动态配置
+     */
+    onHandlerLoad(handlers: HandlerMetadata[]): void;
+    /**
+     * 包装配置方法，实现动态配置注入
+     */
+    private wrapConfigHandler;
+    /**
+     * 引擎启动后钩子：启动配置监听和预加载配置
+     */
+    onAfterStart(engine: Microservice): Promise<void>;
+    /**
+     * 预加载所有配置到缓存，并将配置方法/属性转换为同步 getter
+     */
+    private preloadConfigs;
+    /**
+     * 引擎销毁钩子：清理资源
+     */
+    onDestroy(): Promise<void>;
+    /**
+     * 获取模块名称
+     */
+    private getModuleName;
+    /**
+     * 构建完整的配置键
+     */
+    private buildConfigKey;
+    /**
+     * 公共 API：获取配置
+     */
+    getConfig(key: string): Promise<any>;
+    /**
+     * 公共 API：同步获取配置（从缓存）
+     * 用于 configProxy 的同步访问
+     */
+    getConfigCached(key: string): any;
+    /**
+     * 公共 API：设置配置
+     */
+    setConfig(key: string, value: any, metadata?: ConfigMetadata): Promise<void>;
+    /**
+     * 公共 API：删除配置
+     */
+    deleteConfig(key: string): Promise<void>;
+    /**
+     * 公共 API：获取所有配置
+     */
+    getAllConfigs(prefix?: string): Promise<Map<string, any>>;
+    /**
+     * 公共 API：监听配置变化
+     */
+    watchConfig(key: string, callback: (newValue: any, oldValue: any) => void): () => void;
+}
+
+/**
+ * Config 属性装饰器
+ *
+ * 标记需要动态配置的属性，使其能够从 etcd 动态读取配置值
+ * ✅ 完美的 TypeScript 类型推断，无需类型断言
+ *
+ * @param options 动态配置选项
+ * @returns 属性装饰器
+ *
+ * @example
+ * ```typescript
+ * @Module("user-service")
+ * class UserService {
+ *   // ✅ 使用属性装饰器，完美的类型推断
+ *   @Config({
+ *     key: "MAX_LOGIN_ATTEMPTS",
+ *     description: "最大登录尝试次数",
+ *     schema: z.number().min(1).max(10),
+ *     defaultValue: 5,
+ *   })
+ *   maxLoginAttempts!: number;  // TypeScript 正确识别为 number
+ *
+ *   async login(username: string, password: string) {
+ *     // ✅ 完美：直接访问，类型正确
+ *     const maxAttempts = this.maxLoginAttempts;  // number 类型
+ *     if (attempts > maxAttempts) {
+ *       throw new Error("Too many attempts");
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // 带变更回调
+ * type FeatureFlags = {
+ *   enableNewUI: boolean;
+ *   enableBetaFeatures: boolean;
+ * };
+ *
+ * @Config({
+ *   key: "FEATURE_FLAGS",
+ *   schema: z.object({
+ *     enableNewUI: z.boolean(),
+ *     enableBetaFeatures: z.boolean(),
+ *   }),
+ *   defaultValue: {
+ *     enableNewUI: false,
+ *     enableBetaFeatures: false,
+ *   },
+ *   onChange: async (newValue, oldValue) => {
+ *     console.log("Feature flags changed:", { newValue, oldValue });
+ *   },
+ * })
+ * featureFlags!: FeatureFlags;  // TypeScript 正确识别类型
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // 支持环境变量（优先级：ETCD > ENV > DEFAULT）
+ * @Config({
+ *   key: "MAX_CONNECTIONS",
+ *   schema: z.number().min(1).max(1000),
+ *   defaultValue: 100,
+ * })
+ * maxConnections!: number;
+ *
+ * // 使用时完美
+ * useConnection() {
+ *   const num = this.maxConnections + 10;  // ✅ 类型正确，可以直接运算
+ *   const sum = this.maxConnections * 2;   // ✅ 类型正确，可以直接运算
+ * }
+ * ```
+ */
+declare function Config(options: DynamicConfigOptions): (target: undefined, context: ClassFieldDecoratorContext) => void;
+
+/**
+ * Etcd 配置存储实现
+ *
+ * 负责与 etcd 交互，提供配置的读取、写入、删除、监听功能
+ * 内置缓存机制，减少 etcd 访问次数
+ */
+declare class EtcdConfigStorage implements ConfigStorage {
+    private etcdClient;
+    private prefix;
+    private watchers;
+    private cache;
+    constructor(etcdClient: Etcd3, prefix?: string);
+    /**
+     * 构建完整的 etcd 键
+     */
+    private buildKey;
+    /**
+     * 获取配置
+     */
+    get(key: string): Promise<any>;
+    /**
+     * 同步获取缓存的配置（不访问 etcd）
+     * 用于 configProxy 的同步访问
+     */
+    getCached(key: string): any;
+    /**
+     * 设置配置
+     */
+    set(key: string, value: any, metadata?: ConfigMetadata): Promise<void>;
+    /**
+     * 删除配置
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * 获取所有配置
+     */
+    getAll(prefix?: string): Promise<Map<string, any>>;
+    /**
+     * 监听配置变化
+     */
+    watch(key: string, callback: (newValue: any, oldValue: any) => void): () => void;
+    /**
+     * 清理资源
+     */
+    destroy(): Promise<void>;
+}
+/**
+ * 内存配置存储实现
+ *
+ * 用于测试和本地开发环境，不依赖 etcd
+ * 配置存储在内存中，服务重启后会丢失
+ */
+declare class MemoryConfigStorage implements ConfigStorage {
+    private storage;
+    private watchers;
+    get(key: string): Promise<any>;
+    getCached(key: string): any;
+    set(key: string, value: any, metadata?: ConfigMetadata): Promise<void>;
+    delete(key: string): Promise<void>;
+    getAll(prefix?: string): Promise<Map<string, any>>;
+    watch(key: string, callback: (newValue: any, oldValue: any) => void): () => void;
+    destroy(): Promise<void>;
+}
+
 /**
  * 从插件数组中提取聚合的配置类型
  */
@@ -1418,4 +1939,4 @@ declare const Testing: {
 
 declare const logger: winston.Logger;
 
-export { Action, type ActionInfo, type ActionModuleOptions, type ActionOptions, ActionPlugin, BaseLayout, Cache, type CacheAdapter, type CacheItem, type CacheModuleOptions, type CacheOptions, CachePlugin, type Campaign, type Class, type ClassDecoratorContext, type ClassMethodDecoratorContext$1 as ClassMethodDecoratorContext, ClientCodePlugin, type ClientCodePluginOptions, DEFAULT_TEST_OPTIONS, DuplicateModuleError, type Election, type ErrorTransformer, type Etcd3, Factory, GracefulShutdownPlugin, type GracefulShutdownPluginOptions, type HTTPMethod, Handler, type HandlerMetadata, type HandlerWrapper, HtmxLayout, MemoryCacheAdapter, Microservice, type MicroserviceOptions, MockEtcd3, ModuleConfigValidationError, type ModuleDecorator, type ModuleInfo, type ModuleMetadata, type Observer, Page, type Plugin, type PluginModuleOptionsSchema, PluginNameRequiredError, PluginPriority, type PreStartChecker, RedisCacheAdapter, type RedisCacheAdapterOptions, Route, type RouteModuleOptions, type RouteOptions, RoutePlugin, type RoutePluginOptions, Schedule, type ScheduleMetadata, ScheduleMode, type ScheduleOptions, SchedulePlugin, type SchedulePluginOptions, Scheduler, ServiceInfoCards, type ServiceStatusInfo, ServiceStatusPage, Testing, convertHandlersToModuleInfo, convertHandlersToModuleInfoWithMetadata, generateClientCode, getZodTypeString, logger, startCheck };
+export { Action, type ActionInfo, type ActionModuleOptions, type ActionOptions, ActionPlugin, BaseLayout, Cache, type CacheAdapter, type CacheItem, type CacheModuleOptions, type CacheOptions, CachePlugin, type Campaign, type Class, type ClassDecoratorContext, type ClassMethodDecoratorContext$1 as ClassMethodDecoratorContext, ClientCodePlugin, type ClientCodePluginOptions, Config, type ConfigHistory, type ConfigItem, type ConfigMetadata, type ConfigStorage, DEFAULT_TEST_OPTIONS, DuplicateModuleError, type DynamicConfigModuleOptions, type DynamicConfigOptions, DynamicConfigPlugin, type DynamicConfigPluginOptions, type Election, type ErrorTransformer, type Etcd3$1 as Etcd3, EtcdConfigStorage, Factory, GracefulShutdownPlugin, type GracefulShutdownPluginOptions, type HTTPMethod, Handler, type HandlerMetadata, type HandlerWrapper, HtmxLayout, MemoryCacheAdapter, MemoryConfigStorage, Microservice, type MicroserviceOptions, MockEtcd3, ModuleConfigValidationError, type ModuleDecorator, type ModuleInfo, type ModuleMetadata, type Observer, Page, type Plugin, type PluginModuleOptionsSchema, PluginNameRequiredError, PluginPriority, type PreStartChecker, RedisCacheAdapter, type RedisCacheAdapterOptions, Route, type RouteModuleOptions, type RouteOptions, RoutePlugin, type RoutePluginOptions, Schedule, type ScheduleMetadata, ScheduleMode, type ScheduleOptions, SchedulePlugin, type SchedulePluginOptions, Scheduler, ServiceInfoCards, type ServiceStatusInfo, ServiceStatusPage, Testing, convertHandlersToModuleInfo, convertHandlersToModuleInfoWithMetadata, generateClientCode, getZodTypeString, logger, startCheck };