create-dp-koa 1.0.0

package/template/src/app.ts

@@ -0,0 +1,123 @@
+import { DataSourceOptions } from "typeorm";
+import { bootstrap, setAfterBootstrap, setBeforeBootstrap } from "./framework/utils/bootstrap";
+import { initDb, closeDb, getDataSource } from "@src/framework/utils/db";
+import { clearAllCaches } from "@src/framework/utils/cache";
+import { databaseConfigManager } from "@src/framework/utils/databaseConfig";
+import { migrationManager } from "@src/framework/utils/MigrationManager";
+import { transactionManager } from "@src/framework/utils/TransactionManager";
+import { cacheManager } from "@src/framework/utils/CacheManager";
+import { testDataInitializer } from "@src/utils/testDataInitializer";
+import { isDebug, sleep } from "@src/framework/utils/function";
+import { logger } from "@src/framework/utils/logger";
+import { MigrationHelper } from "@src/framework/utils/MigrationHelper";
+import { AnnotationSystemInitializer } from "@src/framework/decorator/processor/AnnotationSystemInitializer";
+import { annotationRegistry } from "@src/framework/decorator/processor/AnnotationRegistry";
+import { createGracefulShutdownController } from "@src/framework/utils/gracefulShutdown";
+import Router from "@src/routers";
+import dbEntities from "@src/entity"
+import { router } from "@src/framework/utils/router";
+import {
+  collectPluginEntities,
+  getEnabledPlugins,
+  registerPluginRoutes,
+  runAfterBootstrapHooks,
+  runBeforeBootstrapHooks,
+} from "@src/framework/plugins/registry";
+import Koa from "koa";
+import path from "path";
+import staticMiddleware from "@src/middlewares/static.middleware";
+
+const shutdown = createGracefulShutdownController({ logger });
+
+setBeforeBootstrap(async function (app: Koa) {
+  // await sleep(3000)
+
+  // 尽早注册优雅关闭（避免启动期间 SIGINT/SIGTERM 丢失）
+  shutdown.register();
+
+  // 关闭时需要清理的核心资源（与启动流程解耦）
+  shutdown.addHook('annotationRegistry.cleanup', () => annotationRegistry.cleanup());
+  shutdown.addHook('transactionManager.cleanup', () => transactionManager.cleanup());
+  shutdown.addHook('clearAllCaches', () => clearAllCaches());
+  shutdown.addHook('closeDb', () => closeDb());
+
+  const enabledPlugins = getEnabledPlugins();
+  (app as any).plugins = enabledPlugins;
+  await runBeforeBootstrapHooks(app, enabledPlugins);
+
+  // 静态资源映射：默认 /static -> ./static
+  // 可通过环境变量覆盖：STATIC_URL_PREFIX、STATIC_DIR、STATIC_MAX_AGE_SECONDS、STATIC_INDEX
+  app.use(staticMiddleware({
+    urlPrefix: '/static',
+    dir: path.join(process.cwd(), 'static'),
+    maxAgeSeconds: 60 * 60 * 24 * 30,
+    index: 'index.html',
+    defer: false,
+    hidden: false,
+  }));
+  
+  // 初始化新注解处理器系统
+  MigrationHelper.initializeNewSystem();
+  
+  // 初始化注解系统（注册所有处理器）
+  AnnotationSystemInitializer.initialize();
+  
+  // 记录系统状态
+  const systemStatus = MigrationHelper.getSystemStatus();
+  logger.info(`注解系统状态: ${systemStatus.newSystemEnabled ? '新系统' : '旧系统'}, 环境: ${systemStatus.environment}`);
+  
+  Router();
+  registerPluginRoutes(router, enabledPlugins);
+  if (databaseConfigManager.isDatabaseEnabled()) {
+    try {
+      // 根据环境选择数据库配置（支持内存数据库模式）
+      const allEntities = [...dbEntities, ...collectPluginEntities(enabledPlugins)];
+      const dbconfig = databaseConfigManager.getDatabaseConfig(allEntities);
+      
+      await initDb(dbconfig);
+      logger.info(`数据库初始化成功 - 模式: ${databaseConfigManager.getDatabaseTypeDescription()}`);
+
+      // 设置事务管理器的数据源
+      const dataSource = getDataSource();
+      if (dataSource) {
+        transactionManager.setDataSource(dataSource);
+        migrationManager.setDataSource(dataSource);
+      }
+
+      // 非 debug（生产口径）执行迁移
+      if (!isDebug()) {
+        await migrationManager.runMigrations();
+        logger.info('数据库迁移执行完成');
+      }
+
+      // 如果是内存数据库模式，初始化测试数据
+      if (databaseConfigManager.isMemoryDatabaseMode()) {
+        await testDataInitializer.initializeTestData();
+      }
+
+    } catch (err) {
+      logger.error("数据库初始化异常", err as Error)
+      throw err;
+    }
+  }
+  logger.info("启动前初始化完毕");
+});
+
+setAfterBootstrap(async function (app: Koa) {
+  logger.info("启动后执行");
+  const enabledPlugins = getEnabledPlugins();
+  await runAfterBootstrapHooks(app, enabledPlugins);
+});
+
+// 应用启动
+(async () => {
+  try {
+    logger.info("启动应用");
+    await bootstrap();
+    logger.info("启动成功");
+  } catch (error) {
+    logger.error("启动失败", error as Error);
+    process.exit(1);
+  }
+})()
+

