@onebots/core 0.5.0 → 1.0.0

package/lib/errors.js

@@ -0,0 +1,257 @@
+/**
+ * 错误处理和分类系统
+ * 提供统一的错误类型和处理机制
+ */
+/**
+ * 错误分类枚举
+ */
+export var ErrorCategory;
+(function (ErrorCategory) {
+    /** 网络相关错误 */
+    ErrorCategory["NETWORK"] = "NETWORK";
+    /** 配置相关错误 */
+    ErrorCategory["CONFIG"] = "CONFIG";
+    /** 运行时错误 */
+    ErrorCategory["RUNTIME"] = "RUNTIME";
+    /** 验证错误 */
+    ErrorCategory["VALIDATION"] = "VALIDATION";
+    /** 资源错误 */
+    ErrorCategory["RESOURCE"] = "RESOURCE";
+    /** 协议错误 */
+    ErrorCategory["PROTOCOL"] = "PROTOCOL";
+    /** 适配器错误 */
+    ErrorCategory["ADAPTER"] = "ADAPTER";
+    /** 未知错误 */
+    ErrorCategory["UNKNOWN"] = "UNKNOWN";
+})(ErrorCategory || (ErrorCategory = {}));
+/**
+ * 错误严重程度
+ */
+export var ErrorSeverity;
+(function (ErrorSeverity) {
+    /** 低 - 可以忽略或自动恢复 */
+    ErrorSeverity["LOW"] = "LOW";
+    /** 中 - 需要记录但可以继续运行 */
+    ErrorSeverity["MEDIUM"] = "MEDIUM";
+    /** 高 - 影响功能，需要处理 */
+    ErrorSeverity["HIGH"] = "HIGH";
+    /** 严重 - 可能导致服务停止 */
+    ErrorSeverity["CRITICAL"] = "CRITICAL";
+})(ErrorSeverity || (ErrorSeverity = {}));
+/**
+ * 基础错误类
+ */
+export class OneBotsError extends Error {
+    category;
+    severity;
+    code;
+    context;
+    timestamp;
+    cause;
+    constructor(message, options = {}) {
+        super(message);
+        this.name = 'OneBotsError';
+        this.category = options.category || ErrorCategory.UNKNOWN;
+        this.severity = options.severity || ErrorSeverity.MEDIUM;
+        this.code = options.code || 'UNKNOWN_ERROR';
+        this.context = options.context;
+        this.cause = options.cause;
+        this.timestamp = new Date();
+        // 保持错误堆栈
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, OneBotsError);
+        }
+    }
+    /**
+     * 转换为可序列化的对象
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            category: this.category,
+            severity: this.severity,
+            code: this.code,
+            context: this.context,
+            timestamp: this.timestamp.toISOString(),
+            stack: this.stack,
+            cause: this.cause ? {
+                message: this.cause.message,
+                stack: this.cause.stack,
+            } : undefined,
+        };
+    }
+    /**
+     * 转换为字符串
+     */
+    toString() {
+        return `[${this.category}:${this.code}] ${this.message}`;
+    }
+}
+/**
+ * 网络错误
+ */
+export class NetworkError extends OneBotsError {
+    constructor(message, options) {
+        super(message, {
+            category: ErrorCategory.NETWORK,
+            severity: ErrorSeverity.MEDIUM,
+            code: 'NETWORK_ERROR',
+            ...options,
+        });
+        this.name = 'NetworkError';
+    }
+}
+/**
+ * 配置错误
+ */
+export class ConfigError extends OneBotsError {
+    constructor(message, options) {
+        super(message, {
+            category: ErrorCategory.CONFIG,
+            severity: ErrorSeverity.HIGH,
+            code: 'CONFIG_ERROR',
+            ...options,
+        });
+        this.name = 'ConfigError';
+    }
+}
+/**
+ * 验证错误
+ */
+export class ValidationError extends OneBotsError {
+    constructor(message, options) {
+        super(message, {
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            code: 'VALIDATION_ERROR',
+            ...options,
+        });
+        this.name = 'ValidationError';
+    }
+}
+/**
+ * 资源错误
+ */
+export class ResourceError extends OneBotsError {
+    constructor(message, options) {
+        super(message, {
+            category: ErrorCategory.RESOURCE,
+            severity: ErrorSeverity.HIGH,
+            code: 'RESOURCE_ERROR',
+            ...options,
+        });
+        this.name = 'ResourceError';
+    }
+}
+/**
+ * 协议错误
+ */
+export class ProtocolError extends OneBotsError {
+    constructor(message, options) {
+        super(message, {
+            category: ErrorCategory.PROTOCOL,
+            severity: ErrorSeverity.MEDIUM,
+            code: 'PROTOCOL_ERROR',
+            ...options,
+        });
+        this.name = 'ProtocolError';
+    }
+}
+/**
+ * 适配器错误
+ */
+export class AdapterError extends OneBotsError {
+    constructor(message, options) {
+        super(message, {
+            category: ErrorCategory.ADAPTER,
+            severity: ErrorSeverity.HIGH,
+            code: 'ADAPTER_ERROR',
+            ...options,
+        });
+        this.name = 'AdapterError';
+    }
+}
+/**
+ * 运行时错误
+ */
+export class RuntimeError extends OneBotsError {
+    constructor(message, options) {
+        super(message, {
+            category: ErrorCategory.RUNTIME,
+            severity: ErrorSeverity.HIGH,
+            code: 'RUNTIME_ERROR',
+            ...options,
+        });
+        this.name = 'RuntimeError';
+    }
+}
+/**
+ * 错误处理工具函数
+ */
+export class ErrorHandler {
+    /**
+     * 包装错误，转换为 OneBotsError
+     */
+    static wrap(error, context) {
+        if (error instanceof OneBotsError) {
+            if (context) {
+                return new OneBotsError(error.message, {
+                    category: error.category,
+                    severity: error.severity,
+                    code: error.code,
+                    context: { ...error.context, ...context },
+                    cause: error.cause || error,
+                });
+            }
+            return error;
+        }
+        if (error instanceof Error) {
+            // 尝试从错误消息推断错误类型
+            const message = error.message.toLowerCase();
+            let category = ErrorCategory.UNKNOWN;
+            let code = 'UNKNOWN_ERROR';
+            if (message.includes('network') || message.includes('connection') || message.includes('timeout')) {
+                category = ErrorCategory.NETWORK;
+                code = 'NETWORK_ERROR';
+            }
+            else if (message.includes('config') || message.includes('configuration')) {
+                category = ErrorCategory.CONFIG;
+                code = 'CONFIG_ERROR';
+            }
+            else if (message.includes('validation') || message.includes('invalid')) {
+                category = ErrorCategory.VALIDATION;
+                code = 'VALIDATION_ERROR';
+            }
+            else if (message.includes('not found') || message.includes('missing')) {
+                category = ErrorCategory.RESOURCE;
+                code = 'RESOURCE_NOT_FOUND';
+            }
+            return new OneBotsError(error.message, {
+                category,
+                severity: ErrorSeverity.MEDIUM,
+                code,
+                context,
+                cause: error,
+            });
+        }
+        return new OneBotsError(String(error), {
+            category: ErrorCategory.UNKNOWN,
+            severity: ErrorSeverity.MEDIUM,
+            code: 'UNKNOWN_ERROR',
+            context,
+        });
+    }
+    /**
+     * 判断错误是否可恢复
+     */
+    static isRecoverable(error) {
+        return error.severity === ErrorSeverity.LOW || error.severity === ErrorSeverity.MEDIUM;
+    }
+    /**
+     * 判断错误是否致命
+     */
+    static isFatal(error) {
+        return error.severity === ErrorSeverity.CRITICAL;
+    }
+}

