koa3-cli 1.0.3 → 1.0.5

package/README.md

@@ -38,7 +38,7 @@ npm run dev
 ## 项目结构
 
 ```
-koa2-cli/
+koa3-cli/
 ├── app/                    # 应用代码目录
 │   ├── controller/        # 控制器目录
 │   │   ├── home.js        # 首页控制器
@@ -99,18 +99,6 @@ npm start
 - API 示例: http://localhost:3000/api/user
 - 文档: http://localhost:3000/index.html
 
-### 文档开发
-
-启动 VuePress 文档开发服务器：
-```bash
-npm run docs:dev
-```
-
-构建文档为静态文件：
-```bash
-npm run docs:build
-```
-
 ## 环境配置
 
 项目支持多环境配置，通过 `NODE_ENV` 环境变量控制：
@@ -196,8 +184,8 @@ router.get('/api/product', productController.list);
 
 ## 技术栈
 
-- **Koa2**: Web 框架
-- **koa-router**: 路由
+- **Koa3**: Web 框架
+- **@koa/router**: 路由
 - **koa-bodyparser**: 请求体解析
 - **koa-static**: 静态资源服务
 - **koa-views**: 模板引擎支持

package/app/controller/home.js

@@ -7,7 +7,7 @@ class HomeController {
    */
   async index(ctx) {
     ctx.body = {
-      message: 'Welcome to Koa2 CLI',
+      message: 'Welcome to Koa3 CLI',
       version: '1.0.0',
       timestamp: new Date().toISOString()
     };

package/app/controller/user.js

@@ -1,89 +1,100 @@
-/**
- * 用户控制器
- */
-const userService = require('../service/user');
-
-class UserController {
-  /**
-   * 获取用户列表
-   */
-  async list(ctx) {
-    try {
-      const users = await userService.getUserList();
-      ctx.body = users;
-    } catch (error) {
-      ctx.throw(500, error.message);
-    }
-  }
-
-  /**
-   * 获取用户详情
-   */
-  async detail(ctx) {
-    try {
-      const { id } = ctx.params;
-      const user = await userService.getUserById(id);
-      if (!user) {
-        ctx.status = 404;
-        ctx.body = { message: 'User not found' };
-        return;
-      }
-      ctx.body = user;
-    } catch (error) {
-      ctx.throw(500, error.message);
-    }
-  }
-
-  /**
-   * 创建用户
-   */
-  async create(ctx) {
-    try {
-      const userData = ctx.request.body;
-      const user = await userService.createUser(userData);
-      ctx.status = 201;
-      ctx.body = user;
-    } catch (error) {
-      ctx.throw(500, error.message);
-    }
-  }
-
-  /**
-   * 更新用户
-   */
-  async update(ctx) {
-    try {
-      const { id } = ctx.params;
-      const userData = ctx.request.body;
-      const user = await userService.updateUser(id, userData);
-      if (!user) {
-        ctx.status = 404;
-        ctx.body = { message: 'User not found' };
-        return;
-      }
-      ctx.body = user;
-    } catch (error) {
-      ctx.throw(500, error.message);
-    }
-  }
-
-  /**
-   * 删除用户
-   */
-  async delete(ctx) {
-    try {
-      const { id } = ctx.params;
-      const result = await userService.deleteUser(id);
-      if (!result) {
-        ctx.status = 404;
-        ctx.body = { message: 'User not found' };
-        return;
-      }
-      ctx.status = 204;
-    } catch (error) {
-      ctx.throw(500, error.message);
-    }
-  }
-}
-
+const userService = require('../service/user');
+
+function logMeta(ctx, extra = {}) {
+  return {
+    requestId: ctx.state && ctx.state.requestId,
+    method: ctx.method,
+    url: ctx.originalUrl || ctx.url,
+    ...extra
+  };
+}
+
+class UserController {
+  async list(ctx) {
+    try {
+      const users = await userService.getUserList();
+      ctx.logger.info('User list fetched', logMeta(ctx, { count: Array.isArray(users) ? users.length : undefined }));
+      ctx.body = users;
+    } catch (error) {
+      ctx.logger.error('Failed to fetch user list', logMeta(ctx, { message: error.message, stack: error.stack }));
+      ctx.throw(500, error.message);
+    }
+  }
+
+  async detail(ctx) {
+    const { id } = ctx.params;
+
+    try {
+      const user = await userService.getUserById(id);
+      if (!user) {
+        ctx.logger.warn('User detail not found', logMeta(ctx, { userId: id }));
+        ctx.status = 404;
+        ctx.body = { message: 'User not found' };
+        return;
+      }
+
+      ctx.logger.info('User detail fetched', logMeta(ctx, { userId: id }));
+      ctx.body = user;
+    } catch (error) {
+      ctx.logger.error('Failed to fetch user detail', logMeta(ctx, { userId: id, message: error.message, stack: error.stack }));
+      ctx.throw(500, error.message);
+    }
+  }
+
+  async create(ctx) {
+    const userData = ctx.request.body;
+
+    try {
+      const user = await userService.createUser(userData);
+      ctx.logger.info('User created', logMeta(ctx, { userId: user && user.id }));
+      ctx.status = 201;
+      ctx.body = user;
+    } catch (error) {
+      ctx.logger.error('Failed to create user', logMeta(ctx, { message: error.message, stack: error.stack }));
+      ctx.throw(500, error.message);
+    }
+  }
+
+  async update(ctx) {
+    const { id } = ctx.params;
+    const userData = ctx.request.body;
+
+    try {
+      const user = await userService.updateUser(id, userData);
+      if (!user) {
+        ctx.logger.warn('User update target not found', logMeta(ctx, { userId: id }));
+        ctx.status = 404;
+        ctx.body = { message: 'User not found' };
+        return;
+      }
+
+      ctx.logger.info('User updated', logMeta(ctx, { userId: id }));
+      ctx.body = user;
+    } catch (error) {
+      ctx.logger.error('Failed to update user', logMeta(ctx, { userId: id, message: error.message, stack: error.stack }));
+      ctx.throw(500, error.message);
+    }
+  }
+
+  async delete(ctx) {
+    const { id } = ctx.params;
+
+    try {
+      const result = await userService.deleteUser(id);
+      if (!result) {
+        ctx.logger.warn('User delete target not found', logMeta(ctx, { userId: id }));
+        ctx.status = 404;
+        ctx.body = { message: 'User not found' };
+        return;
+      }
+
+      ctx.logger.info('User deleted', logMeta(ctx, { userId: id }));
+      ctx.status = 204;
+    } catch (error) {
+      ctx.logger.error('Failed to delete user', logMeta(ctx, { userId: id, message: error.message, stack: error.stack }));
+      ctx.throw(500, error.message);
+    }
+  }
+}
+
 module.exports = new UserController();

package/app/lib/logger.js

@@ -0,0 +1,141 @@
+const fs = require('fs');
+const path = require('path');
+const util = require('util');
+
+const LEVEL_WEIGHT = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40
+};
+
+function normalizeLevel(level) {
+  const resolved = String(level || 'info').toLowerCase();
+  return LEVEL_WEIGHT[resolved] ? resolved : 'info';
+}
+
+function formatDate(date = new Date()) {
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+
+function formatTimestamp(date = new Date()) {
+  return date.toLocaleString();
+}
+
+function safeSerialize(meta) {
+  if (meta === undefined) {
+    return '';
+  }
+
+  if (meta instanceof Error) {
+    return JSON.stringify({
+      name: meta.name,
+      message: meta.message,
+      stack: meta.stack
+    });
+  }
+
+  if (typeof meta === 'string') {
+    return meta;
+  }
+
+  try {
+    return JSON.stringify(meta);
+  } catch (error) {
+    return util.inspect(meta, { depth: 4, breakLength: 120 });
+  }
+}
+
+class Logger {
+  constructor(options = {}) {
+    this.level = normalizeLevel(options.level);
+    this.enableConsole = options.enableConsole !== false;
+    this.enableFile = options.enableFile !== false;
+    this.dir = options.dir || 'logs';
+    this.appName = options.appName || 'koa3-cli';
+    this.cwd = options.cwd || process.cwd();
+    this.logDir = path.isAbsolute(this.dir) ? this.dir : path.join(this.cwd, this.dir);
+
+    if (this.enableFile) {
+      fs.mkdirSync(this.logDir, { recursive: true });
+    }
+  }
+
+  shouldLog(level) {
+    return LEVEL_WEIGHT[level] >= LEVEL_WEIGHT[this.level];
+  }
+
+  write(level, message, meta) {
+    if (!this.shouldLog(level)) {
+      return;
+    }
+
+    const timestamp = formatTimestamp();
+    const metaText = safeSerialize(meta);
+    const line = `[${timestamp}] [${this.appName}] [${level.toUpperCase()}] ${message}${metaText ? ` ${metaText}` : ''}`;
+
+    if (this.enableConsole) {
+      const printer = level === 'error' ? console.error : level === 'warn' ? console.warn : console.log;
+      printer(line);
+    }
+
+    if (!this.enableFile) {
+      return;
+    }
+
+    const date = formatDate();
+    const commonPath = path.join(this.logDir, `${date}.log`);
+    fs.appendFile(commonPath, `${line}\n`, () => {});
+
+    if (level === 'error') {
+      const errorPath = path.join(this.logDir, `${date}.error.log`);
+      fs.appendFile(errorPath, `${line}\n`, () => {});
+    }
+  }
+
+  access(data) {
+    const line = {
+      timestamp: formatTimestamp(),
+      type: 'access',
+      app: this.appName,
+      ...data
+    };
+
+    if (this.enableConsole && this.shouldLog('info')) {
+      console.log(`[${line.timestamp}] [${this.appName}] [ACCESS] ${line.method} ${line.url} ${line.status} ${line.duration}ms ${line.requestId}`);
+    }
+
+    if (!this.enableFile) {
+      return;
+    }
+
+    const date = formatDate();
+    const accessPath = path.join(this.logDir, `${date}.access.log`);
+    fs.appendFile(accessPath, `${JSON.stringify(line)}\n`, () => {});
+  }
+
+  debug(message, meta) {
+    this.write('debug', message, meta);
+  }
+
+  info(message, meta) {
+    this.write('info', message, meta);
+  }
+
+  warn(message, meta) {
+    this.write('warn', message, meta);
+  }
+
+  error(message, meta) {
+    this.write('error', message, meta);
+  }
+}
+
+function createLogger(options) {
+  return new Logger(options);
+}
+
+module.exports = {
+  createLogger
+};

package/app/middleware/requestLogger.js

@@ -0,0 +1,27 @@
+function createRequestId() {
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+module.exports = function requestLogger(logger) {
+  return async function requestLoggerMiddleware(ctx, next) {
+    const start = Date.now();
+    const requestId = ctx.get('x-request-id') || createRequestId();
+
+    ctx.state.requestId = requestId;
+    ctx.set('x-request-id', requestId);
+
+    try {
+      await next();
+    } finally {
+      const duration = Date.now() - start;
+      logger.access({
+        requestId,
+        method: ctx.method,
+        url: ctx.originalUrl || ctx.url,
+        status: ctx.status,
+        duration,
+        ip: ctx.ip
+      });
+    }
+  };
+};

package/app.js

@@ -1,112 +1,119 @@
-const Koa = require('koa');
-const { Router } = require('@koa/router');
-const bodyParser = require('koa-bodyparser');
-const static = require('koa-static');
-const views = require('@ladjs/koa-views');
-const path = require('path');
-const fs = require('fs');
-
-// 加载环境变量
-require('dotenv').config();
-
-// 加载配置（支持环境配置覆盖）
-const env = process.env.NODE_ENV || 'development';
-const defaultConfig = require('./config/config.default');
-let envConfig = {};
-try {
-  if (env === 'production') {
-    envConfig = require('./config/config.prod');
-  } else if (env === 'local' || env === 'development') {
-    envConfig = require('./config/config.local');
-  }
-} catch (e) {
-  // 环境配置文件不存在时忽略
-}
-const config = Object.assign({}, defaultConfig, envConfig);
-
-// 加载中间件
-const middleware = require('./app/middleware');
-
-// 加载路由
-const router = require('./app/router');
-
-const app = new Koa();
-
-// 应用配置
-app.keys = config.keys || ['koa2-cli-secret-key'];
-
-// 静态资源
-if (config.static && config.static.enable !== false) {
-  const staticPath = path.join(__dirname, config.static.dir || 'public');
-  if (fs.existsSync(staticPath)) {
-    app.use(static(staticPath, config.static.options || {}));
-  }
-}
-
-// 模板引擎
-if (config.view && config.view.enable !== false) {
-  const viewPath = path.join(__dirname, config.view.root || 'app/view');
-  if (fs.existsSync(viewPath)) {
-    app.use(views(viewPath, config.view.options || {
-      extension: 'ejs'
-    }));
-  }
-}
-
-// 请求体解析
-app.use(bodyParser(config.bodyParser || {}));
-
-// 自定义中间件
-if (middleware && typeof middleware === 'function') {
-  app.use(middleware);
-}
-
-// 错误处理中间件
-app.use(async (ctx, next) => {
-  try {
-    await next();
-  } catch (err) {
-    ctx.status = err.status || 500;
-    ctx.body = {
-      success: false,
-      message: err.message || 'Internal Server Error',
-      ...(config.env === 'development' && { stack: err.stack })
-    };
-    ctx.app.emit('error', err, ctx);
-  }
-});
-
-// 日志中间件
-app.use(async (ctx, next) => {
-  const start = Date.now();
-  await next();
-  const ms = Date.now() - start;
-  console.log(`${ctx.method} ${ctx.url} - ${ms}ms`);
-});
-
-// 注册路由
-app.use(router.routes()).use(router.allowedMethods());
-
-// 404 处理（必须在路由之后）
-app.use(async (ctx) => {
-  if (ctx.status === 404) {
-    ctx.body = {
-      success: false,
-      message: 'Not Found'
-    };
-  }
-});
-
-// 错误事件监听
-app.on('error', (err, ctx) => {
-  console.error('Server error:', err);
-});
-
-// 启动服务器
-const port = config.port || 3000;
-app.listen(port, () => {
-  console.log(`Server is running on http://localhost:${port}`);
-  console.log(`Environment: ${config.env}`);
-});
-
+const Koa = require('koa');
+const bodyParser = require('koa-bodyparser');
+const serveStatic = require('koa-static');
+const views = require('@ladjs/koa-views');
+const path = require('path');
+const fs = require('fs');
+const { createLogger } = require('./app/lib/logger');
+const createRequestLogger = require('./app/middleware/requestLogger');
+
+require('dotenv').config();
+
+const env = process.env.NODE_ENV || 'development';
+const defaultConfig = require('./config/config.default');
+let envConfig = {};
+try {
+  if (env === 'production') {
+    envConfig = require('./config/config.prod');
+  } else if (env === 'local' || env === 'development') {
+    envConfig = require('./config/config.local');
+  }
+} catch (e) {
+  // Ignore missing env config override.
+}
+const config = Object.assign({}, defaultConfig, envConfig);
+
+const middleware = require('./app/middleware');
+const router = require('./app/router');
+
+const app = new Koa();
+const logger = createLogger({
+  ...(config.logger || {}),
+  appName: config.name || 'koa3-cli',
+  cwd: __dirname
+});
+
+app.keys = config.keys || ['koa3-cli-secret-key'];
+app.context.logger = logger;
+
+if (config.static && config.static.enable !== false) {
+  const staticPath = path.join(__dirname, config.static.dir || 'public');
+  if (fs.existsSync(staticPath)) {
+    app.use(serveStatic(staticPath, config.static.options || {}));
+  }
+}
+
+if (config.view && config.view.enable !== false) {
+  const viewPath = path.join(__dirname, config.view.root || 'app/view');
+  if (fs.existsSync(viewPath)) {
+    app.use(views(viewPath, config.view.options || {
+      extension: 'ejs'
+    }));
+  }
+}
+
+app.use(bodyParser(config.bodyParser || {}));
+app.use(createRequestLogger(logger));
+
+if (middleware && typeof middleware === 'function') {
+  app.use(middleware);
+}
+
+app.use(async (ctx, next) => {
+  try {
+    await next();
+  } catch (err) {
+    ctx.status = err.status || 500;
+    ctx.body = {
+      success: false,
+      message: err.message || 'Internal Server Error',
+      ...(config.env === 'development' && { stack: err.stack })
+    };
+
+    logger.error('Request failed', {
+      requestId: ctx.state && ctx.state.requestId,
+      method: ctx.method,
+      url: ctx.originalUrl || ctx.url,
+      status: ctx.status,
+      message: err.message,
+      stack: err.stack
+    });
+
+    ctx.app.emit('error', err, ctx);
+  }
+});
+
+app.use(router.routes()).use(router.allowedMethods());
+
+app.use(async (ctx) => {
+  if (ctx.status === 404) {
+    ctx.body = {
+      success: false,
+      message: 'Not Found'
+    };
+  }
+});
+
+app.on('error', (err, ctx) => {
+  logger.error('Server error event', {
+    requestId: ctx && ctx.state && ctx.state.requestId,
+    message: err.message,
+    stack: err.stack
+  });
+});
+
+process.on('unhandledRejection', (reason) => {
+  logger.error('Unhandled promise rejection', reason);
+});
+
+process.on('uncaughtException', (error) => {
+  logger.error('Uncaught exception', error);
+});
+
+const port = config.port || 3000;
+app.listen(port, () => {
+  logger.info(`Server is running on http://localhost:${port}`);
+  logger.info(`Environment: ${config.env}`);
+});
+
 module.exports = app;