package/template/src/controllers/base.controller.ts

@@ -0,0 +1,41 @@
+
+/**
+ * 基础controller类
+ */
+export class ControllerResponse<T> {
+
+    code = 0;
+    data: T | null = null;
+    message: string = ""
+
+    constructor(code: number, data: T | null, message?: string) {
+        this.code = code;
+        this.data = data;
+        if (message) {
+            this.message = message;
+        }
+    }
+}
+export class BaseController {
+
+    /**
+     * 响应成功
+     * @param data 
+     * @param message 
+     * @returns 
+     */
+    success<T>(data: T, message?: string) {
+        return new ControllerResponse<T>(0, data, message);
+    }
+
+
+    /**
+     * 响应失败
+     * @param code 
+     * @param message 
+     * @returns 
+     */
+    fail<T>(code: number, message?: string) {
+        return new ControllerResponse<T>(code, null, message);
+    }
+}

package/template/src/controllers/cacheManagement.controller.ts

@@ -0,0 +1,131 @@
+import { Get, Post } from '@src/framework/decorator/controller';
+import { Body } from '@src/framework/decorator/controller';
+import { BaseController } from '@src/controllers/base.controller';
+import { getCache, deleteCache, getCacheStats, getCacheMemoryUsage, clearAllCaches } from '@src/framework/utils/cache';
+import { logger } from '@src/framework/utils/logger';
+
+export class CacheManagementController extends BaseController {
+
+    /**
+     * 获取所有缓存统计信息
+     */
+    @Get('/cache/stats')
+    async getCacheStats() {
+        const stats = getCacheStats();
+        const memory = getCacheMemoryUsage();
+        
+        return this.success({
+            stats,
+            memory,
+            timestamp: new Date().toISOString()
+        });
+    }
+
+    /**
+     * 清理指定缓存
+     */
+    @Post('/cache/clear')
+    async clearCache(@Body() body: { cacheName: string }) {
+        const { cacheName } = body;
+        
+        if (!cacheName) {
+            return this.fail(400, '缓存名称不能为空');
+        }
+
+        try {
+            const cache = getCache(cacheName);
+            if (!cache) {
+                return this.fail(404, `缓存 ${cacheName} 不存在`);
+            }
+
+            // 清空缓存内容
+            cache.flushAll();
+            logger.info(`手动清理缓存: ${cacheName}`);
+            
+            return this.success({
+                message: `缓存 ${cacheName} 已清理`,
+                cacheName,
+                timestamp: new Date().toISOString()
+            });
+        } catch (error) {
+            logger.error(`清理缓存 ${cacheName} 失败:`, error as Error);
+            return this.fail(500, `清理缓存失败: ${error instanceof Error ? error.message : '未知错误'}`);
+        }
+    }
+
+    /**
+     * 删除指定缓存实例
+     */
+    @Post('/cache/delete')
+    async deleteCache(@Body() body: { cacheName: string }) {
+        const { cacheName } = body;
+        
+        if (!cacheName) {
+            return this.fail(400, '缓存名称不能为空');
+        }
+
+        try {
+            deleteCache(cacheName);
+            logger.info(`删除缓存实例: ${cacheName}`);
+            
+            return this.success({
+                message: `缓存实例 ${cacheName} 已删除`,
+                cacheName,
+                timestamp: new Date().toISOString()
+            });
+        } catch (error) {
+            logger.error(`删除缓存实例 ${cacheName} 失败:`, error as Error);
+            return this.fail(500, `删除缓存实例失败: ${error instanceof Error ? error.message : '未知错误'}`);
+        }
+    }
+
+    /**
+     * 清理所有缓存
+     */
+    @Post('/cache/clear-all')
+    async clearAllCache() {
+        try {
+            clearAllCaches();
+            logger.info('手动清理所有缓存');
+            
+            return this.success({
+                message: '所有缓存已清理',
+                timestamp: new Date().toISOString()
+            });
+        } catch (error) {
+            logger.error('清理所有缓存失败:', error as Error);
+            return this.fail(500, `清理所有缓存失败: ${error instanceof Error ? error.message : '未知错误'}`);
+        }
+    }
+
+    /**
+     * 获取特定缓存的详细信息
+     */
+    @Get('/cache/info')
+    async getCacheInfo(@Body() body: { cacheName: string }) {
+        const { cacheName } = body;
+        
+        if (!cacheName) {
+            return this.fail(400, '缓存名称不能为空');
+        }
+
+        const cache = getCache(cacheName);
+        if (!cache) {
+            return this.fail(404, `缓存 ${cacheName} 不存在`);
+        }
+
+        const keys = cache.keys();
+        const stats = getCacheStats();
+        const memory = getCacheMemoryUsage();
+
+        return this.success({
+            cacheName,
+            keys: keys.slice(0, 10), // 只显示前10个键
+            totalKeys: keys.length,
+            stats: stats[cacheName] || null,
+            memory: memory[cacheName] || null,
+            config: cache.options,
+            timestamp: new Date().toISOString()
+        });
+    }
+}

