create-dp-koa 1.0.0

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

@@ -0,0 +1,61 @@
+import path from "path"
+
+/**
+ * 判断当前是否为调试环境
+ */
+export function isDebug(): boolean {
+    let argv = new Set(process.argv)
+    if (argv.has("--env=debug")) {
+        return true
+    }
+    return false
+}
+
+/**
+ * 与 NODE_ENV 解耦的运行环境标识（日志/配置元数据等）
+ * - 启动参数含 `--env=debug` → development
+ * - 否则 → production（非 debug 即生产口径）
+ */
+export function getRuntimeEnvironmentLabel(): 'development' | 'production' {
+    return isDebug() ? 'development' : 'production'
+}
+
+
+/**
+ * 根据文件夹获取项目目录的全路径
+ * @param relativePath 
+ */
+export function getFullPath(relativePath: string): string {
+    return path.join(process.cwd(), relativePath)
+}
+
+/**
+ * 休眠
+ * @param time 毫秒
+ */
+export function sleep(time: number) {
+    return new Promise((resolve) => {
+        setTimeout(() => {
+            resolve("")
+        }, time);
+    })
+}
+
+/**
+ * 判断Promise
+ * @param obj 
+ * @returns 
+ */
+export function isPromise(obj: any) {
+    return !!obj && typeof obj.then === 'function' && typeof obj.catch === 'function';
+}
+
+
+/**
+ * 生成一定范围内的随机数
+ * @param start 
+ * @param end 
+ */
+export function getRandoNumer(start: number, end: number): number {
+	return Math.floor(Math.random() * (end - start + 1)) + start
+}

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

@@ -0,0 +1,131 @@
+import { closeServer } from '@src/framework/utils/bootstrap';
+
+export type ShutdownReason = 'SIGTERM' | 'SIGINT' | 'uncaughtException' | 'unhandledRejection';
+
+export type ShutdownHook = () => void | Promise<void>;
+
+export interface ShutdownLogger {
+  // 兼容项目内 EnterpriseLogger（通常为 info(message, context?) / error(message, error?, context?)）
+  info: (message: string, context?: any) => void;
+  warn?: (message: string, context?: any) => void;
+  error: (message: string, error?: Error, context?: any) => void;
+}
+
+export interface GracefulShutdownControllerOptions {
+  logger: ShutdownLogger;
+  /**
+   * 超时后强制退出，避免资源卡死导致进程无法停止
+   */
+  timeoutMs?: number;
+  /**
+   * 关闭 HTTP server（stop accepting new connections）
+   * 默认为 true
+   */
+  closeHttpServerFirst?: boolean;
+}
+
+type HookItem = { name: string; hook: ShutdownHook };
+
+const toError = (value: unknown): Error => {
+  if (value instanceof Error) return value;
+  if (typeof value === 'string') return new Error(value);
+
+  if (value && typeof value === 'object') {
+    const maybeMessage = (value as any).message;
+    if (typeof maybeMessage === 'string' && maybeMessage.trim()) {
+      return new Error(maybeMessage);
+    }
+  }
+
+  try {
+    return new Error(JSON.stringify(value));
+  } catch {
+    return new Error(String(value));
+  }
+};
+
+/**
+ * 优雅关闭控制器：
+ * - 统一注册 SIGTERM/SIGINT/uncaughtException/unhandledRejection
+ * - 确保只触发一次
+ * - 按注册顺序依次执行 hook（可用于清理 db/cache/monitor 等）
+ */
+export const createGracefulShutdownController = (options: GracefulShutdownControllerOptions) => {
+  const { logger, timeoutMs = 15_000, closeHttpServerFirst = true } = options;
+
+  let registered = false;
+  let shuttingDown = false;
+  const hooks: HookItem[] = [];
+
+  const addHook = (name: string, hook: ShutdownHook) => {
+    hooks.push({ name, hook });
+  };
+
+  const runHooks = async (reason: ShutdownReason, err?: unknown) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+
+    logger.info(`收到 ${reason} 信号，开始优雅关闭...`);
+    if (err) {
+      logger.error(`触发优雅关闭时携带异常（${reason}）`, toError(err));
+    }
+
+    const timer = setTimeout(() => {
+      logger.error(`优雅关闭超时（${timeoutMs}ms），强制退出`);
+      // eslint-disable-next-line n/no-process-exit
+      process.exit(1);
+    }, timeoutMs);
+    // 让 timer 不阻止进程退出
+    timer.unref?.();
+
+    let exitCode = 0;
+
+    try {
+      if (closeHttpServerFirst) {
+        try {
+          await closeServer();
+        } catch (e) {
+          exitCode = 1;
+          logger.error('关闭 HTTP Server 失败', toError(e));
+        }
+      }
+
+      for (const item of hooks) {
+        try {
+          await item.hook();
+        } catch (e) {
+          exitCode = 1;
+          logger.error(`执行关闭钩子失败: ${item.name}`, toError(e));
+        }
+      }
+
+      logger.info('优雅关闭完成');
+    } finally {
+      clearTimeout(timer);
+      // eslint-disable-next-line n/no-process-exit
+      process.exit(exitCode);
+    }
+  };
+
+  const register = () => {
+    if (registered) return;
+    registered = true;
+
+    process.on('SIGTERM', () => runHooks('SIGTERM'));
+    process.on('SIGINT', () => runHooks('SIGINT'));
+
+    process.on('uncaughtException', (error) => {
+      logger.error('未捕获的异常:', error);
+      runHooks('uncaughtException', error);
+    });
+
+    process.on('unhandledRejection', (reason) => {
+      logger.error('未处理的 Promise 拒绝:', toError(reason));
+      runHooks('unhandledRejection', reason);
+    });
+  };
+
+  return { addHook, register };
+};
+
+

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