package/config/config.default.js

@@ -1,82 +1,83 @@
-/**
- * 默认配置文件
- * 所有环境都会加载此配置
- */
-module.exports = {
-  // 应用名称
-  name: 'koa2-cli',
-  
-  // 运行环境: development, production, test
-  env: process.env.NODE_ENV || 'development',
-  
-  // 服务端口
-  port: process.env.PORT || 3000,
-  
-  // 密钥，用于加密cookie等
-  keys: process.env.KEYS ? process.env.KEYS.split(',') : ['koa2-cli-secret-key'],
-  
-  // 静态资源配置
-  static: {
-    enable: true,
-    dir: 'public',
-    options: {
-      maxAge: 365 * 24 * 60 * 60 * 1000, // 1年
-      gzip: true
-    }
-  },
-  
-  // VuePress 文档配置
-  docs: {
-    enable: true,
-    buildDir: 'public/docs'
-  },
-  
-  // 视图配置
-  view: {
-    enable: true,
-    root: 'app/view',
-    options: {
-      extension: 'ejs',
-      map: {
-        html: 'ejs'
-      }
-    }
-  },
-  
-  // bodyParser配置
-  bodyParser: {
-    enableTypes: ['json', 'form', 'text'],
-    jsonLimit: '10mb',
-    formLimit: '10mb'
-  },
-  
-  // 数据库配置（示例）
-  database: {
-    client: 'mysql',
-    connection: {
-      host: process.env.DB_HOST || 'localhost',
-      port: process.env.DB_PORT || 3306,
-      user: process.env.DB_USER || 'root',
-      password: process.env.DB_PASSWORD || '',
-      database: process.env.DB_NAME || 'test'
-    },
-    pool: {
-      min: 2,
-      max: 10
-    }
-  },
-  
-  // Redis配置（示例）
-  redis: {
-    host: process.env.REDIS_HOST || 'localhost',
-    port: process.env.REDIS_PORT || 6379,
-    password: process.env.REDIS_PASSWORD || '',
-    db: process.env.REDIS_DB || 0
-  },
-  
-  // 日志配置
-  logger: {
-    level: process.env.LOG_LEVEL || 'info',
-    dir: 'logs'
-  }
+/**
+ * Default config loaded in all environments.
+ */
+module.exports = {
+  // Application name
+  name: 'koa3-cli',
+
+  // Runtime env: development, production, test
+  env: process.env.NODE_ENV || 'development',
+
+  // Server port
+  port: process.env.PORT || 3000,
+
+  // Cookie signing keys
+  keys: process.env.KEYS ? process.env.KEYS.split(',') : ['koa3-cli-secret-key'],
+
+  // Static assets
+  static: {
+    enable: true,
+    dir: 'public',
+    options: {
+      maxAge: 365 * 24 * 60 * 60 * 1000,
+      gzip: true
+    }
+  },
+
+  // Docs build config
+  docs: {
+    enable: true,
+    buildDir: 'public/docs'
+  },
+
+  // View engine
+  view: {
+    enable: true,
+    root: 'app/view',
+    options: {
+      extension: 'ejs',
+      map: {
+        html: 'ejs'
+      }
+    }
+  },
+
+  // bodyParser
+  bodyParser: {
+    enableTypes: ['json', 'form', 'text'],
+    jsonLimit: '10mb',
+    formLimit: '10mb'
+  },
+
+  // Database (example)
+  database: {
+    client: 'mysql',
+    connection: {
+      host: process.env.DB_HOST || 'localhost',
+      port: process.env.DB_PORT || 3306,
+      user: process.env.DB_USER || 'root',
+      password: process.env.DB_PASSWORD || '',
+      database: process.env.DB_NAME || 'test'
+    },
+    pool: {
+      min: 2,
+      max: 10
+    }
+  },
+
+  // Redis (example)
+  redis: {
+    host: process.env.REDIS_HOST || 'localhost',
+    port: process.env.REDIS_PORT || 6379,
+    password: process.env.REDIS_PASSWORD || '',
+    db: process.env.REDIS_DB || 0
+  },
+
+  // Logger
+  logger: {
+    level: process.env.LOG_LEVEL || 'info',
+    dir: process.env.LOG_DIR || 'logs',
+    enableConsole: process.env.LOG_ENABLE_CONSOLE !== 'false',
+    enableFile: process.env.LOG_ENABLE_FILE !== 'false'
+  }
 };

package/env.example

@@ -25,3 +25,7 @@ REDIS_DB=0
 
 # 日志级别: debug, info, warn, error
 LOG_LEVEL=info
+
+LOG_DIR=logs
+LOG_ENABLE_CONSOLE=true
+LOG_ENABLE_FILE=true

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "koa3-cli",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Koa3脚手架",
   "main": "app.js",
   "bin": {
-    "koa3-cli": "./bin/cli.js"
+    "koa3-cli": "bin/cli.js"
   },
   "preferGlobal": true,
   "scripts": {
@@ -25,17 +25,17 @@
   "homepage": "https://atwzc.cn/",
   "license": "MIT",
   "dependencies": {
-    "@koa/router": "^15.2.0",
+    "@koa/router": "^15.3.1",
     "@ladjs/koa-views": "^9.0.0",
-    "dotenv": "^17.2.3",
-    "ejs": "^3.1.10",
-    "koa": "^3.1.1",
+    "dotenv": "^17.3.1",
+    "ejs": "^4.0.1",
+    "koa": "^3.1.2",
     "koa-bodyparser": "^4.4.1",
     "koa-cors": "^0.0.16",
     "koa-static": "^5.0.0"
   },
   "devDependencies": {
-    "nodemon": "^3.1.11"
+    "nodemon": "^3.1.14"
   },
   "volta": {
     "node": "20.18.1"