package/template/src/controllers/captcha.controller.ts

@@ -0,0 +1,57 @@
+
+import { Get, Post } from '@src/framework/decorator/controller';
+import { Body } from '@src/framework/decorator/controller';
+import { CaptchaGenerator } from '@src/libs/captcha';
+import { Inject } from 'dp-ioc2';
+import { createCache, CacheType } from '@src/framework/utils/cache';
+
+// 创建验证码缓存实例
+const captchaCache = createCache('captcha-controller', CacheType.CAPTCHA, {
+    stdTTL: 300, // 5分钟过期
+    maxKeys: 100 // 最多100个验证码
+});
+
+export class CaptchaController {
+
+  // @Inject(CaptchaGenerator)
+  // captchaGenerator: CaptchaGenerator;
+
+  @Get('/captcha')
+  async getCaptcha() {
+    const { image, token } = CaptchaGenerator.generate();
+    return {
+      image,
+      token,
+      contentType: 'image/svg+xml'
+    };
+  }
+  
+  @Post('/captcha/verify')
+  async verifyCaptcha(
+    @Body() body: { captcha: string, token: string }
+  ) {
+    const { captcha, token } = body;
+    if (!token) {
+      return {
+        status: 400,
+        body: { success: false, message: 'Missing captcha token' }
+      };
+    }
+
+    // 检查是否已经验证过（防止重复验证）
+    const verifyKey = `verify_${token}`;
+    if (captchaCache.get(verifyKey)) {
+      return { success: false, message: '验证码已使用' };
+    }
+
+    const isValid = CaptchaGenerator.verify(token, captcha);
+    
+    if (isValid) {
+      // 验证成功后标记为已使用，防止重复验证
+      captchaCache.set(verifyKey, true, 300); // 5分钟内不能重复验证
+    }
+    
+    return { success: isValid };
+  }
+
+}

