koa3-cli 1.0.6 → 1.0.8

package/README.md

@@ -50,9 +50,13 @@ koa3-cli/
 │   ├── middleware/        # 中间件目录
 │   │   ├── index.js       # 中间件入口
 │   │   ├── auth.js        # 认证中间件示例
-│   │   └── requestLogger.js # 请求日志中间件
+│   │   ├── requestLogger.js # 请求日志中间件
+│   │   └── errorHandler.js  # 全局错误处理
 │   ├── lib/               # 基础能力目录
-│   │   └── logger.js      # 日志工具
+│   │   ├── logger.js      # 日志工具
+│   │   └── validator.js   # 参数校验中间件（Joi）
+│   ├── schema/            # 参数校验规则目录
+│   │   └── user.js        # 用户相关校验规则
 │   └── router.js          # 路由配置
 ├── config/                # 配置文件目录
 │   ├── config.default.js  # 默认配置
@@ -74,8 +78,9 @@ koa3-cli/
 - ✅ 支持多环境配置（development/production）
 - ✅ MVC 架构（Controller/Service/Model）
 - ✅ 中间件支持
-- ✅ 统一的错误处理
+- ✅ 统一的错误处理（校验失败返回 422，message 为第一条校验提示）
 - ✅ 内置日志系统（访问日志、错误日志、请求追踪）
+- ✅ 基于 Joi 的参数校验（body/query/params，校验结果挂到 `ctx.state.validated`）
 - ✅ RESTful API 示例
 
 ## 快速开始
