koa3-cli 1.0.4 → 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,86 +1,97 @@
-/**
- * 用户控制器
- */
-const userService = require('../service/user');
+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 { id } = ctx.params;
       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 userData = ctx.request.body;
       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 { id } = ctx.params;
-      const userData = ctx.request.body;
       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 { id } = ctx.params;
       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);
     }
   }

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/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

@@ -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/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,111 +1,38 @@
-const Koa = require('koa');
-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 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();
-
-// 应用配置
-app.keys = config.keys || ['koa3-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`);
+const logger = createLogger({
+  ...(config.logger || {}),
+  appName: config.name || 'koa3-cli',
+  cwd: __dirname
 });
 
-// 注册路由
-app.use(router.routes()).use(router.allowedMethods());
+app.keys = config.keys || ['koa3-cli-secret-key'];
+app.context.logger = logger;
 
-// 404 处理（必须在路由之后）
-app.use(async (ctx) => {
-  if (ctx.status === 404) {
-    ctx.body = {
-      success: false,
-      message: 'Not Found'
-    };
-  }
-});
+setup(app, config, logger);
 
-// 错误事件监听
 app.on('error', (err, ctx) => {
-  console.error('Server error:', err);
+  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, () => {
-  console.log(`Server is running on http://localhost:${port}`);
-  console.log(`Environment: ${config.env}`);
+  logger.info(`Server is running on http://localhost:${port}`);
+  logger.info(`Environment: ${config.env}`);
 });
 
 module.exports = app;

package/config/config.default.js

@@ -1,37 +1,36 @@
 /**
- * 默认配置文件
- * 所有环境都会加载此配置
+ * Default config loaded in all environments.
  */
 module.exports = {
-  // 应用名称
+  // Application name
   name: 'koa3-cli',
-  
-  // 运行环境: development, production, test
+
+  // Runtime env: development, production, test
   env: process.env.NODE_ENV || 'development',
-  
-  // 服务端口
+
+  // Server port
   port: process.env.PORT || 3000,
-  
-  // 密钥，用于加密cookie等
+
+  // 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, // 1年
+      maxAge: 365 * 24 * 60 * 60 * 1000,
       gzip: true
     }
   },
-  
-  // VuePress 文档配置
+
+  // Docs build config
   docs: {
     enable: true,
     buildDir: 'public/docs'
   },
-  
-  // 视图配置
+
+  // View engine
   view: {
     enable: true,
     root: 'app/view',
@@ -42,15 +41,15 @@ module.exports = {
       }
     }
   },
-  
-  // bodyParser配置
+
+  // bodyParser
   bodyParser: {
     enableTypes: ['json', 'form', 'text'],
     jsonLimit: '10mb',
     formLimit: '10mb'
   },
-  
-  // 数据库配置（示例）
+
+  // Database (example)
   database: {
     client: 'mysql',
     connection: {
@@ -65,18 +64,20 @@ module.exports = {
       max: 10
     }
   },
-  
-  // Redis配置（示例）
+
+  // 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: 'logs'
+    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/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,6 +1,6 @@
 {
   "name": "koa3-cli",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Koa3脚手架",
   "main": "app.js",
   "bin": {
@@ -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"

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>
 
       <!-- 开发指南 -->