koa3-cli 1.0.5 → 1.0.7

package/README.md

@@ -49,12 +49,20 @@ koa3-cli/
 │   │   └── user.js        # 用户模型
 │   ├── middleware/        # 中间件目录
 │   │   ├── index.js       # 中间件入口
-│   │   └── auth.js        # 认证中间件示例
+│   │   ├── auth.js        # 认证中间件示例
+│   │   ├── requestLogger.js # 请求日志中间件
+│   │   └── errorHandler.js  # 全局错误处理
+│   ├── lib/               # 基础能力目录
+│   │   ├── logger.js      # 日志工具
+│   │   └── validator.js   # 参数校验中间件（Joi）
+│   ├── schema/            # 参数校验规则目录
+│   │   └── user.js        # 用户相关校验规则
 │   └── router.js          # 路由配置
 ├── config/                # 配置文件目录
 │   ├── config.default.js  # 默认配置
 │   ├── config.local.js    # 本地开发配置
 │   └── config.prod.js     # 生产环境配置
+├── logs/                  # 日志输出目录（运行时自动创建）
 ├── public/                # 静态资源目录
 │   └── index.html         # 首页
 ├── app.js                 # 应用入口文件
@@ -70,7 +78,9 @@ koa3-cli/
 - ✅ 支持多环境配置（development/production）
 - ✅ MVC 架构（Controller/Service/Model）
 - ✅ 中间件支持
-- ✅ 统一的错误处理
+- ✅ 统一的错误处理（校验失败返回 422，message 为第一条校验提示）
+- ✅ 内置日志系统（访问日志、错误日志、请求追踪）
+- ✅ 基于 Joi 的参数校验（body/query/params，校验结果挂到 `ctx.state.validated`）
 - ✅ RESTful API 示例
 
 ## 快速开始
@@ -109,6 +119,82 @@ 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`，便于串联排查
+
+## 参数校验
+
+使用 Joi 进行请求参数校验，通过 `app/lib/validator.js` 的 `validate(schemas)` 生成中间件。
+
+### 使用方式
+
+在路由中挂载校验中间件，按需校验 `body`、`query`、`params`：
+
+```javascript
+const { validate } = require('./lib/validator');
+const userSchema = require('./schema/user');
+
+// 只校验路径参数
+router.get('/api/user/:id', validate({ params: userSchema.idParam }), userController.detail);
+
+// 只校验请求体
+router.post('/api/user', validate({ body: userSchema.createUserBody }), userController.create);
+
+// 同时校验 params + body
+router.put('/api/user/:id', validate({
+  params: userSchema.idParam,
+  body: userSchema.updateUserBody
+}), userController.update);
+```
+
+校验通过后，结果在 **`ctx.state.validated`** 中：
+
+- `ctx.state.validated.body`：校验后的 body
+- `ctx.state.validated.query`：校验后的 query
+- `ctx.state.validated.params`：校验后的 params
+
+控制器中应优先使用 `ctx.state.validated`，未走校验的路由可继续使用 `ctx.request.body` / `ctx.params`。
+
+### 校验失败响应
+
+校验未通过时返回 **422**，`message` 为**第一条**未通过项的提示，`errors` 为全部校验项：
+
+```json
+{
+  "success": false,
+  "message": "用户名为必填",
+  "errors": [
+    { "field": "name", "message": "用户名为必填" }
+  ]
+}
+```
+
+### 添加新的校验规则
+
+在 `app/schema/` 下新增或修改 schema 文件，使用 Joi 定义规则（支持 `.messages()` 自定义提示），在路由中通过 `validate({ body: xxx })` 等引用即可。详见 `app/schema/user.js`。
+
 ## API 示例
 
 ### 获取用户列表
@@ -182,11 +268,18 @@ router.get('/api/product', productController.list);
 
 在 `app/middleware/` 目录下创建中间件文件，然后在 `app/middleware/index.js` 中引入使用。
 
+### 添加参数校验
+
+1. 在 `app/schema/` 下定义 Joi 规则（可参考 `app/schema/user.js`）
+2. 在 `app/router.js` 中为对应路由添加 `validate({ body, query, params })` 中间件
+3. 在控制器中从 `ctx.state.validated` 读取已校验数据
+
 ## 技术栈
 
 - **Koa3**: Web 框架
 - **@koa/router**: 路由
 - **koa-bodyparser**: 请求体解析
+- **joi**: 参数校验（body/query/params）
 - **koa-static**: 静态资源服务
 - **koa-views**: 模板引擎支持
 - **dotenv**: 环境变量管理

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.state.validated ? ctx.state.validated.params : 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.state.validated ? ctx.state.validated.body : 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.state.validated ? ctx.state.validated.params : ctx.params;
+    const userData = ctx.state.validated ? ctx.state.validated.body : 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.state.validated ? ctx.state.validated.params : 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/lib/validator.js

@@ -0,0 +1,49 @@
+const Joi = require('joi');
+
+/**
+ * 根据 schemas 生成 Koa 参数校验中间件
+ * @param {Object} schemas - { body?: Joi.Schema, query?: Joi.Schema, params?: Joi.Schema }
+ * @returns {Function} Koa middleware
+ *
+ * 校验通过后，结果会挂到 ctx.state.validated 上：
+ *   ctx.state.validated.body / .query / .params
+ */
+function validate(schemas = {}) {
+  return async function validateMiddleware(ctx, next) {
+    const result = {};
+
+    try {
+      if (schemas.body) {
+        const value = ctx.request.body ?? {};
+        result.body = await schemas.body.validateAsync(value, { stripUnknown: true });
+      }
+      if (schemas.query) {
+        const value = ctx.query ?? {};
+        result.query = await schemas.query.validateAsync(value, { stripUnknown: true });
+      }
+      if (schemas.params) {
+        const value = ctx.params ?? {};
+        result.params = await schemas.params.validateAsync(value, { stripUnknown: true });
+      }
+    } catch (err) {
+      if (!Joi.isError(err)) {
+        throw err;
+      }
+      const validationError = new Error(err.message || 'Validation Failed');
+      validationError.status = 422;
+      validationError.details = err.details.map(d => ({
+        field: d.path.join('.'),
+        message: d.message
+      }));
+      throw validationError;
+    }
+
+    ctx.state.validated = result;
+    await next();
+  };
+}
+
+module.exports = {
+  validate,
+  Joi
+};