create-dp-koa 1.0.0

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

@@ -0,0 +1,148 @@
+import { DataSourceOptions } from "typeorm";
+import { logger } from "@src/framework/utils/logger";
+import { APP_MIGRATIONS } from "@src/migrations";
+import { isDebug } from "@src/framework/utils/function";
+
+/**
+ * 数据库配置工具
+ * 框架级别的数据库配置管理
+ */
+export class DatabaseConfigManager {
+    private static instance: DatabaseConfigManager;
+
+    private constructor() {}
+
+    static getInstance(): DatabaseConfigManager {
+        if (!DatabaseConfigManager.instance) {
+            DatabaseConfigManager.instance = new DatabaseConfigManager();
+        }
+        return DatabaseConfigManager.instance;
+    }
+
+    /**
+     * 检查是否启用数据库
+     */
+    isDatabaseEnabled(): boolean {
+        // 在内存数据库模式下也启用数据库
+        if (this.isMemoryDatabaseMode()) {
+            return true;
+        }
+        return Number(process.env.db_enable) == 1;
+    }
+
+    /**
+     * 检查是否为内存数据库模式
+     */
+    isMemoryDatabaseMode(): boolean {
+        return Number(process.env.db_memory) == 1;
+    }
+
+    /**
+     * 获取数据库类型（postgres | mysql），仅非内存模式时有效
+     */
+    private getDbType(): 'postgres' | 'mysql' {
+        const t = (process.env.db_type || 'postgres').toLowerCase();
+        return t === 'mysql' ? 'mysql' : 'postgres';
+    }
+
+    /**
+     * 获取数据库配置
+     * @param entities 实体列表
+     * 内存模式：SQLite 内存（单元测试保持此方案）；否则按 db_type 使用 PostgreSQL 或 MySQL
+     */
+    getDatabaseConfig(entities: any[]): DataSourceOptions {
+        if (this.isMemoryDatabaseMode()) {
+            logger.info("启用内存数据库模式（SQLite）");
+            return this.getMemoryDatabaseConfig(entities);
+        }
+        const dbType = this.getDbType();
+        if (dbType === 'postgres') {
+            logger.info("启用 PostgreSQL 数据库模式");
+            return this.getPostgresDatabaseConfig(entities);
+        }
+        logger.info("启用 MySQL 数据库模式");
+        return this.getMySQLDatabaseConfig(entities);
+    }
+
+    /**
+     * 获取内存数据库配置
+     * 使用 SQLite 内存数据库，适合开发和测试环境
+     */
+    private getMemoryDatabaseConfig(entities: any[]): DataSourceOptions {
+        // 使用 SQLite 内存数据库
+        return {
+            type: "sqlite",
+            database: ":memory:", // SQLite 内存数据库
+            entities: entities,
+            synchronize: true,
+            logging: false,
+            dropSchema: true, // 每次启动时重新创建表结构
+        };
+    }
+
+    /**
+     * 获取 PostgreSQL 数据库配置（dev/debug 推荐）
+     */
+    private getPostgresDatabaseConfig(entities: any[]): DataSourceOptions {
+        const debug = isDebug();
+        return {
+            type: "postgres",
+            host: process.env.db_host ?? "127.0.0.1",
+            port: parseInt(process.env.db_port || "5432", 10),
+            username: process.env.db_username ?? "admin",
+            password: process.env.db_password ?? "",
+            database: process.env.db_database ?? "mydb",
+            entities: entities,
+            // 非 debug（生产口径）关闭自动同步，避免与 migration 冲突
+            synchronize: debug,
+            logging: process.env.db_logging === "1",
+            migrations: APP_MIGRATIONS,
+            migrationsRun: false,
+            migrationsTableName: "migrations",
+        };
+    }
+
+    /**
+     * 获取 MySQL 数据库配置
+     */
+    private getMySQLDatabaseConfig(entities: any[]): DataSourceOptions {
+        const debug = isDebug();
+        return {
+            type: "mysql",
+            connectorPackage: "mysql2",
+            host: process.env?.db_host ?? "127.0.0.1",
+            port: parseInt(process.env.db_port || "3306", 10),
+            username: process.env?.db_username ?? "test",
+            password: process.env?.db_password ?? "test",
+            database: process.env?.db_database ?? "test",
+            entities: entities,
+            // 非 debug（生产口径）关闭自动同步，避免与 migration 冲突
+            synchronize: debug,
+            logging: false,
+            migrations: APP_MIGRATIONS,
+            migrationsRun: false,
+            migrationsTableName: "migrations",
+        };
+    }
+
+    /**
+     * 获取数据库类型描述
+     */
+    getDatabaseTypeDescription(): string {
+        if (this.isMemoryDatabaseMode()) {
+            return "内存数据库（SQLite）";
+        }
+        return this.getDbType() === "postgres" ? "PostgreSQL" : "MySQL";
+    }
+
+    /**
+     * 检查是否需要数据库监控
+     * 内存数据库不需要连接池监控
+     */
+    needsDatabaseMonitoring(): boolean {
+        return this.isDatabaseEnabled() && !this.isMemoryDatabaseMode();
+    }
+}
+
+// 导出单例实例
+export const databaseConfigManager = DatabaseConfigManager.getInstance();

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