package/lib/index.d.ts

@@ -1,13 +1,17 @@
-export type {} from 'koa-bodyparser';
 export * from "./account.js";
 export * from "./adapter.js";
 export * from "./base-app.js";
-export * from './router.js';
-export * from "./types.js";
 export * from "./router.js";
+export * from "./types.js";
 export * from "./utils.js";
 export * from "./message-utils.js";
 export * from "./protocol.js";
 export * from "./registry.js";
-export * from "./registry.js";
 export * from "./db.js";
+export * from "./errors.js";
+export * from "./logger.js";
+export * from "./config-validator.js";
+export * from "./di-container.js";
+export * from "./lifecycle.js";
+export * from "./retry.js";
+export * from "./rate-limiter.js";

package/lib/index.js

@@ -1,12 +1,20 @@
+// Core modules
 export * from "./account.js";
 export * from "./adapter.js";
 export * from "./base-app.js";
-export * from './router.js';
-export * from "./types.js";
 export * from "./router.js";
+export * from "./types.js";
 export * from "./utils.js";
 export * from "./message-utils.js";
 export * from "./protocol.js";
 export * from "./registry.js";
-export * from "./registry.js";
 export * from "./db.js";
+// Enhanced modules
+export * from "./errors.js";
+export * from "./logger.js";
+export * from "./config-validator.js";
+export * from "./di-container.js";
+export * from "./lifecycle.js";
+// Utilities
+export * from "./retry.js";
+export * from "./rate-limiter.js";

