koa3-cli 1.0.5 → 1.0.7

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,14 @@ npm run dev</code></pre>
 │   │   └── user.js        # 用户模型
 │   ├── middleware/        # 中间件目录
 │   │   ├── index.js       # 中间件入口
-│   │   └── auth.js        # 认证中间件示例
+│   │   ├── auth.js        # 认证中间件示例
+│   │   ├── requestLogger.js # 请求日志中间件
+│   │   └── errorHandler.js  # 全局错误处理
+│   ├── lib/               # 基础能力目录
+│   │   ├── logger.js      # 日志工具
+│   │   └── validator.js   # 参数校验中间件（Joi）
+│   ├── schema/            # 参数校验规则目录
+│   │   └── user.js        # 用户相关校验规则
 │   ├── router.js          # 路由配置
 │   └── view/              # 视图模板目录（可选）
 │       └── docs.ejs       # 页面模板
@@ -157,6 +168,7 @@ npm run dev</code></pre>
 ├── public/                # 静态资源目录
 │   ├── docs/              # 文档资源
 │   └── index.html         # 文档首页
+├── logs/                  # 日志目录（运行时自动创建）
 ├── app.js                 # 应用入口文件
 ├── package.json           # 项目配置
 ├── env.example            # 环境变量示例
@@ -237,7 +249,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 +309,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>
 
       <!-- 开发指南 -->
@@ -390,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">// 抛出错误
@@ -397,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>
@@ -437,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>
@@ -471,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>
@@ -480,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>
@@ -502,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>
@@ -531,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>
@@ -550,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>
@@ -568,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,
@@ -590,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>
@@ -605,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"