@@ -0,0 +1,39 @@
+import { DataSource, DataSourceOptions } from "typeorm"
+import { logger } from "@src/framework/utils/logger"
+
+var _MysqlDataSource: DataSource | null = null;
+
+export const initDb = async (option: DataSourceOptions) => {
+    _MysqlDataSource = new DataSource(option);
+    return _MysqlDataSource.initialize();
+}
+
+export const getDataSource = (): DataSource | null => {
+    return _MysqlDataSource
+}
+
+/**
+ * 关闭数据库连接
+ * 在应用关闭时调用，确保数据库连接池被正确释放
+ */
+export const closeDb = async (): Promise<void> => {
+    if (_MysqlDataSource && _MysqlDataSource.isInitialized) {
+        try {
+            await _MysqlDataSource.destroy();
+            _MysqlDataSource = null;
+            logger.info("数据库连接已关闭");
+        } catch (error) {
+            logger.error("关闭数据库连接时发生错误:", error as Error);
+            throw error;
+        }
+    } else {
+        logger.info("数据库连接未初始化或已关闭");
+    }
+}
+
+/**
+ * 检查数据库连接状态
+ */
+export const isDbConnected = (): boolean => {
+    return _MysqlDataSource !== null && _MysqlDataSource.isInitialized;
+}

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

@@ -0,0 +1,106 @@
+import { logger } from "@src/framework/utils/logger";
+import { getDataSource, isDbConnected } from "@src/framework/utils/db";
+
+/**
+ * 数据库连接监控工具
+ */
+export class DbMonitor {
+    private static instance: DbMonitor;
+    private monitorInterval: NodeJS.Timeout | null = null;
+
+    private constructor() {}
+
+    static getInstance(): DbMonitor {
+        if (!DbMonitor.instance) {
+            DbMonitor.instance = new DbMonitor();
+        }
+        return DbMonitor.instance;
+    }
+
+    /**
+     * 开始监控数据库连接状态
+     * @param intervalMs 监控间隔（毫秒），默认30秒
+     */
+    startMonitoring(intervalMs: number = 30000): void {
+        if (this.monitorInterval) {
+            logger.warn("数据库监控已在运行中");
+            return;
+        }
+
+        this.monitorInterval = setInterval(async () => {
+            try {
+                const isConnected = isDbConnected();
+                const dataSource = getDataSource();
+                
+                if (isConnected && dataSource) {
+                    // 检查是否为内存数据库
+                    const driver = (dataSource as any).driver;
+                    if (driver && driver.options && driver.options.database === ':memory:') {
+                        logger.debug("内存数据库连接正常");
+                    } else {
+                        await dataSource.query('SELECT 1');
+                        const dbType = (dataSource as any).options?.type ?? 'mysql';
+                        logger.debug(`${dbType} 数据库连接正常`);
+                    }
+                } else {
+                    logger.warn("数据库连接异常");
+                }
+            } catch (error) {
+                logger.error("数据库连接检查失败:", error as Error);
+            }
+        }, intervalMs);
+
+        logger.info(`数据库连接监控已启动，监控间隔: ${intervalMs}ms`);
+    }
+
+    /**
+     * 停止监控
+     */
+    stopMonitoring(): void {
+        if (this.monitorInterval) {
+            clearInterval(this.monitorInterval);
+            this.monitorInterval = null;
+            logger.info("数据库连接监控已停止");
+        }
+    }
+
+    /**
+     * 获取数据库连接池状态
+     */
+    async getConnectionPoolStatus(): Promise<any> {
+        const dataSource = getDataSource();
+        if (!dataSource || !dataSource.isInitialized) {
+            return { status: 'disconnected' };
+        }
+
+        try {
+            // 检查是否为内存数据库
+            const driver = (dataSource as any).driver;
+            if (driver && driver.options && driver.options.database === ':memory:') {
+                return {
+                    status: 'connected',
+                    type: 'memory',
+                    message: '内存数据库模式'
+                };
+            }
+
+            const dbType = (dataSource as any).options?.type ?? 'mysql';
+            if (driver && driver.pool) {
+                return {
+                    status: 'connected',
+                    type: dbType,
+                    totalConnections: driver.pool._allConnections?.length || 0,
+                    freeConnections: driver.pool._freeConnections?.length || 0,
+                    usedConnections: driver.pool._usedConnections?.length || 0
+                };
+            }
+            return { status: 'connected', type: dbType, poolInfo: 'unavailable' };
+        } catch (error) {
+            logger.error("获取连接池状态失败:", error as Error);
+            return { status: 'error', error: error instanceof Error ? error.message : '未知错误' };
+        }
+    }
+}
+
+// 导出单例实例
+export const dbMonitor = DbMonitor.getInstance();

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