package/lib/lifecycle.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 生命周期管理
+ * 提供资源管理和优雅关闭机制
+ */
+import { EventEmitter } from 'events';
+import type { Dispose } from './types.js';
+export interface LifecycleHook {
+    /** 初始化钩子 */
+    onInit?(): void | Promise<void>;
+    /** 启动钩子 */
+    onStart?(): void | Promise<void>;
+    /** 停止钩子 */
+    onStop?(): void | Promise<void>;
+    /** 清理钩子 */
+    onCleanup?(): void | Promise<void>;
+}
+/**
+ * 生命周期管理器
+ */
+export declare class LifecycleManager extends EventEmitter {
+    private resources;
+    private hooks;
+    private isShuttingDown;
+    private shutdownTimeout;
+    /**
+     * 注册资源
+     */
+    register(name: string, dispose: Dispose): void;
+    /**
+     * 注销资源
+     */
+    unregister(name: string): boolean;
+    /**
+     * 注册生命周期钩子
+     */
+    addHook(hook: LifecycleHook): void;
+    /**
+     * 移除生命周期钩子
+     */
+    removeHook(hook: LifecycleHook): void;
+    /**
+     * 初始化所有钩子
+     */
+    init(): Promise<void>;
+    /**
+     * 启动所有钩子
+     */
+    start(): Promise<void>;
+    /**
+     * 停止所有钩子
+     */
+    stop(): Promise<void>;
+    /**
+     * 清理所有资源
+     */
+    cleanup(): Promise<void>;
+    /**
+     * 优雅关闭
+     */
+    gracefulShutdown(signal?: string, options?: {
+        exitOnTimeout?: boolean;
+    }): Promise<void>;
+    /**
+     * 设置关闭超时时间
+     */
+    setShutdownTimeout(timeout: number): void;
+    /**
+     * 获取资源数量
+     */
+    getResourceCount(): number;
+    /**
+     * 获取所有资源名称
+     */
+    getResourceNames(): string[];
+}

package/lib/lifecycle.js

