koa3-cli 1.0.5 → 1.0.6

package/README.md

@@ -49,12 +49,16 @@ koa3-cli/
 │   │   └── user.js        # 用户模型
 │   ├── middleware/        # 中间件目录
 │   │   ├── index.js       # 中间件入口
-│   │   └── auth.js        # 认证中间件示例
+│   │   ├── auth.js        # 认证中间件示例
+│   │   └── requestLogger.js # 请求日志中间件
+│   ├── lib/               # 基础能力目录
+│   │   └── logger.js      # 日志工具
 │   └── router.js          # 路由配置
 ├── config/                # 配置文件目录
 │   ├── config.default.js  # 默认配置
 │   ├── config.local.js    # 本地开发配置
 │   └── config.prod.js     # 生产环境配置
+├── logs/                  # 日志输出目录（运行时自动创建）
 ├── public/                # 静态资源目录
 │   └── index.html         # 首页
 ├── app.js                 # 应用入口文件
@@ -71,6 +75,7 @@ koa3-cli/
 - ✅ MVC 架构（Controller/Service/Model）
 - ✅ 中间件支持
 - ✅ 统一的错误处理
+- ✅ 内置日志系统（访问日志、错误日志、请求追踪）
 - ✅ RESTful API 示例
 
 ## 快速开始
@@ -109,6 +114,31 @@ npm start
 
 可以通过 `.env` 文件配置环境变量（参考 `.env.example`）。
 
+### 日志配置
+
+日志系统默认开启控制台和文件输出，支持 4 个级别：`debug`、`info`、`warn`、`error`。
+
+`.env` 可配置项：
+
+```bash
+LOG_LEVEL=info
+LOG_DIR=logs
+LOG_ENABLE_CONSOLE=true
+LOG_ENABLE_FILE=true
+```
+
+运行后会在日志目录按天生成文件：
+
+- `<date>.log`：通用应用日志
+- `<date>.access.log`：请求访问日志（JSON 行格式）
+- `<date>.error.log`：错误级别日志
+
+请求日志中间件会自动处理 `x-request-id`：
+
+- 如果请求头带有 `x-request-id`，服务端会透传并写入日志
+- 如果没有，服务端会自动生成并在响应头返回
+- 出错日志会带上 `requestId`，便于串联排查
+
 ## API 示例
 
 ### 获取用户列表

package/app/controller/user.js

@@ -1,100 +1,100 @@
-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);
-    }
-  }
-}
-
+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

@@ -1,141 +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
-};
+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/errorHandler.js

@@ -0,0 +1,28 @@
+/**
+ * 全局错误处理中间件：捕获异常、记录日志、统一错误响应
+ */
+module.exports = function createErrorHandler(config, logger) {
+  return async function errorHandler(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);
+    }
+  };
+};

package/app/middleware/notFound.js

@@ -0,0 +1,11 @@
+/**
+ * 404 兜底中间件：未匹配路由时返回统一格式
+ */
+module.exports = async function notFound(ctx) {
+  if (ctx.status === 404) {
+    ctx.body = {
+      success: false,
+      message: 'Not Found'
+    };
+  }
+};

package/app/middleware/requestLogger.js

@@ -1,27 +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
-      });
-    }
-  };
-};
+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/processEvents.js

@@ -0,0 +1,14 @@
+/**
+ * 进程级错误监听：未捕获的 Promise 与异常
+ */
+function setupProcessEvents(logger) {
+  process.on('unhandledRejection', (reason) => {
+    logger.error('Unhandled promise rejection', reason);
+  });
+
+  process.on('uncaughtException', (error) => {
+    logger.error('Uncaught exception', error);
+  });
+}
+
+module.exports = setupProcessEvents;

package/app/setup.js