@@ -0,0 +1,410 @@
+import { Provider } from "dp-ioc2";
+import { SwaggerExampleController } from "@src/controllers/example/SwaggerExampleController";
+import { logger } from "@src/framework/utils/logger";
+import { swaggerProcessor } from "@src/annotations/processors/SwaggerProcessor";
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * 动态检测 bindRouter 路径前缀
+ * 通过分析路由注册信息来确定实际的前缀路径
+ */
+function getBindRouterPrefix(): string {
+    // 方法1: 从环境变量读取（推荐用于生产环境）
+    if (process.env.SWAGGER_ROUTE_PREFIX) {
+        const prefix = process.env.SWAGGER_ROUTE_PREFIX;
+        logger.info(`使用环境变量中的 Swagger 路径前缀: ${prefix}`);
+        return prefix.startsWith('/') ? prefix : `/${prefix}`;
+    }
+    
+    // 方法2: 从路由文件中动态检测（开发环境和调试模式）
+    try {
+        const detectedPrefix = detectPrefixFromRouterFile();
+        if (detectedPrefix) {
+            logger.info(`从路由文件检测到 Swagger 路径前缀: ${detectedPrefix}`);
+            return detectedPrefix;
+        }
+        
+        // 方法3: 使用默认值
+        const defaultPrefix = '/swagger/b';
+        logger.info(`使用默认 Swagger 路径前缀: ${defaultPrefix}`);
+        return defaultPrefix;
+    } catch (error) {
+        logger.warn('无法动态检测路由前缀，使用默认值');
+        return '/swagger/b';
+    }
+}
+
+/**
+ * 从路由文件中检测 SwaggerExampleController 的路径前缀
+ */
+function detectPrefixFromRouterFile(): string | null {
+    try {
+        // 获取路由文件路径
+        const routerFilePath = path.join(process.cwd(), 'src/routers/index.ts');
+        
+        if (!fs.existsSync(routerFilePath)) {
+            logger.warn('路由文件不存在');
+            return null;
+        }
+        
+        // 读取路由文件内容
+        const content = fs.readFileSync(routerFilePath, 'utf8');
+        
+        // 查找 SwaggerExampleController 的 bindRouter 调用
+        const regex = /bindRouter\s*\(\s*["']([^"']+)["']\s*,\s*SwaggerExampleController\s*\)/;
+        const match = content.match(regex);
+        
+        if (match && match[1]) {
+            const detectedPrefix = match[1];
+            logger.info(`从路由文件检测到前缀: ${detectedPrefix}`);
+            return detectedPrefix;
+        } else {
+            logger.warn('未找到 SwaggerExampleController 的 bindRouter 调用');
+            return null;
+        }
+    } catch (error) {
+        logger.error('检测路由文件失败:', error as Error);
+        return null;
+    }
+}
+
+/**
+ * 动态生成 Swagger 规范
+ * 使用新的Swagger处理器来生成更完整的API文档
+ */
+export function generateDynamicSwaggerSpec() {
+    try {
+        logger.info('开始使用Swagger处理器生成API规范...');
+        
+        // 获取 SwaggerExampleController 实例
+        const controller = Provider<any>(SwaggerExampleController);
+        
+        // 使用Swagger处理器生成OpenAPI规范
+        const openAPISpec = swaggerProcessor.generateOpenAPISpec([controller]);
+        
+        // 动态检测 bindRouter 路径前缀
+        const bindRouterPrefix = getBindRouterPrefix();
+        
+        // 更新服务器URL
+        openAPISpec.servers = [
+            {
+                url: 'http://localhost:3000',
+                description: '开发环境',
+            },
+        ];
+        
+        // 收集所有路由信息并更新路径
+        const routes: Array<{method: string, path: string, methodName: string}> = [];
+        
+        // 收集 GET 方法
+        if (controller.$_GetMethods) {
+            const getMethods = Array.from(controller.$_GetMethods) as Array<{methodName: string, url: string}>;
+            getMethods.forEach(({ methodName, url }) => {
+                routes.push({ method: 'get', path: `${bindRouterPrefix}${url}`, methodName });
+            });
+        }
+        
+        // 收集 POST 方法
+        if (controller.$_PostMethods) {
+            const postMethods = Array.from(controller.$_PostMethods) as Array<{methodName: string, url: string}>;
+            postMethods.forEach(({ methodName, url }) => {
+                routes.push({ method: 'post', path: `${bindRouterPrefix}${url}`, methodName });
+            });
+        }
+        
+        // 收集 PUT 方法
+        if (controller.$_PutMethods) {
+            const putMethods = Array.from(controller.$_PutMethods) as Array<{methodName: string, url: string}>;
+            putMethods.forEach(({ methodName, url }) => {
+                routes.push({ method: 'put', path: `${bindRouterPrefix}${url}`, methodName });
+            });
+        }
+        
+        // 收集 DELETE 方法
+        if (controller.$_DelMethods) {
+            const delMethods = Array.from(controller.$_DelMethods) as Array<{methodName: string, url: string}>;
+            delMethods.forEach(({ methodName, url }) => {
+                routes.push({ method: 'delete', path: `${bindRouterPrefix}${url}`, methodName });
+            });
+        }
+
+        // 更新OpenAPI规范中的路径
+        routes.forEach(({ method, path, methodName }) => {
+            const swaggerPath = path.replace(/:(\w+)/g, '{$1}');
+            
+            if (!openAPISpec.paths[swaggerPath]) {
+                openAPISpec.paths[swaggerPath] = {};
+            }
+            
+            // 获取方法的Swagger元数据
+            const methodMetadata = swaggerProcessor.processMethod(controller, methodName);
+            
+            openAPISpec.paths[swaggerPath][method] = {
+                operationId: methodMetadata.operationId,
+                summary: methodMetadata.summary,
+                description: methodMetadata.description,
+                tags: methodMetadata.tags,
+                parameters: methodMetadata.parameters,
+                responses: methodMetadata.responses.reduce((acc, response) => {
+                    acc[response.status.toString()] = {
+                        description: response.description,
+                        content: response.content
+                    };
+                    return acc;
+                }, {} as Record<string, any>)
+            };
+            
+            // 添加请求体
+            if (methodMetadata.requestBody) {
+                openAPISpec.paths[swaggerPath][method].requestBody = methodMetadata.requestBody;
+            }
+        });
+
+        logger.info(`使用Swagger处理器生成API规范成功，包含 ${routes.length} 个路由`);
+        return openAPISpec;
+        
+    } catch (error) {
+        logger.error('使用Swagger处理器生成API规范失败:', error as Error);
+        return getFallbackSwaggerSpec();
+    }
+}
+
+/**
+ * 获取方法的 Swagger 元数据
+ */
+function getMethodSwaggerMetadata(controller: any, methodName: string) {
+    try {
+        // 尝试从控制器的元数据中获取 Swagger 注解信息
+        const metadata = Reflect.getMetadata('swagger:metadata', controller, methodName);
+        
+        if (metadata) {
+            logger.info(`找到方法 ${methodName} 的 Swagger 元数据`);
+            return metadata;
+        }
+        
+        // 如果没有找到元数据，返回默认值
+        return getDefaultMethodMetadata(methodName);
+    } catch (error) {
+        logger.warn(`获取方法 ${methodName} 的 Swagger 元数据失败:`, error as Error);
+        return getDefaultMethodMetadata(methodName);
+    }
+}
+
+/**
+ * 获取默认的方法元数据
+ */
+function getDefaultMethodMetadata(methodName: string) {
+    const baseMetadata = {
+        responses: {
+            '200': {
+                description: '成功',
+                content: {
+                    'application/json': {
+                        schema: {
+                            type: 'object',
+                            properties: {
+                                code: { type: 'number', example: 0 },
+                                data: { type: 'object' },
+                                message: { type: 'string', example: '操作成功' }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    };
+
+    // 根据方法名添加特定的参数
+    if (methodName.includes('List') || methodName.includes('list')) {
+        return {
+            ...baseMetadata,
+            parameters: [
+                {
+                    name: 'page',
+                    in: 'query',
+                    schema: { type: 'number', default: 1 },
+                    description: '页码'
+                },
+                {
+                    name: 'pageSize',
+                    in: 'query',
+                    schema: { type: 'number', default: 10 },
+                    description: '每页数量'
+                },
+                {
+                    name: 'keyword',
+                    in: 'query',
+                    schema: { type: 'string' },
+                    description: '搜索关键词'
+                }
+            ]
+        };
+    }
+
+    if (methodName.includes('ById') || methodName.includes('ById')) {
+        return {
+            ...baseMetadata,
+            parameters: [
+                {
+                    name: 'id',
+                    in: 'path',
+                    required: true,
+                    schema: { type: 'number' },
+                    description: 'ID'
+                }
+            ]
+        };
+    }
+
+    // DELETE 方法添加路径参数
+    if (methodName.includes('delete') || methodName.includes('Delete')) {
+        return {
+            ...baseMetadata,
+            parameters: [
+                {
+                    name: 'id',
+                    in: 'path',
+                    required: true,
+                    schema: { type: 'number' },
+                    description: 'ID'
+                }
+            ]
+        };
+    }
+
+    // POST 方法添加请求体
+    if (methodName.includes('create') || methodName.includes('Create')) {
+        return {
+            ...baseMetadata,
+            requestBody: {
+                required: true,
+                content: {
+                    'application/json': {
+                        schema: {
+                            type: 'object',
+                            required: ['name', 'email'],
+                            properties: {
+                                name: { 
+                                    type: 'string', 
+                                    description: '用户名',
+                                    example: '张三'
+                                },
+                                email: { 
+                                    type: 'string', 
+                                    format: 'email',
+                                    description: '邮箱',
+                                    example: 'zhang@example.com'
+                                },
+                                age: { 
+                                    type: 'number',
+                                    description: '年龄',
+                                    example: 25
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        };
+    }
+
+    // PUT 方法添加路径参数和请求体
+    if (methodName.includes('update') || methodName.includes('Update')) {
+        return {
+            ...baseMetadata,
+            parameters: [
+                {
+                    name: 'id',
+                    in: 'path',
+                    required: true,
+                    schema: { type: 'number' },
+                    description: 'ID'
+                }
+            ],
+            requestBody: {
+                required: true,
+                content: {
+                    'application/json': {
+                        schema: {
+                            type: 'object',
+                            properties: {
+                                name: { type: 'string', description: '用户名' },
+                                email: { type: 'string', format: 'email', description: '邮箱' },
+                                age: { type: 'number', description: '年龄' }
+                            }
+                        }
+                    }
+                }
+            }
+        };
+    }
+
+    return baseMetadata;
+}
+
+/**
+ * 获取默认摘要
+ */
+function getDefaultSummary(method: string, path: string) {
+    const methodMap: {[key: string]: string} = {
+        'get': '获取',
+        'post': '创建',
+        'put': '更新',
+        'delete': '删除'
+    };
+    
+    const action = methodMap[method] || '操作';
+    const resource = path.includes('list') ? '列表' : 
+                    path.includes('{id}') ? '详情' : '资源';
+    
+    return `${action}${resource}`;
+}
+
+/**
+ * 获取默认描述
+ */
+function getDefaultDescription(method: string, path: string) {
+    const descriptions: {[key: string]: string} = {
+        'get': path.includes('list') ? '获取列表数据' : '获取详细信息',
+        'post': '创建新资源',
+        'put': '更新资源信息',
+        'delete': '删除资源'
+    };
+    
+    return descriptions[method] || 'API 操作';
+}
+
+/**
+ * 备用 Swagger 规范
+ */
+function getFallbackSwaggerSpec() {
+    return {
+        openapi: '3.0.0',
+        info: {
+            title: 'DP Koa Framework API',
+            version: '1.0.0',
+            description: '基于Koa的企业级框架API文档',
+        },
+        servers: [
+            {
+                url: 'http://localhost:3000',
+                description: '开发环境',
+            },
+        ],
+        paths: {
+            '/swagger/user/list': {
+                get: {
+                    tags: ['用户管理'],
+                    summary: '获取用户列表',
+                    description: '获取用户列表数据',
+                    responses: {
+                        '200': {
+                            description: '成功返回用户列表',
+                        },
+                    },
+                },
+            },
+        },
+    };
+}