nebula-engine 1.0.0-beta3

package/dist/index.d.ts

@@ -0,0 +1,1984 @@
+import { Hono, MiddlewareHandler, Context } from 'hono';
+export { Context, MiddlewareHandler } from 'hono';
+import * as hono_utils_html from 'hono/utils/html';
+import * as hono_jsx_jsx_dev_runtime from 'hono/jsx/jsx-dev-runtime';
+import { ContentfulStatusCode } from 'hono/utils/http-status';
+import { z } from 'zod';
+export { z } from 'zod';
+import winston from 'winston';
+
+/**
+ * 微服务引擎实现类
+ * @internal 此类型仅供内部使用，用户应通过 Factory.create() 创建引擎实例
+ */
+declare class Microservice<ModuleOptions = Record<string, any>> {
+    private modules;
+    protected plugins: Plugin<Record<string, any>>[];
+    protected pluginRegistry: Map<string, Plugin<Record<string, any>>>;
+    private moduleInstances;
+    readonly options: Readonly<MicroserviceOptions>;
+    private started;
+    private readonly moduleMetadataKey;
+    private actualPort;
+    private hono;
+    private server;
+    constructor(options: MicroserviceOptions, moduleMetadataKey: symbol);
+    /**
+     * 获取 Hono 实例（供插件使用）
+     */
+    getHono(): Hono;
+    /**
+     * 内部注册插件方法（供构造函数和子类使用）
+     * @protected
+     */
+    protected registerPlugin<T>(plugin: Plugin<T>): void;
+    /**
+     * 加载并注册所有模块（通过唯一的 key 查找）
+     * 在引擎启动时调用，使用双向访问机制查找所有被装饰的类
+     *
+     * 注意：
+     * - 每个引擎实例使用唯一的 moduleMetadataKey，实现隔离
+     * - 模块类是静态的，可以被多个引擎实例共享
+     * - 每个引擎实例会创建独立的模块实例，互不影响
+     */
+    private loadModules;
+    /**
+     * 加载Handler元数据（平铺结构）
+     * 每个装饰器都是独立的HandlerMetadata条目
+     * 为每个方法创建包装链管理器，提供简单的 wrap API
+     */
+    private loadHandlerMetadata;
+    /**
+     * 应用所有包装链到原型
+     * 在所有插件执行完 onHandlerLoad 后调用
+     */
+    private applyWrapperChains;
+    /**
+     * 寻找一个随机的可用端口
+     */
+    private getRandomPort;
+    /**
+     * 启动引擎
+     * @param requestedPort 启动端口（可选，默认0，表示随机端口）
+     * @returns 实际使用的端口号
+     */
+    start(requestedPort?: number): Promise<number>;
+    /**
+     * 确定实际使用的端口
+     */
+    private determinePort;
+    /**
+     * 初始化模块和插件
+     */
+    private initializeModulesAndPlugins;
+    /**
+     * 处理 Handler 元数据和插件包装
+     */
+    private processHandlers;
+    /**
+     * 执行插件启动钩子
+     */
+    private executePluginStartHooks;
+    /**
+     * 注册版本路由（/prefix/version）
+     * 用于健康检查和探针
+     */
+    private registerVersionRoute;
+    /**
+     * 启动 HTTP 服务器
+     */
+    private startHttpServer;
+    /**
+     * 按优先级排序插件
+     */
+    private sortPluginsByPriority;
+    /**
+     * 获取插件优先级
+     */
+    private getPluginPriority;
+    /**
+     * 分离包装插件和路由插件
+     */
+    private separateWrapperAndRoutePlugins;
+    /**
+     * 执行插件钩子（通用方法）
+     */
+    private executePluginHook;
+    /**
+     * 停止引擎
+     */
+    stop(): Promise<void>;
+    /**
+     * 获取模块实例（单例）
+     * @param moduleClass 模块类
+     * @returns 模块实例
+     */
+    get<T extends Class>(moduleClass: T): InstanceType<T>;
+    /**
+     * 获取已注册的模块列表
+     */
+    getModules(): ModuleMetadata<Record<string, any>>[];
+    /**
+     * 获取实际使用的端口
+     */
+    getPort(): number | null;
+    /**
+     * 确保引擎已初始化（模块和处理器已加载）
+     * 如果引擎未启动，则执行必要的初始化步骤
+     */
+    private ensureInitialized;
+    /**
+     * 获取模块处理器方法（不启动 HTTP 服务器）
+     * 适用于测试场景，可以完整执行中间件和处理逻辑
+     *
+     * 返回一个已绑定模块和方法名的调用函数，调用时只需要传递方法参数
+     * 类型推导：自动推导方法参数类型和返回值类型（无需显式指定泛型参数）
+     *
+     * @param moduleClass 模块类
+     * @param methodName 方法名（handler 名称）
+     * @returns 调用函数，只需要传递方法参数
+     *
+     * @example
+     * ```typescript
+     * @Module("users")
+     * class UserService {
+     *   @Action({ params: [z.string(), z.number()] })
+     *   add(a: string, b: number): { result: number } {
+     *     return { result: Number(a) + b };
+     *   }
+     *
+     *   @Action({ params: [z.string()] })
+     *   getUser(id: string): Promise<{ id: string; name: string }> {
+     *     return Promise.resolve({ id, name: "Alice" });
+     *   }
+     * }
+     *
+     * // 获取 handler 并调用（类型自动推导，无需显式指定泛型）
+     * const addHandler = engine.handler(UserService, "add");
+     * const result1 = await addHandler("10", 20);
+     * // result1 的类型是 { result: number }
+     *
+     * // 也可以链式调用
+     * const result2 = await engine.handler(UserService, "getUser")("123");
+     * // result2 的类型是 { id: string; name: string }（自动解包 Promise）
+     * ```
+     */
+    handler<T extends Class, M extends keyof InstanceType<T> & string>(moduleClass: T, methodName: M): (...args: InstanceType<T>[M] extends (...args: infer P) => any ? P : never) => Promise<InstanceType<T>[M] extends (...args: any[]) => infer R ? R extends Promise<infer U> ? U : R : never>;
+    /**
+     * 使用 Hono 的 request 方法调用路由处理器（不启动 HTTP 服务器）
+     * 适用于测试场景，可以完整执行中间件和处理逻辑
+     *
+     * @param input Request 对象、URL 字符串或相对路径
+     * @param init RequestInit 选项（当 input 是字符串时使用）
+     * @returns Response 对象
+     *
+     * @example
+     * ```typescript
+     * // 使用相对路径
+     * const response = await engine.request("/api/users/123");
+     *
+     * // 使用完整 URL
+     * const response = await engine.request("http://localhost/api/users/123");
+     *
+     * // 使用 Request 对象
+     * const request = new Request("http://localhost/api/users/123", {
+     *   method: "POST",
+     *   headers: { "Content-Type": "application/json" },
+     *   body: JSON.stringify({ name: "Alice" }),
+     * });
+     * const response = await engine.request(request);
+     * ```
+     */
+    request(input: RequestInit | URL | string, init?: RequestInit): Promise<Response>;
+}
+
+/**
+ * 核心类型定义
+ */
+
+type Class = new (...args: any[]) => any;
+/**
+ * 插件Module配置Schema（运行时+类型双维度）
+ */
+interface PluginModuleOptionsSchema<T = Record<string, any>> {
+    _type: T;
+    validate?: (options: T) => boolean | string;
+}
+/**
+ * 插件优先级
+ * 数值越小，优先级越高（越先执行）
+ * 引擎会自动按优先级排序，用户无需关心注册顺序
+ */
+declare enum PluginPriority {
+    /**
+     * 系统级优先级：系统核心功能插件（优雅停机等）
+     * 最高优先级，应该最先执行
+     */
+    SYSTEM = 50,
+    /**
+     * 最高优先级：安全相关插件（限流、认证等）
+     * 应该最先执行，快速拒绝无效请求
+     */
+    SECURITY = 100,
+    /**
+     * 高优先级：日志、监控等插件
+     * 记录所有请求，包括被安全插件拒绝的
+     */
+    LOGGING = 200,
+    /**
+     * 中优先级：业务逻辑插件（数据转换等）
+     * 在安全和日志之后执行
+     */
+    BUSINESS = 300,
+    /**
+     * 低优先级：性能优化插件（缓存等）
+     * 在业务逻辑之后执行，避免重复计算
+     */
+    PERFORMANCE = 400,
+    /**
+     * 最低优先级：路由插件
+     * 必须最后执行，注册HTTP路由
+     */
+    ROUTE = 1000
+}
+/**
+ * 核心插件接口
+ */
+interface Plugin<TModuleOptions = Record<string, any>> {
+    name: string;
+    /**
+     * 插件优先级（可选）
+     * 如果不指定，默认为 PluginPriority.BUSINESS
+     * 引擎会自动按优先级排序，用户无需关心注册顺序
+     *
+     * 优先级规则：
+     * - 数值越小，优先级越高（越先执行）
+     * - 相同优先级按注册顺序执行
+     */
+    priority?: PluginPriority | number;
+    getModuleOptionsSchema?: () => PluginModuleOptionsSchema<TModuleOptions>;
+    onInit?: (engine: Microservice) => void;
+    onModuleLoad?: (modules: ModuleMetadata[]) => void;
+    onHandlerLoad?: (handlers: HandlerMetadata[]) => void;
+    onBeforeStart?: (engine: Microservice) => void;
+    onAfterStart?: (engine: Microservice) => void | Promise<void>;
+    onDestroy?: () => void | Promise<void>;
+}
+/**
+ * 引擎创建选项
+ */
+interface MicroserviceOptions {
+    name: string;
+    version: string;
+    hostname?: string;
+    prefix?: string;
+}
+/**
+ * Module装饰器类型（由引擎实例创建，自动推导类型）
+ * 使用最新的 Stage 3 装饰器标准
+ */
+type ModuleDecorator<TOptions = Record<string, any>> = (name: string, options?: TOptions) => (target: Class, context: ClassDecoratorContext) => void;
+/**
+ * 模块元数据
+ */
+interface ModuleMetadata<TOptions = Record<string, any>> {
+    name: string;
+    clazz: Class;
+    options: TOptions;
+}
+/**
+ * Handler包装函数类型
+ * 插件只需要提供这个函数，引擎自动管理包装链
+ *
+ * @param next 调用下一个包装层或原始方法
+ * @param instance 模块实例
+ * @param args 方法参数
+ * @returns 方法执行结果
+ */
+type HandlerWrapper = (next: () => Promise<any> | any, instance: any, ...args: any[]) => Promise<any> | any;
+/**
+ * Handler元数据（单组元数据）
+ * 提供简单的 wrap API，引擎自动管理包装链和执行顺序
+ */
+interface HandlerMetadata {
+    type: string;
+    options: Record<string, any>;
+    method: Function;
+    methodName: string;
+    module: Class;
+    /**
+     * 包装当前方法（引擎自动管理包装链）
+     *
+     * 插件只需要调用这个方法，引擎会自动：
+     * - 按插件优先级构建包装链
+     * - 确保 RoutePlugin 最后执行
+     * - 自动应用包装到原型
+     *
+     * @param wrapper 包装函数
+     *   - next: 调用下一个包装层或原始方法
+     *   - instance: 模块实例
+     *   - args: 方法参数
+     *
+     * @example
+     * ```typescript
+     * handler.wrap(async (next, instance, ...args) => {
+     *   // 前置逻辑
+     *   const result = await next();
+     *   // 后置逻辑
+     *   return result;
+     * });
+     * ```
+     */
+    wrap(wrapper: HandlerWrapper): void;
+}
+/**
+ * Stage 3 装饰器上下文类型
+ */
+type ClassDecoratorContext = {
+    kind: "class";
+    name: string | undefined;
+    addInitializer(initializer: () => void): void;
+};
+type ClassMethodDecoratorContext$1 = {
+    kind: "method";
+    name: string | symbol;
+    static: boolean;
+    private: boolean;
+    addInitializer(initializer: () => void): void;
+};
+
+/**
+ * 通用Handler装饰器（支持多应用）
+ * 使用最新的 Stage 3 装饰器标准
+ *
+ * @param config Handler配置
+ * @returns 方法装饰器
+ */
+declare function Handler<T = Record<string, any>>(config: {
+    type: string;
+    options?: T;
+}): (target: Function, context: ClassMethodDecoratorContext) => void;
+
+/**
+ * 核心异常类型定义
+ */
+declare class PluginNameRequiredError extends Error {
+    constructor(pluginName?: string);
+}
+declare class ModuleConfigValidationError extends Error {
+    constructor(moduleName: string, pluginName: string, message: string);
+}
+declare class DuplicateModuleError extends Error {
+    constructor(moduleName: string);
+}
+
+interface PreStartChecker {
+    name: string;
+    check: () => Promise<void> | void;
+    skip?: boolean;
+}
+declare function startCheck(checkers: PreStartChecker[], pass?: () => void | Promise<void>): Promise<void>;
+
+declare const BaseLayout: (props?: {
+    children?: any;
+    title?: string;
+    heads?: any;
+}) => hono_utils_html.HtmlEscapedString | Promise<hono_utils_html.HtmlEscapedString>;
+declare const HtmxLayout: (props?: {
+    children?: any;
+    title: string;
+    favicon?: any;
+}) => hono_utils_html.HtmlEscapedString | Promise<hono_utils_html.HtmlEscapedString>;
+
+/**
+ * 服务状态信息接口
+ * 基于 MicroserviceOptions，并添加运行时信息
+ */
+interface ServiceStatusInfo {
+    name: string;
+    version: string;
+    prefix?: string;
+    hostname?: string;
+    port?: number;
+    env?: string;
+    status?: string;
+}
+declare const ServiceInfoCards: ({ serviceInfo, }: {
+    serviceInfo: ServiceStatusInfo;
+}) => hono_jsx_jsx_dev_runtime.JSX.Element;
+declare const ServiceStatusPage: ({ serviceInfo, }: {
+    serviceInfo: ServiceStatusInfo;
+}) => hono_jsx_jsx_dev_runtime.JSX.Element;
+
+type HTTPMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS";
+/**
+ * Route装饰器配置选项
+ */
+interface RouteOptions {
+    /**
+     * HTTP方法（可选，默认为 GET）
+     * 如果未指定，则默认为 GET 方法
+     */
+    method?: HTTPMethod | HTTPMethod[];
+    /**
+     * 路由路径（支持单个路径或多个路径）
+     * 如果提供数组，将为每个路径注册相同的处理器
+     */
+    path: string | string[];
+    /**
+     * 路由专属中间件
+     */
+    middlewares?: MiddlewareHandler[];
+    /**
+     * 路由描述（用于文档和日志）
+     */
+    description?: string;
+    /**
+     * 请求参数校验规则
+     */
+    validate?: {
+        query?: Record<string, any>;
+        body?: Record<string, any>;
+        params?: Record<string, any>;
+    };
+    /**
+     * 响应配置
+     */
+    response?: {
+        status?: ContentfulStatusCode;
+        type?: "json" | "text" | "html";
+    };
+}
+/**
+ * RoutePlugin的Module配置
+ * 注意：配置直接平铺在 Module options 中，不使用 route 命名空间
+ * 插件作者需要确保字段名不与其他插件冲突
+ */
+interface RouteModuleOptions {
+    routePrefix?: string;
+    routeMiddlewares?: MiddlewareHandler[];
+}
+/**
+ * 错误转换函数
+ * 当路由处理器抛出异常时，可以自定义错误响应格式
+ * @param ctx Hono Context 对象
+ * @param error 捕获到的错误对象
+ * @param handler Handler 元数据，包含路由信息、方法名等
+ * @returns Response 对象或可序列化的值（会被自动转换为 Response）
+ */
+type ErrorTransformer = (ctx: Context, error: unknown, handler: HandlerMetadata) => Response | Promise<Response>;
+/**
+ * RoutePlugin 配置选项
+ */
+interface RoutePluginOptions {
+    /**
+     * 全局路径前缀（应用于所有路由）
+     * 路径拼接顺序：全局前缀 + 模块前缀 + 路由路径
+     * 例如：prefix="/api", routePrefix="/v1", path="/users" => "/api/v1/users"
+     */
+    prefix?: string;
+    /**
+     * 全局中间件（应用于所有路由）
+     * 执行顺序：全局中间件 -> 模块级中间件 -> 路由级中间件
+     * 常用于鉴权、日志等全局功能
+     */
+    globalMiddlewares?: MiddlewareHandler[];
+    /**
+     * 错误转换函数（可选）
+     * 当路由处理器抛出异常时，可以自定义错误响应格式
+     * 如果不提供，将使用默认的错误响应格式
+     */
+    errorTransformer?: ErrorTransformer;
+}
+
+/**
+ * Route装饰器（Handler的语法糖封装）
+ * 固定type="route"，简化HTTP路由标注
+ * 使用最新的 Stage 3 装饰器标准
+ *
+ * @example
+ * ```typescript
+ * @Route({ method: "GET", path: "/users" })
+ * async getUsers(ctx: Context) {
+ *   return ctx.json({ users: [] });
+ * }
+ *
+ * // 支持多个路径
+ * @Route({ path: ["/", "/home", "/dashboard"] })
+ * async homePage(ctx: Context) {
+ *   return <HomePage />;
+ * }
+ * ```
+ */
+declare function Route(options: RouteOptions): (target: Function, context: ClassMethodDecoratorContext) => void;
+/**
+ * Page装饰器（Route的别名，用于向后兼容）
+ * 专门用于页面路由，默认使用 GET 方法
+ *
+ * @example
+ * ```typescript
+ * @Page({ path: ["/", "/home"] })
+ * async adminPage(ctx: Context) {
+ *   return HtmxLayout({ title: "Admin", children: <AdminLayout /> });
+ * }
+ * ```
+ */
+declare function Page(options: RouteOptions): (target: Function, context: ClassMethodDecoratorContext) => void;
+
+/**
+ * RoutePlugin - 核心路由插件
+ * 负责解析type="route"的Handler元数据，注册HTTP路由到Hono实例
+ *
+ * @example
+ * ```typescript
+ * // 使用全局前缀和中间件
+ * const authMiddleware = async (ctx, next) => {
+ *   // 验证 token
+ *   await next();
+ * };
+ *
+ * const routePlugin = new RoutePlugin({
+ *   prefix: "/api", // 全局路径前缀，所有路由都会加上这个前缀
+ *   globalMiddlewares: [authMiddleware],
+ * });
+ * ```
+ */
+declare class RoutePlugin implements Plugin<RouteModuleOptions> {
+    readonly name = "route-plugin";
+    readonly priority = PluginPriority.ROUTE;
+    private engine;
+    private globalPrefix;
+    private globalMiddlewares;
+    private errorTransformer?;
+    /**
+     * 构造函数
+     * @param options 插件配置选项
+     */
+    constructor(options?: RoutePluginOptions);
+    /**
+     * 声明Module配置Schema（用于类型推导+运行时校验）
+     */
+    getModuleOptionsSchema(): PluginModuleOptionsSchema<RouteModuleOptions>;
+    /**
+     * 引擎初始化钩子：获取Hono实例
+     */
+    onInit(engine: Microservice): void;
+    /**
+     * Handler加载钩子：解析type="route"的Handler元数据，注册HTTP路由
+     */
+    onHandlerLoad(handlers: HandlerMetadata[]): void;
+}
+
+/**
+ * Action装饰器配置选项
+ */
+interface ActionOptions {
+    /**
+     * 动作描述
+     */
+    description?: string;
+    /**
+     * 参数校验 Schema（使用 zod）
+     * 数组顺序对应方法参数的顺序
+     */
+    params: z.ZodTypeAny[];
+    /**
+     * 返回值校验 Schema（使用 zod）
+     */
+    returns?: z.ZodTypeAny;
+    /**
+     * 是否流式返回（默认 false）
+     */
+    stream?: boolean;
+    /**
+     * 是否幂等（默认 false）
+     */
+    idempotence?: boolean;
+    /**
+     * 路由专属中间件
+     */
+    middlewares?: MiddlewareHandler[];
+}
+/**
+ * ActionPlugin的Module配置
+ */
+interface ActionModuleOptions {
+    /**
+     * 模块级路由中间件
+     */
+    actionMiddlewares?: MiddlewareHandler[];
+}
+
+/**
+ * ActionPlugin - 动作处理插件
+ * 提供基于下标的参数传递、zod 校验和自动参数注入
+ */
+declare class ActionPlugin implements Plugin<ActionModuleOptions> {
+    readonly name = "action-plugin";
+    readonly priority = PluginPriority.ROUTE;
+    private engine;
+    /**
+     * 声明Module配置Schema（用于类型推导+运行时校验）
+     */
+    getModuleOptionsSchema(): PluginModuleOptionsSchema<ActionModuleOptions>;
+    /**
+     * 引擎初始化钩子：获取Hono实例
+     */
+    onInit(engine: Microservice): void;
+    /**
+     * Handler加载钩子：解析type="action"的Handler元数据，注册HTTP路由
+     */
+    onHandlerLoad(handlers: HandlerMetadata[]): void;
+}
+
+/**
+ * Action装饰器（Handler的语法糖封装）
+ * 固定type="action"，用于标注动作处理方法
+ */
+declare function Action(options: ActionOptions): (target: Function, context: ClassMethodDecoratorContext) => void;
+
+/**
+ * Cache装饰器配置选项
+ */
+interface CacheOptions {
+    /**
+     * 缓存失效时间（毫秒）
+     * 默认：60000 (1分钟)
+     */
+    ttl?: number;
+    /**
+     * 缓存键生成函数
+     * 函数签名应该和处理器方法一样，接收相同的参数
+     * 可以返回任意值，返回值会被 ejson 序列化后进行 hash 生成缓存键
+     * 如果不提供，将使用入参（args）进行相同的计算
+     *
+     * @example
+     * ```typescript
+     * @Cache({
+     *   key: (id: string, name: string) => ({ id, name }), // 返回对象
+     *   ttl: 5000
+     * })
+     * async getUser(id: string, name: string) {
+     *   return { id, name };
+     * }
+     * ```
+     */
+    key?: (...args: any[]) => any;
+    /**
+     * 是否启用缓存
+     * 默认：true
+     */
+    enabled?: boolean;
+}
+/**
+ * CachePlugin的Module配置
+ * 注意：配置直接平铺在 Module options 中
+ */
+interface CacheModuleOptions {
+    /**
+     * 默认缓存失效时间（毫秒）
+     * 默认：60000 (1分钟)
+     */
+    cacheDefaultTtl?: number;
+    /**
+     * 是否启用全局缓存
+     * 默认：true
+     */
+    cacheEnabled?: boolean;
+    /**
+     * 缓存清理间隔（毫秒）
+     * 默认：60000 (1分钟)
+     */
+    cacheCleanupInterval?: number;
+}
+/**
+ * 缓存项数据结构
+ */
+interface CacheItem<T = any> {
+    value: T;
+    expiresAt: number;
+    createdAt: number;
+}
+
+/**
+ * Cache Adapter 接口
+ * 定义缓存存储的抽象接口，支持不同的存储后端
+ */
+
+/**
+ * 缓存适配器接口
+ */
+interface CacheAdapter {
+    /**
+     * 获取缓存项
+     * @param key 缓存键
+     * @returns 缓存项，如果不存在或已过期则返回 null
+     */
+    get<T = any>(key: string): Promise<CacheItem<T> | null>;
+    /**
+     * 设置缓存项
+     * @param key 缓存键
+     * @param item 缓存项
+     */
+    set<T = any>(key: string, item: CacheItem<T>): Promise<void>;
+    /**
+     * 删除缓存项
+     * @param key 缓存键
+     * @returns 是否删除成功
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * 清空所有缓存
+     */
+    clear(): Promise<void>;
+    /**
+     * 获取所有缓存键（用于统计）
+     * @returns 缓存键数组（不包含过期项）
+     */
+    keys(): Promise<string[]>;
+    /**
+     * 清理所有过期项（高效批量清理）
+     * @returns 清理的过期项数量
+     */
+    cleanupExpired?(): Promise<number>;
+    /**
+     * 获取缓存统计信息
+     */
+    getStats(): Promise<{
+        size: number;
+        entries: Array<{
+            key: string;
+            expiresAt: number;
+            createdAt: number;
+        }>;
+    }>;
+}
+/**
+ * 内存缓存适配器
+ * 使用 Map 存储，适合单进程应用
+ *
+ * 注意：过期项会在以下情况被自动清理：
+ * 1. get() 时检查并删除过期项
+ * 2. keys() 和 getStats() 会过滤过期项
+ * 3. 建议通过 CachePlugin 的定期清理机制主动清理过期项
+ */
+declare class MemoryCacheAdapter implements CacheAdapter {
+    private cache;
+    get<T = any>(key: string): Promise<CacheItem<T> | null>;
+    set<T = any>(key: string, item: CacheItem<T>): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    keys(): Promise<string[]>;
+    /**
+     * 清理所有过期项（高效批量清理）
+     * 这个方法比通过 keys() + get() + delete() 更高效
+     */
+    cleanupExpired(): Promise<number>;
+    getStats(): Promise<{
+        size: number;
+        entries: Array<{
+            key: string;
+            expiresAt: number;
+            createdAt: number;
+        }>;
+    }>;
+}
+/**
+ * Redis 缓存适配器配置
+ */
+interface RedisCacheAdapterOptions {
+    /**
+     * Redis 客户端实例（需要实现基本的 get/set/del/keys 方法）
+     * 可以是 ioredis、node-redis 等
+     */
+    client: {
+        get(key: string): Promise<string | null>;
+        set(key: string, value: string, expiryMode?: string, time?: number): Promise<string | null>;
+        del(key: string): Promise<number>;
+        keys(pattern: string): Promise<string[]>;
+    };
+    /**
+     * 键前缀，用于区分不同应用的缓存
+     * 默认：'cache:'
+     */
+    keyPrefix?: string;
+}
+/**
+ * Redis 缓存适配器
+ * 使用 Redis 作为存储后端，适合分布式应用
+ *
+ * 注意：Redis 本身支持 TTL（Time To Live），过期键会自动删除，
+ * 因此不需要手动清理过期项。当使用 SET key value EX seconds 时，
+ * Redis 会在过期后自动删除键。
+ */
+declare class RedisCacheAdapter implements CacheAdapter {
+    private client;
+    private keyPrefix;
+    constructor(options: RedisCacheAdapterOptions);
+    private getKey;
+    get<T = any>(key: string): Promise<CacheItem<T> | null>;
+    set<T = any>(key: string, item: CacheItem<T>): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    keys(): Promise<string[]>;
+    /**
+     * 清理所有过期项
+     *
+     * 注意：Redis 本身支持自动过期（通过 SET key value EX seconds），
+     * 过期键会被 Redis 自动删除。但在某些情况下（如测试环境、某些 Redis 客户端），
+     * 可能需要手动清理。此方法会检查并清理：
+     * 1. 已过期但尚未被 Redis 删除的键（双重保险）
+     * 2. JSON 解析失败的数据
+     */
+    cleanupExpired(): Promise<number>;
+    getStats(): Promise<{
+        size: number;
+        entries: Array<{
+            key: string;
+            expiresAt: number;
+            createdAt: number;
+        }>;
+    }>;
+}
+
+/**
+ * CachePlugin - 缓存插件
+ * 负责为标记了 @Cache 装饰器的方法提供缓存功能
+ *
+ * @example
+ * ```ts
+ * // 使用内存缓存（默认）
+ * const cachePlugin = new CachePlugin();
+ *
+ * // 使用自定义适配器
+ * const cachePlugin = new CachePlugin(new MemoryCacheAdapter());
+ *
+ * // 使用 Redis 适配器
+ * import { RedisCacheAdapter } from "./adapter";
+ * const cachePlugin = new CachePlugin(new RedisCacheAdapter({ client: redisClient }));
+ * ```
+ */
+declare class CachePlugin implements Plugin<CacheModuleOptions> {
+    readonly name = "cache-plugin";
+    readonly priority = PluginPriority.PERFORMANCE;
+    private adapter;
+    private cleanupTimer;
+    private engine;
+    private defaultTtl;
+    private cacheEnabled;
+    private cleanupInterval;
+    /**
+     * 构造函数
+     * @param adapter 缓存适配器，如果不提供则使用默认的内存缓存适配器
+     */
+    constructor(adapter?: CacheAdapter);
+    /**
+     * 声明Module配置Schema
+     */
+    getModuleOptionsSchema(): PluginModuleOptionsSchema<CacheModuleOptions>;
+    /**
+     * 引擎初始化前钩子
+     */
+    onInit(engine: Microservice): void;
+    /**
+     * Handler加载后钩子
+     * 拦截带有 type="cache" 的 Handler，包装原始方法实现缓存逻辑
+     */
+    onHandlerLoad(handlers: HandlerMetadata[]): void;
+    /**
+     * 引擎启动前钩子
+     */
+    onBeforeStart(engine: Microservice): void;
+    /**
+     * 引擎停止时钩子
+     */
+    onDestroy(): Promise<void>;
+    /**
+     * 生成缓存键
+     * @param moduleName 模块名
+     * @param methodName 方法名
+     * @param keyFunction 可选的 key 函数
+     * @param args 方法参数
+     * @returns 缓存键（格式：模块名:方法名:hash）
+     */
+    private generateCacheKey;
+    /**
+     * 清理过期缓存
+     */
+    private cleanup;
+    /**
+     * 获取缓存统计信息
+     */
+    getStats(): Promise<{
+        size: number;
+        entries: Array<{
+            key: string;
+            expiresAt: number;
+            createdAt: number;
+        }>;
+    }>;
+    /**
+     * 清空所有缓存
+     */
+    clear(): Promise<void>;
+    /**
+     * 删除指定的缓存项
+     */
+    delete(key: string): Promise<boolean>;
+}
+
+/**
+ * Cache装饰器
+ * 用于标记需要缓存的方法
+ *
+ * @example
+ * ```typescript
+ * @Cache({ ttl: 5000 })
+ * async getUser(id: number) {
+ *   return { id, name: "John" };
+ * }
+ * ```
+ */
+declare function Cache(options?: CacheOptions): (target: Function, context: ClassMethodDecoratorContext) => void;
+
+/**
+ * 优雅停机插件配置选项
+ */
+interface GracefulShutdownPluginOptions {
+    /**
+     * 停机超时时间（毫秒）
+     * 默认：10分钟（600000ms）
+     */
+    shutdownTimeout?: number;
+    /**
+     * 是否启用优雅停机
+     * 默认：true
+     */
+    enabled?: boolean;
+}
+
+/**
+ * 优雅停机插件
+ *
+ * 功能：
+ * 1. 追踪所有处理器的执行状态（包括 Action、Route、Schedule 等）
+ * 2. 监听系统停机信号（SIGINT、SIGTERM 等）
+ * 3. 收到信号后，等待所有正在执行的处理器完成
+ * 4. 如果超时或所有处理完成，执行优雅停机
+ *
+ * @example
+ * ```typescript
+ * // 使用默认配置（10分钟超时）
+ * const gracefulShutdownPlugin = new GracefulShutdownPlugin();
+ *
+ * // 自定义超时时间（5分钟）
+ * const gracefulShutdownPlugin = new GracefulShutdownPlugin({
+ *   shutdownTimeout: 5 * 60 * 1000, // 5分钟
+ * });
+ * ```
+ */
+declare class GracefulShutdownPlugin implements Plugin {
+    readonly name = "graceful-shutdown-plugin";
+    readonly priority = PluginPriority.SYSTEM;
+    private engine;
+    private options;
+    private activeHandlers;
+    private isShuttingDown;
+    private shutdownTimer;
+    private signalListeners;
+    constructor(options?: GracefulShutdownPluginOptions);
+    /**
+     * 引擎初始化钩子
+     */
+    onInit(engine: Microservice): void;
+    /**
+     * Handler加载钩子：拦截所有处理器，追踪执行状态
+     */
+    onHandlerLoad(handlers: HandlerMetadata[]): void;
+    /**
+     * 引擎启动后钩子：注册系统信号监听器
+     */
+    onAfterStart(engine: Microservice): Promise<void>;
+    /**
+     * 注册系统信号监听器
+     */
+    private registerSignalHandlers;
+    /**
+     * 增加活跃处理器计数
+     */
+    private incrementActiveHandlers;
+    /**
+     * 减少活跃处理器计数
+     */
+    private decrementActiveHandlers;
+    /**
+     * 启动优雅停机流程
+     */
+    private initiateShutdown;
+    /**
+     * 完成停机流程
+     */
+    private completeShutdown;
+    /**
+     * 清理信号监听器
+     */
+    private cleanupSignalHandlers;
+    /**
+     * 引擎销毁钩子：清理资源
+     */
+    onDestroy(): Promise<void>;
+    /**
+     * 获取当前活跃处理器数量（用于测试和监控）
+     */
+    getActiveHandlersCount(): number;
+    /**
+     * 检查是否正在停机（用于测试和监控）
+     */
+    isShuttingDownNow(): boolean;
+}
+
+/**
+ * 调度模式
+ */
+declare enum ScheduleMode {
+    /**
+     * 固定频率模式：无论任务执行时间多长，都会按照固定间隔执行
+     * 例如：每 5 秒执行一次，即使上次任务执行了 10 秒
+     */
+    FIXED_RATE = "FIXED_RATE",
+    /**
+     * 固定延迟模式：任务执行完成后，等待固定间隔再执行下一次
+     * 例如：任务执行了 10 秒，间隔 5 秒，则下次执行在 15 秒后
+     */
+    FIXED_DELAY = "FIXED_DELAY"
+}
+/**
+ * 调度选项
+ */
+interface ScheduleOptions {
+    /**
+     * 执行间隔（毫秒）
+     */
+    interval: number;
+    /**
+     * 调度模式（默认 FIXED_RATE）
+     */
+    mode?: ScheduleMode;
+}
+/**
+ * 调度元数据
+ */
+interface ScheduleMetadata {
+    /**
+     * 方法名称
+     */
+    name: string;
+    /**
+     * 执行间隔（毫秒）
+     */
+    interval: number;
+    /**
+     * 调度模式
+     */
+    mode: ScheduleMode;
+}
+/**
+ * SchedulePlugin 配置选项
+ */
+interface SchedulePluginOptions {
+    /**
+     * Etcd3 客户端实例
+     * 如果未提供且 useMockEtcd 为 false，插件将不会启动调度任务
+     */
+    etcdClient?: Etcd3$1;
+    /**
+     * 是否使用 Mock Etcd（用于测试和本地开发）
+     * 当设置为 true 时，将使用内置的 MockEtcd3，始终选举自己作为 leader
+     * 这样可以在没有真实 etcd 的情况下运行调度任务
+     *
+     * @default false
+     */
+    useMockEtcd?: boolean;
+}
+/**
+ * Etcd3 类型定义（避免直接依赖 etcd3 包）
+ * 这些类型定义与 etcd3@1.1.2 的实际类型兼容
+ */
+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 | 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): Campaign;
+    on(event: "elected", callback: () => void): Campaign;
+    resign(): Promise<void>;
+}
+
+/**
+ * Schedule装饰器
+ * 用于标记需要定时调度的方法
+ *
+ * @example
+ * ```typescript
+ * @Schedule({ interval: 5000, mode: ScheduleMode.FIXED_RATE })
+ * async syncData() {
+ *   // 定时执行的任务
+ * }
+ * ```
+ */
+declare function Schedule(options: ScheduleOptions): (target: Function, context: ClassMethodDecoratorContext) => void;
+
+/**
+ * SchedulePlugin - 调度任务插件
+ * 使用 etcd 选举机制实现分布式定时任务，确保多个实例中只有一个执行任务
+ */
+declare class SchedulePlugin implements Plugin {
+    readonly name = "schedule-plugin";
+    readonly priority = PluginPriority.BUSINESS;
+    private engine;
+    private scheduler;
+    private etcdClient;
+    private scheduleHandlers;
+    private useMockEtcd;
+    constructor(options?: SchedulePluginOptions);
+    /**
+     * 引擎初始化钩子
+     */
+    onInit(engine: Microservice): void;
+    /**
+     * Handler加载钩子：收集所有调度任务
+     */
+    onHandlerLoad(handlers: HandlerMetadata[]): void;
+    /**
+     * 引擎启动后钩子：启动所有调度任务
+     */
+    onAfterStart(engine: Microservice): Promise<void>;
+    /**
+     * 引擎销毁钩子：停止所有调度任务
+     */
+    onDestroy(): Promise<void>;
+}
+
+/**
+ * 调度器类
+ * 负责管理基于 etcd 选举的分布式定时任务
+ */
+declare class Scheduler {
+    private etcdClient;
+    private campaigns;
+    private timers;
+    private isLeader;
+    constructor(etcdClient: Etcd3$1);
+    /**
+     * 启动调度任务
+     */
+    startSchedule(serviceId: string, moduleName: string, methodName: string, electionKey: string, metadata: ScheduleMetadata, method: Function): Promise<void>;
+    /**
+     * 启动定时器
+     */
+    private startTimer;
+    /**
+     * 停止定时器
+     */
+    private stopTimer;
+    /**
+     * 停止所有调度任务
+     */
+    stop(): Promise<void>;
+}
+
+/**
+ * Mock Etcd3 客户端
+ * 用于测试和本地开发，模拟 etcd 的选举机制
+ * 始终选举第一个参与选举的候选者作为 leader
+ */
+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;
+}
+/**
+ * Mock Election
+ */
+declare class MockElection implements Election {
+    private key;
+    private observers;
+    private campaigns;
+    private currentLeader;
+    constructor(key: string);
+    observe(): Promise<Observer>;
+    campaign(candidate: string): Campaign;
+    setLeader(leader: string): void;
+    getCurrentLeader(): string | null;
+}
+
+/**
+ * ClientCodePlugin 配置选项
+ */
+interface ClientCodePluginOptions {
+    /**
+     * 客户端代码保存路径（可选）
+     * 如果设置，将在生成代码后自动保存到该路径
+     * 通常用于开发阶段自动生成客户端代码用于调试或测试
+     *
+     * @example
+     * ```ts
+     * new ClientCodePlugin({ clientSavePath: "./generated/client.ts" })
+     * ```
+     */
+    clientSavePath?: string;
+}
+/**
+ * ClientCodePlugin - 客户端代码生成插件
+ * 收集所有 Action handlers，生成类型化的客户端代码，
+ * 并提供 /client.ts 路由供远程下载
+ */
+declare class ClientCodePlugin implements Plugin {
+    readonly name = "client-code-plugin";
+    readonly priority = PluginPriority.ROUTE;
+    private engine;
+    private actionHandlers;
+    private generatedCode;
+    private readonly clientSavePath?;
+    constructor(options?: ClientCodePluginOptions);
+    /**
+     * 引擎初始化钩子
+     */
+    onInit(engine: Microservice): void;
+    /**
+     * Handler加载钩子：收集所有 Action handlers
+     */
+    onHandlerLoad(handlers: HandlerMetadata[]): void;
+    /**
+     * 引擎启动后钩子：注册客户端代码下载路由
+     */
+    onAfterStart(engine: Microservice): Promise<void>;
+    /**
+     * 生成客户端代码
+     */
+    private generateCode;
+    /**
+     * 保存代码到文件
+     */
+    private saveCodeToFile;
+}
+
+/**
+ * Action 信息（用于生成客户端代码）
+ */
+interface ActionInfo {
+    /**
+     * 动作描述
+     */
+    description?: string;
+    /**
+     * 参数校验 Schema（使用 zod）
+     */
+    params: z.ZodTypeAny[];
+    /**
+     * 返回值校验 Schema（使用 zod）
+     */
+    returns?: z.ZodTypeAny;
+    /**
+     * 是否流式返回（默认 false）
+     */
+    stream?: boolean;
+    /**
+     * 是否幂等（默认 false）
+     */
+    idempotence?: boolean;
+    /**
+     * 参数名称数组（从方法定义中提取）
+     */
+    paramNames?: string[];
+}
+/**
+ * 模块信息（用于生成客户端代码）
+ */
+interface ModuleInfo {
+    /**
+     * 模块名称
+     */
+    name: string;
+    /**
+     * 模块的所有 actions
+     */
+    actions: Record<string, ActionInfo>;
+}
+
+/**
+ * 获取 Zod 类型的 TypeScript 类型字符串
+ */
+declare function getZodTypeString(schema: z.ZodType<any>, defaultOptional?: boolean): string;
+/**
+ * 生成客户端代码
+ * @param modules 模块信息
+ * @returns 生成的客户端代码
+ */
+declare function generateClientCode(modules: Record<string, ModuleInfo>): Promise<string>;
+
+/**
+ * 将 HandlerMetadata 数组转换为 ModuleInfo 格式
+ * @param handlers Action handlers
+ * @returns 模块信息映射
+ */
+declare function convertHandlersToModuleInfo(handlers: HandlerMetadata[]): Record<string, ModuleInfo>;
+/**
+ * 从引擎获取模块信息并转换为 ModuleInfo 格式
+ * @param handlers Action handlers
+ * @param getModuleMetadata 获取模块元数据的函数
+ * @returns 模块信息映射
+ */
+declare function convertHandlersToModuleInfoWithMetadata(handlers: HandlerMetadata[], getModuleMetadata: (moduleClass: any) => {
+    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>;
+}
+
+/**
+ * 从插件数组中提取聚合的配置类型
+ */
+type ExtractPluginOptions<T extends readonly Plugin<any>[]> = T extends readonly [infer P1, ...infer Rest] ? P1 extends Plugin<infer T1> ? Rest extends readonly Plugin<any>[] ? T1 & ExtractPluginOptions<Rest> : T1 : ExtractPluginOptions<Rest extends readonly Plugin<any>[] ? Rest : []> : Record<string, any>;
+/**
+ * Factory - 创建类型化的引擎实例
+ *
+ * 注意：所有插件都必须显式注册，不会自动包含任何默认插件
+ */
+declare class Factory {
+    /**
+     * 创建类型化的引擎工厂
+     *
+     * @param plugins 插件列表（必须显式提供所有需要的插件）
+     * @returns 包含类型化的 Module 装饰器和 Microservice 类的对象
+     */
+    static create<TPlugins extends readonly Plugin<any>[]>(...plugins: TPlugins): {
+        Module: ModuleDecorator<ExtractPluginOptions<TPlugins>>;
+        Microservice: new (options: MicroserviceOptions) => Microservice<ExtractPluginOptions<TPlugins>>;
+    };
+}
+
+/**
+ * 测试辅助模块
+ * 提供常用的测试工具函数和类型，简化测试代码编写
+ */
+
+/**
+ * 默认测试配置
+ */
+declare const DEFAULT_TEST_OPTIONS: {
+    readonly name: "test-service";
+    readonly version: "1.0.0";
+};
+/**
+ * 创建测试引擎
+ *
+ * @example
+ * ```ts
+ * // 只传插件
+ * const { engine, Module } = Testing.createTestEngine({
+ *   plugins: [new CachePlugin()]
+ * });
+ *
+ * // 传插件和 options
+ * const { engine, Module } = Testing.createTestEngine({
+ *   plugins: [new CachePlugin()],
+ *   options: { prefix: "/api" }
+ * });
+ * ```
+ */
+declare function createTestEngine<TPlugins extends readonly Plugin<any>[]>(config: {
+    plugins: TPlugins;
+    options?: Partial<MicroserviceOptions>;
+}): ReturnType<typeof Factory.create<TPlugins>> & {
+    engine: InstanceType<ReturnType<typeof Factory.create<TPlugins>>["Microservice"]>;
+};
+/**
+ * 等待指定时间（用于异步测试）
+ *
+ * @param ms 等待的毫秒数
+ * @returns Promise
+ */
+declare function wait(ms: number): Promise<void>;
+/**
+ * 测试辅助工具命名空间
+ * 所有测试相关的工具函数都通过这个命名空间导出，避免命名冲突
+ */
+declare const Testing: {
+    readonly createTestEngine: typeof createTestEngine;
+    readonly DEFAULT_TEST_OPTIONS: {
+        readonly name: "test-service";
+        readonly version: "1.0.0";
+    };
+    readonly wait: typeof wait;
+};
+
+declare const logger: winston.Logger;
+
+/**
+ * Nebula ID Generator - 基于 nanoid 的 ID 生成器
+ *
+ * 使用自定义字符集（仅包含大小写字母和数字）生成唯一 ID
+ * 字符集：A-Z, a-z, 0-9 (共62个字符)
+ *
+ * @example
+ * ```typescript
+ * import { nebulaId } from "nebula-engine";
+ *
+ * // 生成默认长度（12）的 ID
+ * const id1 = nebulaId();
+ * console.log(id1); // 例如: "V1StGXR8IZ5j"
+ *
+ * // 生成指定长度的 ID
+ * const id2 = nebulaId(10);
+ * console.log(id2); // 例如: "V1StGXR8IZ"
+ * ```
+ */
+/**
+ * Nebula ID 字符集
+ * 仅包含大小写字母和数字（A-Z, a-z, 0-9），不包含下划线和横线
+ */
+declare const NEBULA_ID_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+/**
+ * 生成 Nebula ID
+ *
+ * @param length - ID 长度（默认 12
+ * @returns 生成的 ID 字符串
+ *
+ * @example
+ * ```typescript
+ * // 生成默认长度的 ID
+ * const id1 = nebulaId();
+ *
+ * // 生成指定长度的 ID
+ * const id2 = nebulaId(10);
+ * const id3 = nebulaId(32);
+ * ```
+ */
+declare function nebulaId(length?: number): string;
+
+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, NEBULA_ID_ALPHABET, 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, nebulaId, startCheck };