create-dp-koa 1.0.0

package/template/src/framework/utils/bootstrap.ts

@@ -0,0 +1,445 @@
+import Koa from 'koa';
+const app = new Koa();
+import dotenv from 'dotenv';
+import "reflect-metadata";
+import koaBody from 'koa-body';
+const moduleAlias = require("module-alias");//路径别名
+import path from 'path';
+import type { Server } from 'http';
+
+// 首先设置路径别名
+moduleAlias.addAliases({
+    "@src": path.join(process.cwd(), "./src"),
+});
+
+// import koaCros from "@koa/cors"
+const koaCros = require("@koa/cors")
+import { logger } from '@src/framework/utils/logger';
+import { isDebug } from '@src/framework/utils/function';
+import { router } from '@src/framework/utils/router';
+import { loggingMiddleware, businessLoggingMiddleware, databaseLoggingMiddleware } from '@src/middlewares/logging.middleware';
+
+// 开发/调试用 .env.development，生产用 .env.production（与 NODE_ENV 解耦：仅 `--env=debug` 走 development）
+const envFile = isDebug() ? '.env.development' : '.env.production';
+dotenv.config({ path: envFile });
+
+let beforeBootstraps: Function | null = null;
+let afterBootstraps: Function | null = null;
+let server: Server | null = null;
+
+/**
+ * 企业级错误分类枚举
+ */
+enum ErrorCategory {
+    VALIDATION = 'VALIDATION_ERROR',
+    AUTHENTICATION = 'AUTH_ERROR',
+    AUTHORIZATION = 'AUTHZ_ERROR',
+    BUSINESS_LOGIC = 'BUSINESS_ERROR',
+    DATABASE = 'DATABASE_ERROR',
+    EXTERNAL_SERVICE = 'EXTERNAL_SERVICE_ERROR',
+    SYSTEM = 'SYSTEM_ERROR',
+    NETWORK = 'NETWORK_ERROR',
+    UNKNOWN = 'UNKNOWN_ERROR'
+}
+
+/**
+ * 企业级错误码定义
+ */
+enum ErrorCode {
+    // 4xx 客户端错误
+    INVALID_REQUEST = 'E400001',
+    VALIDATION_FAILED = 'E400002',
+    UNAUTHORIZED = 'E401001',
+    FORBIDDEN = 'E403001',
+    NOT_FOUND = 'E404001',
+    METHOD_NOT_ALLOWED = 'E405001',
+    CONFLICT = 'E409001',
+    
+    // 5xx 服务器错误
+    INTERNAL_ERROR = 'E500001',
+    DATABASE_ERROR = 'E500002',
+    EXTERNAL_SERVICE_ERROR = 'E500003',
+    SERVICE_UNAVAILABLE = 'E503001',
+    TIMEOUT = 'E504001'
+}
+
+/**
+ * 企业级错误处理中间件
+ * 符合企业开发规范：错误分类、标准化错误码、安全防护、监控告警
+ */
+const frameworkErrorMiddleware = () => {
+    return async (ctx: any, next: Function) => {
+        try {
+            await next();
+        } catch (err) {
+            const error = err as any;
+            
+            // 1. 错误分类和标准化处理
+            const errorInfo = classifyAndStandardizeError(error);
+            
+            // 2. 设置响应状态码
+            ctx.status = errorInfo.statusCode;
+            
+            // 3. 安全信息过滤
+            const sanitizedError = sanitizeErrorForLogging(error, ctx);
+            
+            // 4. 记录结构化错误日志
+            logger.error('企业级异常处理', error as Error, {
+                error: {
+                    category: errorInfo.category,
+                    code: errorInfo.code,
+                    message: sanitizedError.message,
+                    stack: sanitizedError.stack,
+                    statusCode: errorInfo.statusCode,
+                    severity: errorInfo.severity
+                },
+                request: {
+                    method: ctx.method,
+                    url: sanitizeUrl(ctx.url),
+                    userAgent: ctx.headers['user-agent'],
+                    ip: ctx.ip,
+                    requestId: ctx.requestId || 'unknown',
+                    userId: ctx.userId || 'anonymous'
+                },
+                context: {
+                    timestamp: new Date().toISOString(),
+                    environment: isDebug() ? 'development' : 'production',
+                    service: 'dp-koa-framework',
+                    version: process.env.npm_package_version || '1.0.0'
+                }
+            });
+            
+            // 5. 错误监控和告警（严重错误）
+            if (errorInfo.severity === 'critical' || errorInfo.severity === 'high') {
+                triggerErrorAlert(errorInfo, sanitizedError, ctx);
+            }
+            
+            // 6. 标准化错误响应
+            ctx.body = buildStandardErrorResponse(errorInfo, ctx);
+            
+            // 7. 设置安全响应头
+            setSecurityHeaders(ctx);
+        }
+    };
+};
+
+/**
+ * 错误分类和标准化处理
+ */
+function classifyAndStandardizeError(error: any): {
+    category: ErrorCategory;
+    code: ErrorCode;
+    statusCode: number;
+    severity: 'low' | 'medium' | 'high' | 'critical';
+    message: string;
+} {
+    // 根据错误类型进行分类
+    if (error.name === 'ValidationError' || error.name === 'CastError') {
+        return {
+            category: ErrorCategory.VALIDATION,
+            code: ErrorCode.VALIDATION_FAILED,
+            statusCode: 400,
+            severity: 'low',
+            message: '请求参数验证失败'
+        };
+    }
+    
+    if (error.name === 'UnauthorizedError' || error.status === 401) {
+        return {
+            category: ErrorCategory.AUTHENTICATION,
+            code: ErrorCode.UNAUTHORIZED,
+            statusCode: 401,
+            severity: 'medium',
+            message: '身份验证失败'
+        };
+    }
+    
+    if (error.name === 'ForbiddenError' || error.status === 403) {
+        return {
+            category: ErrorCategory.AUTHORIZATION,
+            code: ErrorCode.FORBIDDEN,
+            statusCode: 403,
+            severity: 'medium',
+            message: '访问权限不足'
+        };
+    }
+    
+    if (error.name === 'NotFoundError' || error.status === 404) {
+        return {
+            category: ErrorCategory.BUSINESS_LOGIC,
+            code: ErrorCode.NOT_FOUND,
+            statusCode: 404,
+            severity: 'low',
+            message: '请求的资源不存在'
+        };
+    }
+    
+    if (error.code && error.code.startsWith('ER_')) {
+        return {
+            category: ErrorCategory.DATABASE,
+            code: ErrorCode.DATABASE_ERROR,
+            statusCode: 500,
+            severity: 'high',
+            message: '数据库操作失败'
+        };
+    }
+    
+    if (error.code === 'ECONNREFUSED' || error.code === 'ETIMEDOUT') {
+        return {
+            category: ErrorCategory.NETWORK,
+            code: ErrorCode.EXTERNAL_SERVICE_ERROR,
+            statusCode: 503,
+            severity: 'high',
+            message: '外部服务不可用'
+        };
+    }
+    
+    // 默认系统错误
+    return {
+        category: ErrorCategory.SYSTEM,
+        code: ErrorCode.INTERNAL_ERROR,
+        statusCode: error.status || error.statusCode || 500,
+        severity: error.status >= 500 ? 'critical' : 'medium',
+        message: error.message || '系统内部错误'
+    };
+}
+
+/**
+ * 安全信息过滤
+ */
+function sanitizeErrorForLogging(error: any, ctx: any): any {
+    const sensitiveFields = ['password', 'token', 'secret', 'key', 'auth', 'credential'];
+    
+    const sanitize = (obj: any): any => {
+        if (typeof obj !== 'object' || obj === null) return obj;
+        
+        const sanitized = { ...obj };
+        for (const [key, value] of Object.entries(sanitized)) {
+            if (sensitiveFields.some(field => key.toLowerCase().includes(field))) {
+                sanitized[key] = '***REDACTED***';
+            } else if (typeof value === 'object') {
+                sanitized[key] = sanitize(value);
+            }
+        }
+        return sanitized;
+    };
+    
+    return {
+        message: error.message || 'Unknown error',
+        stack: isDebug() ? error.stack : undefined,
+        ...sanitize(error)
+    };
+}
+
+/**
+ * URL 安全过滤
+ */
+function sanitizeUrl(url: string): string {
+    // 移除查询参数中的敏感信息
+    try {
+        // 如果URL是相对路径，则直接处理查询参数
+        if (!url.startsWith('http://') && !url.startsWith('https://')) {
+            // 处理相对路径，如 /api/users?token=xxx
+            const [pathname, search] = url.split('?');
+            if (!search) return pathname;
+            
+            const params = new URLSearchParams(search);
+            const sensitiveParams = ['password', 'token', 'secret', 'key'];
+            
+            sensitiveParams.forEach(param => {
+                if (params.has(param)) {
+                    params.set(param, '***REDACTED***');
+                }
+            });
+            
+            return pathname + '?' + params.toString();
+        }
+        
+        // 处理完整URL
+        const urlObj = new URL(url);
+        const sensitiveParams = ['password', 'token', 'secret', 'key'];
+        
+        sensitiveParams.forEach(param => {
+            if (urlObj.searchParams.has(param)) {
+                urlObj.searchParams.set(param, '***REDACTED***');
+            }
+        });
+        
+        return urlObj.pathname + urlObj.search;
+    } catch {
+        // 如果URL解析失败，至少移除明显的敏感参数
+        return url.replace(/([?&])(password|token|secret|key)=[^&]*/gi, '$1$2=***REDACTED***');
+    }
+}
+
+/**
+ * 错误告警触发
+ */
+function triggerErrorAlert(errorInfo: any, error: any, ctx: any): void {
+    // 这里可以集成告警系统，如钉钉、企业微信、邮件等
+    logger.warn('触发错误告警', {
+        alert: {
+            level: errorInfo.severity,
+            category: errorInfo.category,
+            code: errorInfo.code,
+            message: errorInfo.message,
+            timestamp: new Date().toISOString()
+        },
+        request: {
+            method: ctx.method,
+            url: sanitizeUrl(ctx.url),
+            ip: ctx.ip,
+            requestId: ctx.requestId
+        }
+    });
+}
+
+/**
+ * 构建标准化错误响应
+ */
+function buildStandardErrorResponse(errorInfo: any, ctx: any): any {
+    const baseResponse = {
+        success: false,
+        error: {
+            code: errorInfo.code,
+            category: errorInfo.category,
+            message: errorInfo.message,
+            timestamp: new Date().toISOString(),
+            requestId: ctx.requestId || 'unknown'
+        }
+    };
+    
+    // 开发环境添加调试信息
+    if (isDebug()) {
+        return {
+            ...baseResponse,
+            debug: {
+                stack: errorInfo.stack,
+                originalError: errorInfo.originalError
+            }
+        };
+    }
+    
+    return baseResponse;
+}
+
+/**
+ * 设置安全响应头
+ */
+function setSecurityHeaders(ctx: any): void {
+    // 防止信息泄露
+    ctx.set('X-Content-Type-Options', 'nosniff');
+    ctx.set('X-Frame-Options', 'DENY');
+    ctx.set('X-XSS-Protection', '1; mode=block');
+    
+    // 移除可能泄露信息的头
+    ctx.remove('X-Powered-By');
+    ctx.remove('Server');
+}
+
+/**
+ * 启动应用
+ * @param fn 启动函数，该函数会在应用启动前执行，所以可以在该函数中执行耗时操作，比如数据库连接、日志初始化等。
+ * @param port 应用端口，默认为3000
+/**
+ * 启动前执行，用户可以在这里执行一些初始化操作，比如数据库连接、日志初始化等。
+ * 注意：该函数会在应用启动前执行，所以不要在该函数中执行耗时操作，否则会影响应用启动速度。
+ * 注意：该函数是异步函数，所以需要使用await关键字来等待执行完成。  
+ * @param fn 
+ */
+export const setBeforeBootstrap = async (fn: Function) => {
+    beforeBootstraps = fn;
+}
+
+/**
+ * 启动后执行，用户可以在这里执行一些初始化操作，比如数据库连接、日志初始化等。
+ * 注意：该函数会在应用启动后执行，所以可以在该函数中执行耗时操作，比如数据库连接、日志初始化等。
+ * 注意：该函数是异步函数，所以需要使用await关键字来等待执行完成。
+ * @param fn
+ */
+export const setAfterBootstrap = async (fn: Function) => {
+    afterBootstraps = fn;
+}
+
+
+export const bootstrap = async () => {
+    if (beforeBootstraps) {
+        await beforeBootstraps(app);
+    }
+
+    app.use(koaCros({
+        origin: '*', //允许所有域名访问
+        maxAge: 5,
+        credentials: true, //允许携带cookie
+        allowMethods: ['GET', 'POST', 'PUT', 'DELETE'], //允许的请求方法
+        allowHeaders: ['Content-Type', 'Authorization', 'Accept'], //允许的请求头
+    }));
+    
+    // 企业级日志中间件
+    app.use(loggingMiddleware());
+    app.use(businessLoggingMiddleware());
+    app.use(databaseLoggingMiddleware());
+    
+    // 框架层错误处理中间件
+    app.use(frameworkErrorMiddleware())
+    app.use(koaBody());
+    
+    // Swagger文档和UI（仅开发环境启用）
+    // if (isDebug()) {
+    //     app.use(swaggerJson);
+    //     app.use(swaggerMiddleware());
+    // }
+    
+    // 添加路由调试中间件
+    // app.use(async (ctx, next) => {
+    //     logger.info(`收到请求: ${ctx.method} ${ctx.path}`);
+    //     await next();
+    // });
+    
+    // 启用路由
+    app.use(router.routes()).use(router.allowedMethods());
+
+    // 启动应用
+    const port = Number(process.env.port) || 3000;
+    const host = process.env.host || '0.0.0.0';
+
+    await new Promise<void>((resolve, reject) => {
+        try {
+            server = app.listen(port, host, () => {
+                logger.info(`Server is running on ${host}:${port}`);
+                resolve();
+            })
+            server.on('error', (err) => reject(err));
+        } catch (error) {
+            reject(error)
+        }
+    })
+
+    if (afterBootstraps) {
+        await afterBootstraps(app);
+    }
+}
+
+// 导出app 对象
+export const App = app;
+
+/**
+ * 获取当前 HTTP Server（如果已启动）
+ */
+export const getServer = (): Server | null => server;
+
+/**
+ * 关闭 HTTP Server（幂等）
+ */
+export const closeServer = async (): Promise<void> => {
+    if (!server) return;
+    const s = server;
+    server = null;
+
+    await new Promise<void>((resolve, reject) => {
+        s.close((err?: Error) => {
+            if (err) return reject(err);
+            resolve();
+        });
+    });
+}