@@ -0,0 +1,48 @@
+/**
+ * 应用挂载：静态资源、视图、中间件、路由等
+ * 保持 app.js 只做「创建实例 + 调用 setup + 监听 + 启动」
+ */
+const path = require('path');
+const fs = require('fs');
+const bodyParser = require('koa-bodyparser');
+const serveStatic = require('koa-static');
+const views = require('@ladjs/koa-views');
+
+const createRequestLogger = require('./middleware/requestLogger');
+const createErrorHandler = require('./middleware/errorHandler');
+const notFound = require('./middleware/notFound');
+const middleware = require('./middleware');
+const router = require('./router');
+
+const rootDir = path.join(__dirname, '..');
+
+function setup(app, config, logger) {
+  // 静态资源
+  if (config.static && config.static.enable !== false) {
+    const staticPath = path.join(rootDir, 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(rootDir, 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(createErrorHandler(config, logger));
+  app.use(router.routes()).use(router.allowedMethods());
+  app.use(notFound);
+}
+
+module.exports = setup;

package/app.js

@@ -1,119 +1,38 @@
-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}`);
-});
-
+require('dotenv').config();
+
+const Koa = require('koa');
+const { loadConfig } = require('./config/loader');
+const { createLogger } = require('./app/lib/logger');
+const setup = require('./app/setup');
+const setupProcessEvents = require('./app/processEvents');
+
+const config = loadConfig();
+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;
+
+setup(app, config, logger);
+
+app.on('error', (err, ctx) => {
+  logger.error('Server error event', {
+    requestId: ctx && ctx.state && ctx.state.requestId,
+    message: err.message,
+    stack: err.stack
+  });
+});
+
+setupProcessEvents(logger);
+
+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,83 +1,83 @@
-/**
- * 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'
-  }
+/**
+ * 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/config/loader.js

@@ -0,0 +1,25 @@
+/**
+ * 配置加载器：合并 default + 环境配置
+ */
+const path = require('path');
+
+const defaultConfig = require('./config.default');
+
+function loadConfig() {
+  const env = process.env.NODE_ENV || 'development';
+  let envConfig = {};
+
+  try {
+    if (env === 'production') {
+      envConfig = require('./config.prod');
+    } else if (env === 'local' || env === 'development') {
+      envConfig = require('./config.local');
+    }
+  } catch (e) {
+    // 忽略缺失的环境配置文件
+  }
+
+  return Object.assign({}, defaultConfig, envConfig);
+}
+
+module.exports = { loadConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koa3-cli",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "Koa3脚手架",
   "main": "app.js",
   "bin": {

package/public/index.html

@@ -69,6 +69,10 @@
               <h3>✅ 错误处理</h3>
               <p>统一的错误处理机制</p>
             </div>
+            <div class="feature">
+              <h3>📝 日志系统</h3>
+              <p>支持访问日志、错误日志和 requestId 链路追踪</p>
+            </div>
             <div class="feature">
               <h3>⚡ CLI 工具</h3>
               <p>一键创建项目，快速上手</p>
@@ -144,7 +148,10 @@ npm run dev</code></pre>
 │   │   └── user.js        # 用户模型
 │   ├── middleware/        # 中间件目录
 │   │   ├── index.js       # 中间件入口
-│   │   └── auth.js        # 认证中间件示例
+│   │   ├── auth.js        # 认证中间件示例
+│   │   └── requestLogger.js # 请求日志中间件
+│   ├── lib/               # 基础能力目录
+│   │   └── logger.js      # 日志工具
 │   ├── router.js          # 路由配置
 │   └── view/              # 视图模板目录（可选）
 │       └── docs.ejs       # 页面模板
@@ -157,6 +164,7 @@ npm run dev</code></pre>
 ├── public/                # 静态资源目录
 │   ├── docs/              # 文档资源
 │   └── index.html         # 文档首页
+├── logs/                  # 日志目录（运行时自动创建）
 ├── app.js                 # 应用入口文件
 ├── package.json           # 项目配置
 ├── env.example            # 环境变量示例
@@ -237,7 +245,16 @@ REDIS_PASSWORD=
 REDIS_DB=0
 
 # 日志级别
-LOG_LEVEL=info</code></pre>
+LOG_LEVEL=info
+
+# 日志目录
+LOG_DIR=logs
+
+# 是否输出到控制台
+LOG_ENABLE_CONSOLE=true
+
+# 是否输出到文件
+LOG_ENABLE_FILE=true</code></pre>
         <h2>配置项说明</h2>
         <h3>基础配置</h3>
         <pre><code class="language-javascript">{
@@ -288,11 +305,26 @@ LOG_LEVEL=info</code></pre>
   password: '',
   db: 0
 }</code></pre>
-        <h3>日志配置</h3>
-        <pre><code class="language-javascript">logger: {
+<h3>日志配置</h3>
+<pre><code class="language-javascript">logger: {
   level: 'info',              // 日志级别: debug, info, warn, error
-  dir: 'logs'                 // 日志目录
+  dir: 'logs',                // 日志目录
+  enableConsole: true,        // 是否输出到控制台
+  enableFile: true            // 是否输出到文件
 }</code></pre>
+        <h3>日志文件说明</h3>
+        <ul>
+          <li><code>YYYY-MM-DD.log</code>: 通用应用日志</li>
+          <li><code>YYYY-MM-DD.access.log</code>: 请求访问日志（JSON 行格式）</li>
+          <li><code>YYYY-MM-DD.error.log</code>: 错误级别日志</li>
+        </ul>
+        <h3>请求追踪（x-request-id）</h3>
+        <p>每个请求都会自动记录 <code>requestId</code>：</p>
+        <ul>
+          <li>请求头带有 <code>x-request-id</code> 时会透传该值</li>
+          <li>未提供时服务端会自动生成并在响应头返回</li>
+          <li>访问日志与错误日志都会带上 <code>requestId</code>，便于串联排查</li>
+        </ul>
       </div>
 
       <!-- 开发指南 -->