create-dp-koa 1.0.0

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

@@ -0,0 +1,184 @@
+import swaggerJsdoc from 'swagger-jsdoc';
+import { logger } from './logger';
+
+/**
+ * Swagger配置
+ */
+const swaggerOptions: swaggerJsdoc.Options = {
+  definition: {
+    openapi: '3.0.0',
+    info: {
+      title: 'DP Koa Framework API',
+      version: '1.0.0',
+      description: '基于Koa的企业级框架API文档',
+      contact: {
+        name: 'API Support',
+        email: 'support@example.com',
+      },
+      license: {
+        name: 'MIT',
+        url: 'https://opensource.org/licenses/MIT',
+      },
+    },
+    servers: [
+      {
+        url: process.env.API_BASE_URL || 'http://localhost:3000',
+        description: '开发环境',
+      },
+    ],
+    components: {
+      securitySchemes: {
+        bearerAuth: {
+          type: 'http',
+          scheme: 'bearer',
+          bearerFormat: 'JWT',
+          description: 'JWT授权',
+        },
+      },
+    },
+    tags: [
+      {
+        name: '示例',
+        description: '示例API接口',
+      },
+      {
+        name: '用户',
+        description: '用户相关接口',
+      },
+      {
+        name: '健康检查',
+        description: '系统健康检查接口',
+      },
+    ],
+  },
+  apis: [
+    './src/controllers/**/*.ts',
+    './src/dto/**/*.ts',
+  ],
+};
+
+/**
+ * 生成Swagger规范
+ */
+export function getSwaggerSpec(): any {
+  const spec = swaggerJsdoc(swaggerOptions);
+  return spec;
+}
+
+/**
+ * 从Controller中提取Swagger信息
+ */
+export function extractSwaggerFromController(controller: any, methodName: string, routePath: string, httpMethod: string) {
+  try {
+    // 获取方法的Swagger元数据
+    const metadata: any = {
+      operationId: `${methodName}`,
+      tags: [],
+      summary: '',
+      description: '',
+      parameters: [],
+      requestBody: null,
+      responses: {},
+    };
+
+    // 获取类级别的标签
+    if (controller.constructor.$_SwaggerTags) {
+      metadata.tags = controller.constructor.$_SwaggerTags;
+    }
+
+    // 获取方法级别的元数据
+    if (controller.$_SwaggerMethods && controller.$_SwaggerMethods.has(methodName)) {
+      const methodMeta = controller.$_SwaggerMethods.get(methodName);
+      metadata.summary = methodMeta.summary || methodName;
+      metadata.description = methodMeta.description || '';
+      metadata.operationId = methodMeta.operationId || methodName;
+      if (methodMeta.tags && methodMeta.tags.length > 0) {
+        metadata.tags = methodMeta.tags;
+      }
+    }
+
+    // 获取参数信息
+    if (controller.$_SwaggerParams && controller.$_SwaggerParams.has(methodName)) {
+      const params = controller.$_SwaggerParams.get(methodName);
+      metadata.parameters = params.map((param: any) => ({
+        name: param.name,
+        in: param.in,
+        description: param.description,
+        required: param.required || false,
+        schema: param.schema || { type: 'string' },
+        example: param.example,
+      }));
+    }
+
+    // 获取请求体信息
+    if (controller.$_SwaggerBodies && controller.$_SwaggerBodies.has(methodName)) {
+      const body = controller.$_SwaggerBodies.get(methodName);
+      metadata.requestBody = {
+        description: body.description || '',
+        required: body.required || false,
+        content: {
+          'application/json': {
+            schema: body.schema,
+            examples: body.examples,
+          },
+        },
+      };
+    }
+
+    // 获取响应信息
+    if (controller.$_SwaggerResponses && controller.$_SwaggerResponses.has(methodName)) {
+      const responses = controller.$_SwaggerResponses.get(methodName);
+      responses.forEach((response: any) => {
+        metadata.responses[response.status] = {
+          description: response.description,
+          content: response.schema ? {
+            'application/json': {
+              schema: response.schema,
+              examples: response.examples,
+            },
+          } : undefined,
+        };
+      });
+    } else {
+      // 默认成功响应
+      metadata.responses['200'] = {
+        description: '成功响应',
+        content: {
+          'application/json': {
+            schema: {
+              type: 'object',
+              properties: {
+                code: { type: 'number' },
+                data: { type: 'object' },
+                message: { type: 'string' },
+              },
+            },
+          },
+        },
+      };
+    }
+
+    return metadata;
+  } catch (error) {
+      logger.error('提取Swagger信息失败:', error as Error);
+      return null;
+  }
+}
+
+/**
+ * 根据路径参数生成Swagger路径定义
+ */
+export function generateSwaggerPath(path: string, httpMethod: string, swaggerData: any): string {
+  // 将路径参数转换为Swagger格式
+  let swaggerPath = path;
+  const params = swaggerData?.parameters || [];
+  
+  params.forEach((param: any) => {
+    if (param.in === 'path') {
+      swaggerPath = swaggerPath.replace(`/${param.name}`, `/{${param.name}}`);
+    }
+  });
+
+  return swaggerPath;
+}
+

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