@@ -139,6 +144,57 @@ LOG_ENABLE_FILE=true
 - 如果没有，服务端会自动生成并在响应头返回
 - 出错日志会带上 `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 示例
 
 ### 获取用户列表
@@ -212,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,4 +1,27 @@
-const userService = require('../service/user');
+const userService = require('../service/user');
+const { Joi, validateValue } = require('../lib/validator');
+
+const idParamSchema = Joi.object({
+  id: Joi.string().required().messages({ 'any.required': '用户 id 不能为空' })
+});
+
+const createUserBodySchema = Joi.object({
+  name: Joi.string().trim().min(1).max(100).required().messages({
+    'any.required': '用户名为必填',
+    'string.empty': '用户名不能为空',
+    'string.max': '用户名不能超过 100 个字符'
+  }),
+  email: Joi.string().email().allow('').optional(),
+  age: Joi.number().integer().min(0).max(150).optional()
+}).options({ stripUnknown: true });
+
+const updateUserBodySchema = Joi.object({
+  name: Joi.string().trim().min(1).max(100).optional(),
+  email: Joi.string().email().allow('').optional(),
+  age: Joi.number().integer().min(0).max(150).optional()
+}).min(1).messages({
+  'object.min': '至少需要提供一个要更新的字段'
+}).options({ stripUnknown: true });
 
 function logMeta(ctx, extra = {}) {
   return {
@@ -22,7 +45,7 @@ class UserController {
   }
 
   async detail(ctx) {
-    const { id } = ctx.params;
+    const { id } = await validateValue(idParamSchema, ctx.params);
 
     try {
       const user = await userService.getUserById(id);
@@ -42,7 +65,7 @@ class UserController {
   }
 
   async create(ctx) {
-    const userData = ctx.request.body;
+    const userData = await validateValue(createUserBodySchema, ctx.request.body);
 
     try {
       const user = await userService.createUser(userData);
@@ -56,8 +79,8 @@ class UserController {
   }
 
   async update(ctx) {
-    const { id } = ctx.params;
-    const userData = ctx.request.body;
+    const { id } = await validateValue(idParamSchema, ctx.params);
+    const userData = await validateValue(updateUserBodySchema, ctx.request.body);
 
     try {
       const user = await userService.updateUser(id, userData);
@@ -77,7 +100,7 @@ class UserController {
   }
 
   async delete(ctx) {
-    const { id } = ctx.params;
+    const { id } = await validateValue(idParamSchema, ctx.params);
 
     try {
       const result = await userService.deleteUser(id);

package/app/lib/validator.js

@@ -0,0 +1,70 @@
+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();
+  };
+}
+
+/**
+ * 在控制器内校验单个对象，失败时抛出与 validate() 中间件相同形态的 422 错误
+ */
+async function validateValue(schema, value, validateOptions = { stripUnknown: true }) {
+  try {
+    return await schema.validateAsync(value ?? {}, validateOptions);
+  } 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;
+  }
+}
+
+module.exports = {
+  validate,
+  validateValue,
+  Joi
+};

package/app/middleware/errorHandler.js

@@ -7,10 +7,11 @@ module.exports = function createErrorHandler(config, logger) {
       await next();
     } catch (err) {
       ctx.status = err.status || 500;
+      const firstDetailMessage = err.details && err.details[0] && err.details[0].message;
       ctx.body = {
         success: false,
-        message: err.message || 'Internal Server Error',
-        ...(config.env === 'development' && { stack: err.stack })
+        message: firstDetailMessage || err.message || 'Internal Server Error',
+        ...(err.details && { errors: err.details })
       };
 
       logger.error('Request failed', {

package/app/router.js

@@ -1,4 +1,5 @@
 const { Router } = require('@koa/router');
+
 const router = new Router();
 
 // 加载控制器

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koa3-cli",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "Koa3脚手架",
   "main": "app.js",
   "bin": {
@@ -29,6 +29,7 @@
     "@ladjs/koa-views": "^9.0.0",
     "dotenv": "^17.3.1",
     "ejs": "^4.0.1",
+    "joi": "^17.13.3",
     "koa": "^3.1.2",
     "koa-bodyparser": "^4.4.1",
     "koa-cors": "^0.0.16",

package/public/index.html

@@ -149,9 +149,13 @@ npm run dev</code></pre>
 │   ├── middleware/        # 中间件目录
 │   │   ├── index.js       # 中间件入口
 │   │   ├── auth.js        # 认证中间件示例
-│   │   └── requestLogger.js # 请求日志中间件
+│   │   ├── requestLogger.js # 请求日志中间件
+│   │   └── errorHandler.js  # 全局错误处理
 │   ├── lib/               # 基础能力目录
-│   │   └── logger.js      # 日志工具
+│   │   ├── logger.js      # 日志工具
+│   │   └── validator.js   # 参数校验中间件（Joi）
+│   ├── schema/            # 参数校验规则目录
+│   │   └── user.js        # 用户相关校验规则
 │   ├── router.js          # 路由配置
 │   └── view/              # 视图模板目录（可选）
 │       └── docs.ejs       # 页面模板
@@ -422,6 +426,15 @@ module.exports = async (ctx, next) => {
   await logger(ctx, next);
   // 其他中间件...
 };</code></pre>
+        <h2>添加参数校验</h2>
+        <p>使用 Joi 在路由上挂载 <code>validate(schemas)</code>，按需校验 <code>body</code>、<code>query</code>、<code>params</code>。校验通过后从 <code>ctx.state.validated</code> 读取数据。</p>
+        <pre><code class="language-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);
+router.put('/api/user/:id', validate({ params: userSchema.idParam, body: userSchema.updateUserBody }), userController.update);</code></pre>
+        <p>校验规则定义在 <code>app/schema/</code> 下（如 <code>user.js</code>），使用 Joi 编写，支持 <code>.messages()</code> 自定义提示。校验未通过时返回 422，<code>message</code> 为第一条未通过项的提示，<code>errors</code> 为全部校验项。</p>
         <h2>错误处理</h2>
         <p>控制器中的错误会自动被错误处理中间件捕获：</p>
         <pre><code class="language-javascript">// 抛出错误
@@ -429,11 +442,19 @@ ctx.throw(400, 'Bad Request');
 
 // 或者
 throw new Error('Something went wrong');</code></pre>
-        <p>错误会被统一处理并返回：</p>
+        <p>错误会被统一处理并返回。普通错误：</p>
         <pre><code class="language-json">{
   "success": false,
   "message": "Error message",
   "stack": "..." // 仅在开发环境显示
+}</code></pre>
+        <p>参数校验失败（422）时，<code>message</code> 为第一条校验提示，<code>errors</code> 为所有校验项：</p>
+        <pre><code class="language-json">{
+  "success": false,
+  "message": "用户名为必填",
+  "errors": [
+    { "field": "name", "message": "用户名为必填" }
+  ]
 }</code></pre>
         <h2>响应格式</h2>
         <p>API 请求会自动统一响应格式：</p>
@@ -469,6 +490,15 @@ throw new Error('Something went wrong');</code></pre>
   "success": false,
   "message": "错误信息",
   "stack": "..." // 仅在开发环境显示
+}</code></pre>
+        <h3>参数校验失败（422）</h3>
+        <p><code>message</code> 为第一条未通过项的提示，<code>errors</code> 为全部校验项：</p>
+        <pre><code class="language-json">{
+  "success": false,
+  "message": "用户名为必填",
+  "errors": [
+    { "field": "name", "message": "用户名为必填" }
+  ]
 }</code></pre>
         <h2>API 列表</h2>
         <ul>
@@ -503,7 +533,7 @@ throw new Error('Something went wrong');</code></pre>
   ]
 }</code></pre>
         <h2>获取用户详情</h2>
-        <p>根据用户 ID 获取用户详情。</p>
+        <p>根据用户 ID 获取用户详情。路径参数 <code>id</code> 会经过 Joi 校验，缺失或非法时返回 422。</p>
         <h3>请求</h3>
         <pre><code class="language-http">GET /api/user/:id</code></pre>
         <h3>路径参数</h3>
@@ -512,13 +542,15 @@ throw new Error('Something went wrong');</code></pre>
             <tr>
               <th>参数</th>
               <th>类型</th>
+              <th>必填</th>
               <th>说明</th>
             </tr>
           </thead>
           <tbody>
             <tr>
               <td>id</td>
-              <td>number</td>
+              <td>string</td>
+              <td>是</td>
               <td>用户ID</td>
             </tr>
           </tbody>
@@ -534,12 +566,19 @@ throw new Error('Something went wrong');</code></pre>
   }
 }</code></pre>
         <h3>错误响应</h3>
+        <p>404 用户不存在：</p>
         <pre><code class="language-json">{
   "success": false,
   "message": "User not found"
+}</code></pre>
+        <p>422 参数校验失败（如 id 为空）：</p>
+        <pre><code class="language-json">{
+  "success": false,
+  "message": "用户 id 不能为空",
+  "errors": [{ "field": "id", "message": "用户 id 不能为空" }]
 }</code></pre>
         <h2>创建用户</h2>
-        <p>创建新用户。</p>
+        <p>创建新用户。请求体会经过 Joi 校验（<code>name</code> 必填、长度等），未通过返回 422。</p>
         <h3>请求</h3>
         <pre><code class="language-http">POST /api/user
 Content-Type: application/json</code></pre>
@@ -563,14 +602,20 @@ Content-Type: application/json</code></pre>
               <td>name</td>
               <td>string</td>
               <td>是</td>
-              <td>用户姓名</td>
+              <td>用户姓名（1～100 字符）</td>
             </tr>
             <tr>
               <td>email</td>
               <td>string</td>
-              <td>是</td>
+              <td>否</td>
               <td>用户邮箱</td>
             </tr>
+            <tr>
+              <td>age</td>
+              <td>number</td>
+              <td>否</td>
+              <td>年龄（0～150）</td>
+            </tr>
           </tbody>
         </table>
         <h3>响应</h3>
@@ -582,9 +627,15 @@ Content-Type: application/json</code></pre>
     "email": "zhangsan@example.com",
     "createdAt": "2024-01-01T00:00:00.000Z"
   }
+}</code></pre>
+        <h3>校验失败（422）</h3>
+        <pre><code class="language-json">{
+  "success": false,
+  "message": "用户名为必填",
+  "errors": [{ "field": "name", "message": "用户名为必填" }]
 }</code></pre>
         <h2>更新用户</h2>
-        <p>更新用户信息。</p>
+        <p>更新用户信息。路径参数与请求体均会校验，至少需提供一个要更新的字段。</p>
         <h3>请求</h3>
         <pre><code class="language-http">PUT /api/user/:id
 Content-Type: application/json</code></pre>
@@ -600,16 +651,18 @@ Content-Type: application/json</code></pre>
           <tbody>
             <tr>
               <td>id</td>
-              <td>number</td>
-              <td>用户ID</td>
+              <td>string</td>
+              <td>用户ID（必填）</td>
             </tr>
           </tbody>
         </table>
         <h3>请求体</h3>
         <pre><code class="language-json">{
   "name": "李四",
-  "email": "lisi@example.com"
+  "email": "lisi@example.com",
+  "age": 25
 }</code></pre>
+        <p>可选字段：<code>name</code>（1～100 字符）、<code>email</code>、<code>age</code>（0～150），至少填一项。</p>
         <h3>响应</h3>
         <pre><code class="language-json">{
   "success": true,
@@ -622,7 +675,7 @@ Content-Type: application/json</code></pre>
   }
 }</code></pre>
         <h2>删除用户</h2>
-        <p>删除指定用户。</p>
+        <p>删除指定用户。路径参数 <code>id</code> 会经过校验。</p>
         <h3>请求</h3>
         <pre><code class="language-http">DELETE /api/user/:id</code></pre>
         <h3>路径参数</h3>
@@ -637,14 +690,15 @@ Content-Type: application/json</code></pre>
           <tbody>
             <tr>
               <td>id</td>
-              <td>number</td>
-              <td>用户ID</td>
+              <td>string</td>
+              <td>用户ID（必填）</td>
             </tr>
           </tbody>
         </table>
         <h3>响应</h3>
         <pre><code class="language-http">204 No Content</code></pre>
         <h3>错误响应</h3>
+        <p>404 用户不存在 / 422 参数校验失败（格式同获取用户详情）。</p>
         <pre><code class="language-json">{
   "success": false,
   "message": "User not found"