@@ -0,0 +1,175 @@
+/**
+ * 生命周期管理
+ * 提供资源管理和优雅关闭机制
+ */
+import { EventEmitter } from 'events';
+import { ResourceError } from './errors.js';
+/**
+ * 生命周期管理器
+ */
+export class LifecycleManager extends EventEmitter {
+    resources = new Map();
+    hooks = [];
+    isShuttingDown = false;
+    shutdownTimeout = 30000; // 30秒超时
+    /**
+     * 注册资源
+     */
+    register(name, dispose) {
+        if (this.resources.has(name)) {
+            throw new ResourceError(`Resource ${name} already registered`);
+        }
+        this.resources.set(name, dispose);
+    }
+    /**
+     * 注销资源
+     */
+    unregister(name) {
+        return this.resources.delete(name);
+    }
+    /**
+     * 注册生命周期钩子
+     */
+    addHook(hook) {
+        this.hooks.push(hook);
+    }
+    /**
+     * 移除生命周期钩子
+     */
+    removeHook(hook) {
+        const index = this.hooks.indexOf(hook);
+        if (index !== -1) {
+            this.hooks.splice(index, 1);
+        }
+    }
+    /**
+     * 初始化所有钩子
+     */
+    async init() {
+        this.emit('beforeInit');
+        for (const hook of this.hooks) {
+            if (hook.onInit) {
+                await hook.onInit();
+            }
+        }
+        this.emit('afterInit');
+    }
+    /**
+     * 启动所有钩子
+     */
+    async start() {
+        this.emit('beforeStart');
+        for (const hook of this.hooks) {
+            if (hook.onStart) {
+                await hook.onStart();
+            }
+        }
+        this.emit('afterStart');
+    }
+    /**
+     * 停止所有钩子
+     */
+    async stop() {
+        this.emit('beforeStop');
+        for (const hook of this.hooks) {
+            if (hook.onStop) {
+                await hook.onStop();
+            }
+        }
+        this.emit('afterStop');
+    }
+    /**
+     * 清理所有资源
+     */
+    async cleanup() {
+        if (this.isShuttingDown) {
+            return;
+        }
+        this.isShuttingDown = true;
+        this.emit('beforeCleanup');
+        // 执行清理钩子
+        for (const hook of this.hooks) {
+            if (hook.onCleanup) {
+                try {
+                    await hook.onCleanup();
+                }
+                catch (error) {
+                    this.emit('cleanupError', { hook: 'onCleanup', error });
+                    // 继续执行，不抛出错误
+                }
+            }
+        }
+        // 清理所有资源
+        const cleanupPromises = [];
+        for (const [name, dispose] of this.resources.entries()) {
+            cleanupPromises.push((async () => {
+                try {
+                    const result = dispose();
+                    if (result instanceof Promise) {
+                        await result;
+                    }
+                }
+                catch (error) {
+                    this.emit('cleanupError', { name, error });
+                    // 继续执行，不抛出错误
+                }
+            })());
+        }
+        await Promise.all(cleanupPromises);
+        this.resources.clear();
+        this.hooks = [];
+        this.emit('afterCleanup');
+    }
+    /**
+     * 优雅关闭
+     */
+    async gracefulShutdown(signal, options) {
+        if (this.isShuttingDown) {
+            return;
+        }
+        this.emit('shutdown', signal);
+        // 设置超时
+        let timeout = null;
+        if (this.shutdownTimeout > 0) {
+            timeout = setTimeout(() => {
+                this.emit('shutdownTimeout');
+                if (options?.exitOnTimeout !== false) {
+                    process.exit(1);
+                }
+            }, this.shutdownTimeout);
+        }
+        try {
+            await this.stop();
+            await this.cleanup();
+            if (timeout) {
+                clearTimeout(timeout);
+            }
+            this.emit('shutdownComplete');
+        }
+        catch (error) {
+            if (timeout) {
+                clearTimeout(timeout);
+            }
+            this.emit('shutdownError', error);
+            throw error;
+        }
+    }
+    /**
+     * 设置关闭超时时间
+     */
+    setShutdownTimeout(timeout) {
+        this.shutdownTimeout = timeout;
+    }
+    /**
+     * 获取资源数量
+     */
+    getResourceCount() {
+        return this.resources.size;
+    }
+    /**
+     * 获取所有资源名称
+     */
+    getResourceNames() {
+        return Array.from(this.resources.keys());
+    }
+}

package/lib/logger.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 增强的日志系统
+ * 提供结构化日志、错误追踪和上下文信息
+ */
+import { OneBotsError } from './errors.js';
+import type { LogLevel } from './types.js';
+export interface LogContext {
+    [key: string]: any;
+}
+export interface LogEntry {
+    level: string;
+    message: string;
+    context?: LogContext;
+    error?: OneBotsError;
+    timestamp: Date;
+}
+/**
+ * 增强的 Logger 类
+ */
+export declare class Logger {
+    private logger;
+    private context;
+    constructor(name: string, level?: LogLevel);
+    /**
+     * 设置日志级别
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * 添加上下文信息
+     */
+    withContext(context: LogContext): Logger;
+    /**
+     * Trace 级别日志
+     */
+    trace(message: string, context?: LogContext): void;
+    /**
+     * Debug 级别日志
+     */
+    debug(message: string, context?: LogContext): void;
+    /**
+     * Info 级别日志
+     */
+    info(message: string, context?: LogContext): void;
+    /**
+     * Warn 级别日志
+     */
+    warn(message: string, context?: LogContext): void;
+    /**
+     * Error 级别日志
+     */
+    error(message: string | Error | OneBotsError, context?: LogContext): void;
+    /**
+     * Fatal 级别日志
+     */
+    fatal(message: string | Error | OneBotsError, context?: LogContext): void;
+    /**
+     * Mark 级别日志
+     */
+    mark(message: string, context?: LogContext): void;
+    /**
+     * 记录性能指标
+     */
+    performance(operation: string, duration: number, context?: LogContext): void;
+    /**
+     * 记录操作开始
+     */
+    start(operation: string, context?: LogContext): () => void;
+    /**
+     * 内部日志方法
+     */
+    private log;
+}
+/**
+ * 创建 Logger 实例
+ */
+export declare function createLogger(name: string, level?: LogLevel): Logger;