@@ -0,0 +1,19 @@
+import { DataSource } from "typeorm"
+import "reflect-metadata"
+
+export const createTestDataSource = async (entities: any[]) => {
+  return new DataSource({
+    type: "sqlite",
+    database: ":memory:",
+    dropSchema: true,
+    synchronize: true,
+    logging: false,
+    entities: entities
+  }).initialize()
+}
+
+export const closeTestDataSource = async (dataSource: DataSource) => {
+  if (dataSource.isInitialized) {
+    await dataSource.destroy()
+  }
+}

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

@@ -0,0 +1,23 @@
+import { Context } from "koa";
+
+export function getTokenFromHeader(ctx: Context): string | null {
+    // 1. 从Authorization头获取token
+    const authHeader = ctx.headers.authorization || ctx.headers.Authorization;
+    if (!authHeader) {
+        return null;
+    }
+
+    // 2. 检查Bearer token格式
+    if (typeof authHeader === 'string') {
+        const parts = authHeader.split(' ');
+        if (parts.length === 2 && parts[0] === 'Bearer') {
+            return parts[1];
+        }
+    }
+
+    return null;
+}
+
+export function setTokenToHeader(ctx: Context, token: string): void {
+    ctx.set('Authorization', `Bearer ${token}`);
+}

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

@@ -0,0 +1,17 @@
+/**
+ * 转为数字类型
+ * @param val
+ * @returns 
+ */
+export function ToNumber(val: any) {
+    return Number(val);
+}
+
+/**
+ * 去除多余的空格
+ * @param val 
+ * @returns 
+ */
+export function Trim(val: string) {
+    return String(val).trim();
+}

package/template/src/libs/aokEmailSender.ts

@@ -0,0 +1,42 @@
+
+type EmailParams = {
+    to: string;
+    templateId: string;
+    templateData?: Record<string, string>;
+};
+
+export class AokEmailSender{
+    private apiKey: string;
+    private apiUrl: string;
+
+    constructor(apiKey: string, apiUrl = 'https://www.aoksend.com/index/api/send_email') {
+        this.apiKey = apiKey;
+        this.apiUrl = apiUrl;
+    }
+
+    async sendEmail(params: EmailParams): Promise<any> {
+        try {
+            const formData = new URLSearchParams();
+            formData.append('app_key', this.apiKey);
+            formData.append('to', params.to);
+            formData.append('template_id', params.templateId || '');
+            formData.append('data', JSON.stringify(params.templateData || {}));
+
+            const response = await fetch(this.apiUrl, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded'
+                },
+                body: formData.toString()
+            });
+``
+            if (!response.ok) {
+                const errorData = await response.json();
+                throw new Error(errorData.message || 'Failed to send email');
+            }
+            return await response.json();
+        } catch (error) {
+            throw new Error(error instanceof Error ? error.message : 'Failed to send email');
+        }
+    }
+}

