create-dp-koa 1.1.1 → 1.1.3

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

@@ -1,445 +0,0 @@
-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

@@ -1,269 +0,0 @@
-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 };