package/template/src/framework/utils/cache.ts

@@ -0,0 +1,269 @@
+import { logger } from "@src/framework/utils/logger";
+
+const NodeCache = require("node-cache");
+
+/**
+ * 缓存配置接口
+ */
+export interface CacheConfig {
+    /** 默认TTL时间（秒） */
+    stdTTL?: number;
+    /** 最大缓存条目数 */
+    maxKeys?: number;
+    /** 检查过期时间间隔（秒） */
+    checkperiod?: number;
+    /** 是否使用克隆模式 */
+    useClones?: boolean;
+    /** 是否删除过期键 */
+    deleteOnExpire?: boolean;
+}
+
+/**
+ * 默认缓存配置
+ * 统一管理所有缓存的默认参数，防止内存泄露
+ */
+const DEFAULT_CACHE_CONFIG: Required<CacheConfig> = {
+    stdTTL: 300, // 默认5分钟过期
+    maxKeys: 1000, // 最大1000个缓存条目
+    checkperiod: 120, // 每2分钟检查一次过期
+    useClones: false, // 不使用克隆，提高性能
+    deleteOnExpire: true // 自动删除过期键
+};
+
+/**
+ * 缓存类型枚举
+ */
+export enum CacheType {
+    /** 用户缓存 */
+    USER = 'user',
+    /** 控制器结果缓存 */
+    CONTROLLER = 'controller',
+    /** 会话缓存 */
+    SESSION = 'session',
+    /** 验证码缓存 */
+    CAPTCHA = 'captcha',
+    /** 临时缓存 */
+    TEMP = 'temp'
+}
+
+/**
+ * 不同类型缓存的特定配置
+ */
+const CACHE_TYPE_CONFIGS: Record<CacheType, Partial<CacheConfig>> = {
+    [CacheType.USER]: {
+        stdTTL: 1800, // 30分钟
+        maxKeys: 500
+    },
+    [CacheType.CONTROLLER]: {
+        stdTTL: 60, // 1分钟
+        maxKeys: 2000
+    },
+    [CacheType.SESSION]: {
+        stdTTL: 3600, // 1小时
+        maxKeys: 1000
+    },
+    [CacheType.CAPTCHA]: {
+        stdTTL: 300, // 5分钟
+        maxKeys: 100
+    },
+    [CacheType.TEMP]: {
+        stdTTL: 60, // 1分钟
+        maxKeys: 100
+    }
+};
+
+/**
+ * 缓存管理器类
+ */
+class CacheManager {
+    private caches: Map<string, any> = new Map();
+    private stats: Map<string, { hits: number; misses: number; keys: number }> = new Map();
+
+    /**
+     * 创建缓存实例
+     * @param name 缓存名称
+     * @param type 缓存类型
+     * @param customConfig 自定义配置
+     */
+    createCache(name: string, type: CacheType = CacheType.TEMP, customConfig?: Partial<CacheConfig>) {
+        if (this.caches.has(name)) {
+            logger.warn(`缓存 ${name} 已存在，返回现有实例`);
+            return this.caches.get(name);
+        }
+
+        // 合并配置
+        const typeConfig = CACHE_TYPE_CONFIGS[type] || {};
+        const finalConfig = { ...DEFAULT_CACHE_CONFIG, ...typeConfig, ...customConfig };
+
+        // 创建缓存实例
+        const cache = new NodeCache(finalConfig);
+        
+        // 添加统计信息
+        this.stats.set(name, { hits: 0, misses: 0, keys: 0 });
+
+        // 监听缓存事件
+        cache.on('set', (key: string, value: any) => {
+            const stats = this.stats.get(name);
+            if (stats) {
+                stats.keys = cache.keys().length;
+            }
+            logger.debug(`缓存 ${name} 设置键: ${key}`);
+        });
+
+        cache.on('del', (key: string, value: any) => {
+            const stats = this.stats.get(name);
+            if (stats) {
+                stats.keys = cache.keys().length;
+            }
+            logger.debug(`缓存 ${name} 删除键: ${key}`);
+        });
+
+        cache.on('expired', (key: string, value: any) => {
+            const stats = this.stats.get(name);
+            if (stats) {
+                stats.keys = cache.keys().length;
+            }
+            logger.debug(`缓存 ${name} 键过期: ${key}`);
+        });
+
+        // 包装get方法以添加统计
+        const originalGet = cache.get.bind(cache);
+        cache.get = (key: string) => {
+            const result = originalGet(key);
+            const stats = this.stats.get(name);
+            if (stats) {
+                if (result !== undefined) {
+                    stats.hits++;
+                } else {
+                    stats.misses++;
+                }
+            }
+            return result;
+        };
+
+        this.caches.set(name, cache);
+        logger.debug(`创建缓存 ${name}，类型: ${type}，配置:`, finalConfig);
+        
+        return cache;
+    }
+
+    /**
+     * 获取缓存实例
+     * @param name 缓存名称
+     */
+    getCache(name: string) {
+        return this.caches.get(name);
+    }
+
+    /**
+     * 删除缓存实例
+     * @param name 缓存名称
+     */
+    deleteCache(name: string) {
+        const cache = this.caches.get(name);
+        if (cache) {
+            cache.close();
+            this.caches.delete(name);
+            this.stats.delete(name);
+            logger.info(`删除缓存 ${name}`);
+        }
+    }
+
+    /**
+     * 清空所有缓存
+     */
+    clearAllCaches() {
+        this.caches.forEach((cache, name) => {
+            cache.flushAll();
+            logger.info(`清空缓存 ${name}`);
+        });
+    }
+
+    /**
+     * 获取缓存统计信息
+     */
+    getStats() {
+        const result: Record<string, any> = {};
+        this.stats.forEach((stats, name) => {
+            const cache = this.caches.get(name);
+            result[name] = {
+                ...stats,
+                hitRate: stats.hits + stats.misses > 0 ? (stats.hits / (stats.hits + stats.misses) * 100).toFixed(2) + '%' : '0%',
+                config: cache ? cache.options : null
+            };
+        });
+        return result;
+    }
+
+    /**
+     * 获取所有缓存的内存使用情况
+     */
+    getMemoryUsage() {
+        const result: Record<string, any> = {};
+        this.caches.forEach((cache, name) => {
+            const keys = cache.keys();
+            result[name] = {
+                keyCount: keys.length,
+                maxKeys: cache.options.maxKeys,
+                usage: ((keys.length / cache.options.maxKeys) * 100).toFixed(2) + '%'
+            };
+        });
+        return result;
+    }
+}
+
+// 创建全局缓存管理器实例
+const cacheManager = new CacheManager();
+
+/**
+ * 创建缓存的便捷函数
+ * @param name 缓存名称
+ * @param type 缓存类型
+ * @param customConfig 自定义配置
+ */
+export const createCache = (name: string, type: CacheType = CacheType.TEMP, customConfig?: Partial<CacheConfig>) => {
+    return cacheManager.createCache(name, type, customConfig);
+};
+
+/**
+ * 获取缓存实例
+ * @param name 缓存名称
+ */
+export const getCache = (name: string) => {
+    return cacheManager.getCache(name);
+};
+
+/**
+ * 删除缓存实例
+ * @param name 缓存名称
+ */
+export const deleteCache = (name: string) => {
+    return cacheManager.deleteCache(name);
+};
+
+/**
+ * 清空所有缓存
+ */
+export const clearAllCaches = () => {
+    return cacheManager.clearAllCaches();
+};
+
+/**
+ * 获取缓存统计信息
+ */
+export const getCacheStats = () => {
+    return cacheManager.getStats();
+};
+
+/**
+ * 获取缓存内存使用情况
+ */
+export const getCacheMemoryUsage = () => {
+    return cacheManager.getMemoryUsage();
+};
+
+// 导出缓存管理器实例（用于高级操作）
+export { cacheManager };
+
+// 导出默认配置（用于参考）
+export { DEFAULT_CACHE_CONFIG, CACHE_TYPE_CONFIGS };