package/template/src/libs/captcha.ts

@@ -0,0 +1,37 @@
+import svgCaptcha from 'svg-captcha';
+import jwt from 'jsonwebtoken';
+
+export class CaptchaGenerator {
+  private static readonly JWT_SECRET = process.env.CAPTCHA_JWT_SECRET || 'captcha_secret';
+  private static readonly JWT_EXPIRES_IN = '5m';
+
+  static generate() {
+    const captcha = svgCaptcha.create({
+      size: 4,
+      ignoreChars: '0o1i',
+      noise: 2,
+      color: true,
+      background: '#f0f0f0'
+    });
+
+    const token = jwt.sign(
+      { captcha: captcha.text.toLowerCase() },
+      this.JWT_SECRET,
+      { expiresIn: this.JWT_EXPIRES_IN }
+    );
+
+    return {
+      image: captcha.data,
+      token
+    };
+  }
+
+  static verify(token: string, input: string): boolean {
+    try {
+      const decoded = jwt.verify(token, this.JWT_SECRET) as { captcha: string };
+      return decoded.captcha === input?.toLowerCase();
+    } catch {
+      return false;
+    }
+  }
+}

package/template/src/libs/cos.ts

@@ -0,0 +1,45 @@
+import COS from "cos-nodejs-sdk-v5";
+import fs from "fs";
+
+const SECRET_ID = process.env.COS_SECRET_ID || "";
+const SECRET_KEY = process.env.COS_SECRET_KEY || "";
+const BUCKET = process.env.COS_BUCKET || "";
+const REGION = process.env.COS_REGION || "";
+const FILES_HOST =
+  process.env.WEBOFFICE_FILES_HOST || process.env.FILES_HOST || "";
+
+function getCosClient(): COS | null {
+  if (!SECRET_ID || !SECRET_KEY) return null;
+  return new COS({
+    SecretId: SECRET_ID,
+    SecretKey: SECRET_KEY,
+  });
+}
+
+export function isCosConfigured(): boolean {
+  return !!(SECRET_ID && SECRET_KEY && BUCKET && REGION);
+}
+
+export async function uploadToCos(localFilePath: string, key: string): Promise<void> {
+  const client = getCosClient();
+  if (!client) throw new Error("COS client not configured");
+  if (!BUCKET || !REGION) throw new Error("COS bucket/region not configured");
+  await client.putObject({
+    Bucket: BUCKET,
+    Region: REGION,
+    Key: key,
+    Body: fs.createReadStream(localFilePath),
+  });
+}
+
+export function getFilePublicUrl(key: string): string {
+  if (!FILES_HOST) return "";
+  const host = FILES_HOST.replace(/\/$/, "");
+  const k = key.replace(/^\//, "");
+  return `${host}/${k}`;
+}
+
+export function webofficeCosKey(fileId: string, version: number): string {
+  return `weboffice/files/${fileId}/v${version}`;
+}
+

package/template/src/libs/mCache.ts

@@ -0,0 +1,7 @@
+import { createCache, CacheType } from "@src/framework/utils/cache";
+
+// 使用统一的缓存管理创建用户缓存
+export const ytUserCache = createCache('yt-user', CacheType.USER, {
+    stdTTL: 600, // 10分钟过期
+    maxKeys: 500 // 用户缓存限制500个
+});

package/template/src/libs/serviceValidate.ts

@@ -0,0 +1,3 @@
+export const ServiceValidate = (params: any, instance: any, fn: Function, done: (err: any, param: any) => void) => {
+    console.log(params, instance, fn, done, "seravice拦截器");
+}   

package/template/src/libs/tecentSms.ts

@@ -0,0 +1,51 @@
+import * as tencentcloud from 'tencentcloud-sdk-nodejs';
+import { config } from 'dotenv';
+
+type SmsParams = {
+    PhoneNumberSet: string[];
+    TemplateId: string;
+    SignName: string;
+    TemplateParamSet?: string[];
+    SmsSdkAppId: string;
+};
+
+export class TencentSms {
+    private client: any;
+
+    constructor() {
+        config();
+        const SmsClient = tencentcloud.sms.v20210111.Client;
+
+        this.client = new SmsClient({
+            credential: {
+                secretId: process.env.TENCENT_SMS_SECRET_ID,
+                secretKey: process.env.TENCENT_SMS_SECRET_KEY,
+            },
+            region: process.env.TENCENT_SMS_REGION || 'ap-guangzhou',
+            profile: {
+                httpProfile: {
+                    endpoint: 'sms.tencentcloudapi.com',
+                },
+            },
+        });
+    }
+
+    async sendSms(params: SmsParams): Promise<any> {
+        try {
+            const request = {
+                PhoneNumberSet: params.PhoneNumberSet,
+                TemplateId: params.TemplateId,
+                SignName: params.SignName,
+                TemplateParamSet: params.TemplateParamSet || [],
+                SmsSdkAppId: params.SmsSdkAppId,
+            };
+
+            return await this.client.SendSms(request);
+        } catch (error) {
+            throw error;
+            //   throw new Error(`Failed to send SMS: ${error.message}`);
+        }
+    }
+}
+
+export const tencentSms = new TencentSms();

package/template/src/middlewares/a.middleware.ts

@@ -0,0 +1,6 @@
+export default function () {
+    return async (ctx: any, next: Function) => {
+        // console.log("a middleware ");
+        await next()
+    }
+}

package/template/src/middlewares/error.middleware.ts

@@ -0,0 +1,14 @@
+import { logger } from "@src/framework/utils/logger";
+
+export default function () {
+    return async (ctx: any, next: Function) => {
+        try {
+            await next();
+        } catch (err) {
+            const error = err as any;
+            ctx.status = 500;
+            logger.error((err as Error).message || 'Unknown error');
+            return ctx.body = error;
+        }
+    }
+}

package/template/src/middlewares/logging.middleware.ts

@@ -0,0 +1,187 @@
+import { Context, Next } from 'koa'
+import { logger, createRequestLogger } from '@src/framework/utils/logger'
+import { isDebug } from '@src/framework/utils/function'
+
+/**
+ * 企业级日志中间件
+ * 提供请求追踪、性能监控、安全审计等功能
+ */
+export const loggingMiddleware = () => {
+  return async (ctx: Context, next: Next) => {
+    const startTime = Date.now()
+    const requestId = logger.generateRequestId()
+    
+    // 创建请求专用的日志器
+    const requestLogger = createRequestLogger(requestId)
+    
+    // 设置请求上下文
+    requestLogger.setRequestContext(
+      requestId,
+      ctx.state.user?.id,
+      ctx.session?.id
+    )
+
+    // 设置追踪上下文（如果存在）
+    const traceId = ctx.get('X-Trace-ID') || ctx.get('X-Request-ID')
+    if (traceId) {
+      requestLogger.setTraceContext(traceId, requestId)
+    }
+
+    // 记录请求开始 - 只在调试模式下记录详细信息
+    if (isDebug()) {
+      requestLogger.debug('Request started', {
+        method: ctx.method,
+        url: ctx.url,
+        userAgent: ctx.get('User-Agent'),
+        ip: ctx.ip,
+        headers: sanitizeHeaders(ctx.headers)
+      })
+    }
+
+    // 审计日志 - 请求访问（只在调试模式下输出到控制台）
+    if (isDebug()) {
+      requestLogger.audit('REQUEST_ACCESS', ctx.url, {
+        method: ctx.method,
+        ip: ctx.ip,
+        userAgent: ctx.get('User-Agent'),
+        userId: ctx.state.user?.id
+      })
+    }
+
+    // 将日志器添加到上下文
+    ctx.logger = requestLogger
+    ctx.requestId = requestId
+
+    try {
+      await next()
+      
+      const duration = Date.now() - startTime
+      
+      // 记录请求完成 - 只在调试模式或慢请求时记录
+      if (isDebug() || duration > 1000) {
+        requestLogger.info('Request completed', {
+          method: ctx.method,
+          url: ctx.url,
+          status: ctx.status,
+          duration: `${duration}ms`,
+          responseSize: ctx.response.length || 0
+        })
+      }
+
+      // 性能监控日志 - 只在调试模式下输出到控制台
+      if (isDebug()) {
+        requestLogger.performance('HTTP_REQUEST', duration, {
+          method: ctx.method,
+          url: ctx.url,
+          status: ctx.status,
+          responseSize: ctx.response.length || 0
+        })
+      }
+
+      // 安全审计 - 响应状态
+      if (ctx.status >= 400) {
+        requestLogger.security('HTTP_ERROR_RESPONSE', 
+          ctx.status >= 500 ? 'high' : 'medium', 
+          {
+            status: ctx.status,
+            method: ctx.method,
+            url: ctx.url,
+            userId: ctx.state.user?.id
+          }
+        )
+      }
+
+    } catch (error) {
+      const duration = Date.now() - startTime
+      
+      // 记录错误
+      requestLogger.error('Request failed', error as Error, {
+        method: ctx.method,
+        url: ctx.url,
+        duration: `${duration}ms`
+      })
+
+      // 安全审计 - 错误事件
+      requestLogger.security('REQUEST_ERROR', 'high', {
+        error: error instanceof Error ? error.message : 'Unknown error',
+        method: ctx.method,
+        url: ctx.url,
+        userId: ctx.state.user?.id
+      })
+
+      throw error
+    } finally {
+      // 清理上下文
+      requestLogger.clearContext()
+    }
+  }
+}
+
+/**
+ * 脱敏请求头
+ */
+function sanitizeHeaders(headers: any): any {
+  const sanitized = { ...headers }
+  const sensitiveHeaders = ['authorization', 'cookie', 'x-api-key', 'x-auth-token']
+  
+  sensitiveHeaders.forEach(header => {
+    if (sanitized[header]) {
+      sanitized[header] = '***REDACTED***'
+    }
+  })
+  
+  return sanitized
+}
+
+/**
+ * 业务日志中间件
+ * 用于记录业务操作
+ */
+export const businessLoggingMiddleware = () => {
+  return async (ctx: Context, next: Next) => {
+    const originalBody = ctx.body
+    
+    await next()
+    
+    // 记录业务操作 - 注释掉，不在控制台输出
+    // 如果需要查看业务日志，请查看 logs/structured.log 文件
+    // if (ctx.logger && ctx.status < 400 && isDebug()) {
+    //   ctx.logger.business('API_CALL', {
+    //     method: ctx.method,
+    //     url: ctx.url,
+    //     status: ctx.status,
+    //     userId: ctx.state.user?.id,
+    //     timestamp: new Date().toISOString()
+    //   })
+    // }
+  }
+}
+
+/**
+ * 数据库操作日志中间件
+ */
+export const databaseLoggingMiddleware = () => {
+  return async (ctx: Context, next: Next) => {
+    const startTime = Date.now()
+    
+    await next()
+    
+    const duration = Date.now() - startTime
+    
+    if (ctx.logger && duration > 100) { // 只记录超过100ms的数据库操作
+      ctx.logger.performance('DATABASE_OPERATION', duration, {
+        method: ctx.method,
+        url: ctx.url,
+        userId: ctx.state.user?.id
+      })
+    }
+  }
+}
+
+// 扩展Context类型
+declare module 'koa' {
+  interface Context {
+    logger: any
+    requestId: string
+  }
+}