package/template/src/controllers/demo/AnnotationDemoController.ts

@@ -0,0 +1,118 @@
+import { Get, Query, State } from '@src/framework/decorator/controller';
+import { Logging, Permission, RateLimit } from '@src/framework/decorator/processor/AnnotationDecorators';
+import { PerformanceMonitor } from '@src/annotations/decorators/PerformanceMonitor';
+import { BaseController } from '@src/controllers/base.controller';
+
+/**
+ * 注解演示控制器
+ * 展示业务层自定义注解的使用方法
+ */
+export class AnnotationDemoController extends BaseController {
+    
+    /**
+     * 示例1: 基础性能监控
+     * 使用默认配置的性能监控注解
+     */
+    @Get('/demo/performance/basic')
+    @PerformanceMonitor()
+    async getBasicPerformanceData(@Query() query: any) {
+        // 模拟一些处理时间
+        await new Promise(resolve => setTimeout(resolve, 100));
+        
+        return {
+            code: 0,
+            data: {
+                message: '基础性能监控示例',
+                query,
+                timestamp: Date.now()
+            }
+        };
+    }
+
+    /**
+     * 示例2: 带配置的性能监控
+     * 设置执行时间和内存使用阈值
+     */
+    @Get('/demo/performance/configured')
+    @PerformanceMonitor({ 
+        maxExecutionTime: 200, 
+        maxMemoryUsage: 5,
+        verbose: true 
+    })
+    async getConfiguredPerformanceData(@Query() query: any) {
+        // 模拟较重的操作
+        const data = [];
+        for (let i = 0; i < 10000; i++) {
+            data.push({ id: i, value: Math.random() });
+        }
+        
+        return {
+            code: 0,
+            data: {
+                message: '配置化性能监控示例',
+                query,
+                dataLength: data.length,
+                timestamp: Date.now()
+            }
+        };
+    }
+
+    /**
+     * 示例3: 组合注解使用
+     * 同时使用性能监控、日志记录、权限检查和限流
+     */
+    @Get('/demo/performance/combined')
+    @PerformanceMonitor({ maxExecutionTime: 500 })
+    @Logging()
+    @Permission({ requiredPermission: 'read:performance' })
+    @RateLimit({ maxRequests: 5, windowMs: 60000 })
+    async getCombinedAnnotationData(@Query() query: any, @State() state: any, ctx: any) {
+        // 模拟复杂业务逻辑
+        await new Promise(resolve => setTimeout(resolve, 200));
+        
+        const result = {
+            code: 0,
+            data: {
+                message: '组合注解示例',
+                query,
+                user: state.user,
+                timestamp: Date.now(),
+                performance: 'monitored'
+            }
+        };
+
+            // 性能监控结果现在会自动记录，无需手动调用
+        
+        return result;
+    }
+
+    /**
+     * 示例4: 性能警告触发
+     * 故意触发性能警告的示例
+     */
+    @Get('/demo/performance/warning')
+    @PerformanceMonitor({ 
+        maxExecutionTime: 50,  // 设置很低的阈值
+        maxMemoryUsage: 1      // 设置很低的内存阈值
+    })
+    async getPerformanceWarningData(@Query() query: any) {
+        // 故意执行耗时操作
+        await new Promise(resolve => setTimeout(resolve, 100));
+        
+        // 故意使用大量内存
+        const largeArray = new Array(100000).fill(0).map((_, i) => ({
+            id: i,
+            data: 'x'.repeat(100)
+        }));
+        
+        return {
+            code: 0,
+            data: {
+                message: '性能警告触发示例',
+                query,
+                arrayLength: largeArray.length,
+                timestamp: Date.now()
+            }
+        };
+    }
+}