@@ -0,0 +1,388 @@
+import log4js from 'log4js'
+import { getFullPath, isDebug, getRuntimeEnvironmentLabel } from '@src/framework/utils/function'
+import { randomUUID } from 'crypto'
+
+// 企业级日志配置
+interface LogContext {
+  requestId?: string
+  userId?: string
+  sessionId?: string
+  traceId?: string
+  spanId?: string
+  service?: string
+  version?: string
+  environment?: string
+  [key: string]: any
+}
+
+// 敏感信息脱敏配置
+const SENSITIVE_FIELDS = [
+  'password', 'token', 'secret', 'key', 'auth', 'credential',
+  'ssn', 'socialSecurityNumber', 'creditCard', 'cardNumber',
+  'phone', 'email', 'address', 'ip', 'mac'
+]
+
+// 自定义布局器 - 支持结构化日志
+class EnterpriseLayout {
+  constructor(private config: any) {}
+
+  format(loggingEvent: any): string {
+    const timestamp = new Date(loggingEvent.startTime).toISOString()
+    const level = loggingEvent.level.levelStr
+    const category = loggingEvent.categoryName
+    const message = loggingEvent.data[0]
+    const context = loggingEvent.context || {}
+
+    // 构建结构化日志对象
+    const logEntry = {
+      timestamp,
+      level,
+      category,
+      message,
+      service: context.service || 'dp-koa-framework',
+      version: context.version || '1.0.0',
+      environment: context.environment || getRuntimeEnvironmentLabel(),
+      requestId: context.requestId,
+      userId: context.userId,
+      sessionId: context.sessionId,
+      traceId: context.traceId,
+      spanId: context.spanId,
+      pid: process.pid,
+      hostname: process.env.HOSTNAME || 'localhost',
+      ...this.extractAdditionalData(loggingEvent.data.slice(1))
+    }
+
+    // 脱敏处理
+    this.sanitizeSensitiveData(logEntry)
+
+    return JSON.stringify(logEntry)
+  }
+
+  private extractAdditionalData(data: any[]): any {
+    const additionalData: any = {}
+    
+    data.forEach((item, index) => {
+      if (typeof item === 'object' && item !== null) {
+        Object.assign(additionalData, item)
+      } else {
+        additionalData[`param${index}`] = item
+      }
+    })
+
+    return additionalData
+  }
+
+  private sanitizeSensitiveData(obj: any): void {
+    const sanitize = (value: any): any => {
+      if (typeof value === 'string') {
+        return '***REDACTED***'
+      }
+      if (typeof value === 'object' && value !== null) {
+        const sanitized: any = {}
+        for (const [key, val] of Object.entries(value)) {
+          sanitized[key] = this.isSensitiveField(key) ? '***REDACTED***' : sanitize(val)
+        }
+        return sanitized
+      }
+      return value
+    }
+
+    for (const [key, value] of Object.entries(obj)) {
+      if (this.isSensitiveField(key)) {
+        obj[key] = '***REDACTED***'
+      } else if (typeof value === 'object' && value !== null) {
+        obj[key] = sanitize(value)
+      }
+    }
+  }
+
+  private isSensitiveField(fieldName: string): boolean {
+    return SENSITIVE_FIELDS.some(field => 
+      fieldName.toLowerCase().includes(field.toLowerCase())
+    )
+  }
+}
+
+// 企业级日志器类
+class EnterpriseLogger {
+  private logger: log4js.Logger
+  private context: LogContext = {}
+  private isProduction: boolean
+
+  constructor() {
+    this.logger = log4js.getLogger()
+    this.isProduction = !isDebug()
+    this.setupContext()
+  }
+
+  private setupContext(): void {
+    this.context = {
+      service: 'dp-koa-framework',
+      version: process.env.npm_package_version || '1.0.0',
+      environment: getRuntimeEnvironmentLabel(),
+      pid: process.pid,
+      hostname: process.env.HOSTNAME || 'localhost'
+    }
+  }
+
+  // 设置请求上下文
+  setRequestContext(requestId: string, userId?: string, sessionId?: string): void {
+    this.context.requestId = requestId
+    this.context.userId = userId
+    this.context.sessionId = sessionId
+  }
+
+  // 设置追踪上下文
+  setTraceContext(traceId: string, spanId?: string): void {
+    this.context.traceId = traceId
+    this.context.spanId = spanId
+  }
+
+  // 清除上下文
+  clearContext(): void {
+    this.context = {
+      service: 'dp-koa-framework',
+      version: process.env.npm_package_version || '1.0.0',
+      environment: getRuntimeEnvironmentLabel(),
+      pid: process.pid,
+      hostname: process.env.HOSTNAME || 'localhost'
+    }
+  }
+
+  // 生成请求ID
+  generateRequestId(): string {
+    return randomUUID()
+  }
+
+  // 安全审计日志
+  audit(action: string, resource: string, details?: any): void {
+    // 审计日志写入文件，但不在控制台输出
+    const auditLogger = log4js.getLogger('audit')
+    auditLogger.info('AUDIT', {
+      ...this.context,
+      action,
+      resource,
+      details,
+      timestamp: new Date().toISOString()
+    })
+  }
+
+  // 性能监控日志 - 使用独立的category，不在控制台输出
+  performance(operation: string, duration: number, metrics?: any): void {
+    // 只在生产环境的慢请求时输出到控制台
+    if (this.isProduction && duration > 1000) {
+      this.logger.warn('慢请求警告', {
+        operation,
+        duration,
+        metrics
+      })
+    }
+    // 性能日志始终写入文件，但不会输出到控制台
+    const perfLogger = log4js.getLogger('performance')
+    perfLogger.info('PERFORMANCE', {
+      ...this.context,
+      operation,
+      duration,
+      metrics,
+      timestamp: new Date().toISOString()
+    })
+  }
+
+  // 安全事件日志
+  security(event: string, severity: 'low' | 'medium' | 'high' | 'critical', details?: any): void {
+    this.logger.warn('SECURITY', {
+      ...this.context,
+      event,
+      severity,
+      details,
+      timestamp: new Date().toISOString()
+    })
+  }
+
+  // 业务事件日志 - 不输出到控制台，只写入文件
+  business(event: string, data?: any): void {
+    // 业务日志不输出到控制台，会被 shouldFilterInfo 过滤掉
+    // 如果需要查看业务日志，请查看 logs/structured.log 文件
+    this.info('BUSINESS', {
+      ...this.context,
+      event,
+      data,
+      timestamp: new Date().toISOString()
+    })
+  }
+
+  // 错误日志增强
+  error(message: string, error?: Error, context?: any): void {
+    const errorDetails = error ? {
+      name: error.name,
+      message: error.message,
+      stack: error.stack,
+      code: (error as any).code
+    } : undefined
+
+    this.logger.error(message, {
+      ...this.context,
+      error: errorDetails,
+      context,
+      timestamp: new Date().toISOString()
+    })
+  }
+
+    // 标准日志方法 - 带智能过滤
+    info(message: string, ...args: any[]): void {
+        // 过滤掉冗余信息
+        if (this.shouldFilterInfo(message)) {
+            return
+        }
+        this.logger.info(message, ...args)
+    }
+
+  warn(message: string, ...args: any[]): void {
+    this.logger.warn(message, ...args)
+  }
+
+  debug(message: string, ...args: any[]): void {
+    // 只在调试模式下输出debug日志
+    if (!isDebug()) {
+      return
+    }
+    this.logger.debug(message, ...args)
+  }
+
+  trace(message: string, ...args: any[]): void {
+    // 只在调试模式下输出trace日志
+    if (!isDebug()) {
+      return
+    }
+    this.logger.trace(message, ...args)
+  }
+
+    // 判断是否应该过滤info级别的日志
+    private shouldFilterInfo(message: string): boolean {
+        const filterPatterns = [
+            '创建缓存',
+            '缓存命中',
+            '缓存未命中',
+            'Request started',
+            'Request completed',
+            '启动后执行',
+            '启动前初始化完毕',
+            '启动成功',
+            '[Logging]',
+            'BUSINESS'
+        ]
+        
+        return filterPatterns.some(pattern => message.includes(pattern))
+    }
+
+  // 获取当前上下文
+  getContext(): LogContext {
+    return { ...this.context }
+  }
+}
+
+// 注册自定义布局器
+log4js.addLayout('enterprise', (config: any) => {
+  const layout = new EnterpriseLayout(config)
+  return (logEvent: any) => layout.format(logEvent)
+})
+
+// 配置log4js
+log4js.configure({
+  pm2: true,
+  appenders: {
+    // 结构化日志文件
+    structured: {
+      type: 'dateFile',
+      filename: getFullPath("/logs/structured"),
+      pattern: 'yyyy-MM-dd.log',
+      alwaysIncludePattern: true,
+      maxLogSize: '50M',
+      backups: 30,
+      layout: {
+        type: 'enterprise'
+      },
+    },
+    // 错误日志文件
+    error: {
+      type: 'dateFile',
+      filename: getFullPath("/logs/error"),
+      pattern: 'yyyy-MM-dd.log',
+      alwaysIncludePattern: true,
+      maxLogSize: '20M',
+      backups: 15,
+      layout: {
+        type: 'enterprise'
+      },
+    },
+    // 审计日志文件
+    audit: {
+      type: 'dateFile',
+      filename: getFullPath("/logs/audit"),
+      pattern: 'yyyy-MM-dd.log',
+      alwaysIncludePattern: true,
+      maxLogSize: '30M',
+      backups: 20,
+      layout: {
+        type: 'enterprise'
+      },
+    },
+    // 性能日志文件
+    performance: {
+      type: 'dateFile',
+      filename: getFullPath("/logs/performance"),
+      pattern: 'yyyy-MM-dd.log',
+      alwaysIncludePattern: true,
+      maxLogSize: '25M',
+      backups: 15,
+      layout: {
+        type: 'enterprise'
+      },
+      // 不输出到控制台
+      suppressClustering: true
+    },
+    // 控制台输出 - 简化格式
+    console: {
+      type: 'console',
+      layout: {
+        type: 'colored',
+        pattern: isDebug() 
+          ? '[%d{hh:mm:ss}] [%p] %c - %m'
+          : '[%d{hh:mm:ss}] [%p] %m'
+      }
+    }
+  },
+  categories: {
+    default: {
+      // 开发与生产均输出到控制台，便于查看启动与运行状态
+      appenders: ['console', 'structured'],
+      level: isDebug() ? 'debug' : 'info'
+    },
+    error: {
+      appenders: ['error', 'console'],
+      level: 'error'
+    },
+    audit: {
+      appenders: ['audit'],
+      level: 'info'
+    },
+    performance: {
+      appenders: ['performance'], // 只写入文件，不输出到控制台
+      level: 'info'
+    }
+  }
+})
+
+// 创建企业级日志器实例
+export const logger = new EnterpriseLogger()
+
+// 导出类型和工具函数
+export { LogContext, EnterpriseLogger }
+export const createRequestLogger = (requestId?: string) => {
+  const requestLogger = new EnterpriseLogger()
+  if (requestId) {
+    requestLogger.setRequestContext(requestId)
+  }
+  return requestLogger
+}
+