npm - koa3-cli - Versions diffs - 1.0.0 - Mend

koa3-cli 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

package/public/index.html ADDED Viewed

@@ -0,0 +1,608 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Koa3 CLI 文档</title>
+  <!-- Prism.js 代码高亮 -->
+  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/themes/prism-tomorrow.min.css">
+  <!-- 文档样式文件 - 修改 docs.css 来调整样式 -->
+  <link rel="stylesheet" href="/docs/docs.css">
+</head>
+<body>
+  <!-- 顶部导航栏 -->
+  <nav class="navbar">
+    <button class="menu-toggle" onclick="toggleSidebar()">☰</button>
+    <a href="#" class="navbar-brand" onclick="showHome(); return false;">Koa3 CLI</a>
+    <div style="margin-left: auto; display: flex; gap: 1rem; align-items: center;">
+      <a href="https://gitee.com/wangziwl/koa3-cli" target="_blank" style="color: #2c3e50; text-decoration: none; font-size: 0.9rem;">🔗 Gitee</a>
+    </div>
+  </nav>
+  <!-- 侧边栏 - 导航菜单由 docs-content.js 动态生成 -->
+  <aside class="sidebar" id="sidebar">
+    <!-- 导航菜单将在这里动态生成 -->
+  </aside>
+  <!-- 主内容区 -->
+  <main class="main">
+    <div class="content">
+      <!-- ============================================
+           文档内容区域
+           修改下面的内容来更新文档
+           ============================================ -->
+      <!-- 首页 -->
+      <div id="home" class="content-section active">
+        <div class="home">
+          <div class="hero">
+            <h1>Koa3 CLI</h1>
+            <p>基于 Koa3 的脚手架项目</p>
+            <p class="info-text">2025年4月28日，Node.js 生态圈迎来了一场重磅升级——Koa.js 3.0 正式发布！自2017年启动开发计划，历经8年长跑，由 Express 原班人马打造的经典轻量级 Web 框架，终于以全新姿态回归视野。Koa 3.0 不仅是一次版本号的跃迁，更是 Node.js 现代化进程的重要里程碑。</p>
+            <div style="margin: 1.5rem 0;">
+              <a href="https://gitee.com/wangziwl/koa3-cli" target="_blank" style="color: #3eaf7c; text-decoration: none; margin-right: 1rem;">🔗 Gitee 仓库</a>
+            </div>
+            <a href="#" class="action-button" onclick="showContent('getting-started'); return false;">快速开始 →</a>
+          </div>
+          <div class="features">
+            <div class="feature">
+              <h3>🚀 轻量高效</h3>
+              <p>基于 Koa3，性能优异，代码简洁</p>
+            </div>
+            <div class="feature">
+              <h3>📁 清晰结构</h3>
+              <p>规范统一，易于维护</p>
+            </div>
+            <div class="feature">
+              <h3>🔧 多环境配置</h3>
+              <p>支持 development/production 环境配置</p>
+            </div>
+            <div class="feature">
+              <h3>🏗️ MVC 架构</h3>
+              <p>Controller/Service/Model 分层清晰</p>
+            </div>
+            <div class="feature">
+              <h3>🔌 中间件支持</h3>
+              <p>灵活的中间件系统，易于扩展</p>
+            </div>
+            <div class="feature">
+              <h3>✅ 错误处理</h3>
+              <p>统一的错误处理机制</p>
+            </div>
+          </div>
+        </div>
+      </div>
+      <!-- 快速开始 -->
+      <div id="getting-started" class="content-section">
+        <h1>快速开始</h1>
+        <h2>安装依赖</h2>
+        <pre><code class="language-bash">npm install</code></pre>
+        <h2>启动项目</h2>
+        <h3>开发环境</h3>
+        <p>使用 nodemon 自动重启：</p>
+        <pre><code class="language-bash">npm run dev</code></pre>
+        <h3>生产环境</h3>
+        <pre><code class="language-bash">npm start</code></pre>
+        <h2>访问应用</h2>
+        <p>启动成功后，你可以访问：</p>
+        <ul>
+          <li><strong>首页</strong>: http://localhost:3000</li>
+          <li><strong>API 示例</strong>: http://localhost:3000/api/user</li>
+          <li><strong>文档</strong>: http://localhost:3000/index.html</li>
+        </ul>
+        <h2>环境配置</h2>
+        <p>项目支持多环境配置，通过 <code>NODE_ENV</code> 环境变量控制：</p>
+        <ul>
+          <li><code>development</code> 或 <code>local</code>: 加载 <code>config.local.js</code></li>
+          <li><code>production</code>: 加载 <code>config.prod.js</code></li>
+          <li>默认: 加载 <code>config.default.js</code></li>
+        </ul>
+        <p>可以通过 <code>.env</code> 文件配置环境变量（参考 <code>env.example</code>）。</p>
+        <h2>下一步</h2>
+        <ul>
+          <li>了解 <a href="#" onclick="showContent('project-structure'); return false;">项目结构</a></li>
+          <li>查看 <a href="#" onclick="showContent('configuration'); return false;">配置说明</a></li>
+          <li>阅读 <a href="#" onclick="showContent('development'); return false;">开发指南</a></li>
+        </ul>
+      </div>
+      <!-- 项目结构 -->
+      <div id="project-structure" class="content-section">
+        <h1>项目结构</h1>
+        <pre><code class="language-text">koa3-cli/
+├── app/                    # 应用代码目录
+│   ├── controller/        # 控制器目录
+│   │   ├── home.js        # 首页控制器
+│   │   ├── user.js        # 用户控制器
+│   │   └── docs.js        # 文档控制器
+│   ├── service/           # 服务层目录
+│   │   └── user.js        # 用户服务
+│   ├── model/             # 数据模型目录
+│   │   └── user.js        # 用户模型
+│   ├── middleware/        # 中间件目录
+│   │   ├── index.js       # 中间件入口
+│   │   └── auth.js        # 认证中间件示例
+│   ├── router.js          # 路由配置
+│   └── view/              # 视图模板目录（可选）
+│       └── docs.ejs       # 页面模板
+├── config/                # 配置文件目录
+│   ├── config.default.js  # 默认配置
+│   ├── config.local.js    # 本地开发配置
+│   └── config.prod.js     # 生产环境配置
+├── public/                # 静态资源目录
+│   └── index.html         # 首页
+├── app.js                 # 应用入口文件
+├── package.json           # 项目配置
+└── README.md             # 项目说明</code></pre>
+        <h2>目录说明</h2>
+        <h3>app/</h3>
+        <p>应用代码目录，包含所有业务逻辑代码。</p>
+        <h4>controller/</h4>
+        <p>控制器目录，处理 HTTP 请求和响应。</p>
+        <pre><code class="language-javascript">// app/controller/user.js
+class UserController {
+  async list(ctx) {
+    ctx.body = await userService.getUserList();
+  }
+}</code></pre>
+        <h4>service/</h4>
+        <p>服务层目录，处理业务逻辑。</p>
+        <pre><code class="language-javascript">// app/service/user.js
+class UserService {
+  async getUserList() {
+    return await userModel.findAll();
+  }
+}</code></pre>
+        <h4>model/</h4>
+        <p>数据模型目录，处理数据访问。</p>
+        <pre><code class="language-javascript">// app/model/user.js
+class UserModel {
+  async findAll() {
+    // 数据库查询逻辑
+  }
+}</code></pre>
+        <h4>middleware/</h4>
+        <p>中间件目录，处理请求预处理和后处理。</p>
+        <pre><code class="language-javascript">// app/middleware/index.js
+module.exports = async (ctx, next) => {
+  // 中间件逻辑
+  await next();
+};</code></pre>
+        <h3>config/</h3>
+        <p>配置文件目录，包含不同环境的配置。</p>
+        <h3>public/</h3>
+        <p>静态资源目录，存放静态文件。</p>
+      </div>
+      <!-- 配置说明 -->
+      <div id="configuration" class="content-section">
+        <h1>配置说明</h1>
+        <h2>环境配置</h2>
+        <p>项目支持多环境配置，通过 <code>NODE_ENV</code> 环境变量控制：</p>
+        <ul>
+          <li><code>development</code> 或 <code>local</code>: 加载 <code>config.local.js</code></li>
+          <li><code>production</code>: 加载 <code>config.prod.js</code></li>
+          <li>默认: 加载 <code>config.default.js</code></li>
+        </ul>
+        <p>配置文件会按顺序加载，后面的配置会覆盖前面的配置。</p>
+        <h2>环境变量</h2>
+        <p>可以通过 <code>.env</code> 文件配置环境变量（参考 <code>env.example</code>）：</p>
+        <pre><code class="language-env"># 运行环境
+NODE_ENV=development
+# 服务端口
+PORT=3000
+# 应用密钥（多个密钥用逗号分隔）
+KEYS=your-secret-key-1,your-secret-key-2
+# 数据库配置
+DB_HOST=localhost
+DB_PORT=3306
+DB_USER=root
+DB_PASSWORD=
+DB_NAME=test
+# Redis配置
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=
+REDIS_DB=0
+# 日志级别
+LOG_LEVEL=info</code></pre>
+        <h2>配置项说明</h2>
+        <h3>基础配置</h3>
+        <pre><code class="language-javascript">{
+  name: 'koa3-cli',           // 应用名称
+  env: 'development',          // 运行环境
+  port: 3000,                 // 服务端口
+  keys: ['secret-key']         // 应用密钥
+}</code></pre>
+        <h3>静态资源配置</h3>
+        <pre><code class="language-javascript">static: {
+  enable: true,                // 是否启用
+  dir: 'public',              // 静态文件目录
+  options: {
+    maxAge: 365 * 24 * 60 * 60 * 1000,  // 缓存时间
+    gzip: true                // 是否启用 gzip
+  }
+}</code></pre>
+        <h3>视图配置</h3>
+        <pre><code class="language-javascript">view: {
+  enable: true,               // 是否启用
+  root: 'app/view',          // 视图文件目录
+  options: {
+    extension: 'ejs',        // 默认扩展名
+    map: {
+      html: 'ejs'            // 文件扩展名映射
+    }
+  }
+}</code></pre>
+        <h3>数据库配置</h3>
+        <pre><code class="language-javascript">database: {
+  client: 'mysql',
+  connection: {
+    host: 'localhost',
+    port: 3306,
+    user: 'root',
+    password: '',
+    database: 'test'
+  },
+  pool: {
+    min: 2,
+    max: 10
+  }
+}</code></pre>
+        <h3>Redis配置</h3>
+        <pre><code class="language-javascript">redis: {
+  host: 'localhost',
+  port: 6379,
+  password: '',
+  db: 0
+}</code></pre>
+        <h3>日志配置</h3>
+        <pre><code class="language-javascript">logger: {
+  level: 'info',              // 日志级别: debug, info, warn, error
+  dir: 'logs'                 // 日志目录
+}</code></pre>
+      </div>
+      <!-- 开发指南 -->
+      <div id="development" class="content-section">
+        <h1>开发指南</h1>
+        <h2>添加新的控制器</h2>
+        <p>1. 在 <code>app/controller/</code> 目录下创建控制器文件</p>
+        <pre><code class="language-javascript">// app/controller/product.js
+const productService = require('../service/product');
+class ProductController {
+  async list(ctx) {
+    try {
+      const products = await productService.getList();
+      ctx.body = products;
+    } catch (error) {
+      ctx.throw(500, error.message);
+    }
+  }
+  async detail(ctx) {
+    const { id } = ctx.params;
+    const product = await productService.getById(id);
+    if (!product) {
+      ctx.status = 404;
+      ctx.body = { message: 'Product not found' };
+      return;
+    }
+    ctx.body = product;
+  }
+}
+module.exports = new ProductController();</code></pre>
+        <p>2. 在 <code>app/router.js</code> 中注册路由</p>
+        <pre><code class="language-javascript">const productController = require('./controller/product');
+router.get('/api/product', productController.list);
+router.get('/api/product/:id', productController.detail);</code></pre>
+        <h2>添加新的服务</h2>
+        <p>在 <code>app/service/</code> 目录下创建服务文件，处理业务逻辑：</p>
+        <pre><code class="language-javascript">// app/service/product.js
+const productModel = require('../model/product');
+class ProductService {
+  async getList() {
+    return await productModel.findAll();
+  }
+  async getById(id) {
+    return await productModel.findById(id);
+  }
+  async create(productData) {
+    // 数据验证
+    if (!productData.name) {
+      throw new Error('Product name is required');
+    }
+    return await productModel.create(productData);
+  }
+}
+module.exports = new ProductService();</code></pre>
+        <h2>添加新的模型</h2>
+        <p>在 <code>app/model/</code> 目录下创建模型文件，处理数据访问：</p>
+        <pre><code class="language-javascript">// app/model/product.js
+class ProductModel {
+  async findAll() {
+    // 数据库查询逻辑
+    // return await db.query('SELECT * FROM products');
+  }
+  async findById(id) {
+    // return await db.query('SELECT * FROM products WHERE id = ?', [id]);
+  }
+  async create(productData) {
+    // return await db.insert('products', productData);
+  }
+}
+module.exports = new ProductModel();</code></pre>
+        <h2>添加中间件</h2>
+        <p>在 <code>app/middleware/</code> 目录下创建中间件文件：</p>
+        <pre><code class="language-javascript">// app/middleware/logger.js
+module.exports = async (ctx, next) => {
+  const start = Date.now();
+  await next();
+  const ms = Date.now() - start;
+  console.log(`${ctx.method} ${ctx.url} - ${ms}ms`);
+};</code></pre>
+        <p>然后在 <code>app/middleware/index.js</code> 中引入使用：</p>
+        <pre><code class="language-javascript">const logger = require('./logger');
+module.exports = async (ctx, next) => {
+  await logger(ctx, next);
+  // 其他中间件...
+};</code></pre>
+        <h2>错误处理</h2>
+        <p>控制器中的错误会自动被错误处理中间件捕获：</p>
+        <pre><code class="language-javascript">// 抛出错误
+ctx.throw(400, 'Bad Request');
+// 或者
+throw new Error('Something went wrong');</code></pre>
+        <p>错误会被统一处理并返回：</p>
+        <pre><code class="language-json">{
+  "success": false,
+  "message": "Error message",
+  "stack": "..." // 仅在开发环境显示
+}</code></pre>
+        <h2>响应格式</h2>
+        <p>API 请求会自动统一响应格式：</p>
+        <pre><code class="language-json">{
+  "success": true,
+  "data": {
+    // 响应数据
+  }
+}</code></pre>
+        <p>如果响应已经是 <code>{ success: true/false }</code> 格式，则不会再次包装。</p>
+      </div>
+      <!-- API 文档首页 -->
+      <div id="api-readme" class="content-section">
+        <h1>API 文档</h1>
+        <p>本文档描述了 Koa3 CLI 提供的所有 API 接口。</p>
+        <h2>基础信息</h2>
+        <ul>
+          <li><strong>Base URL</strong>: <code>http://localhost:3000</code></li>
+          <li><strong>Content-Type</strong>: <code>application/json</code></li>
+        </ul>
+        <h2>响应格式</h2>
+        <p>所有 API 响应都遵循统一的格式：</p>
+        <h3>成功响应</h3>
+        <pre><code class="language-json">{
+  "success": true,
+  "data": {
+    // 响应数据
+  }
+}</code></pre>
+        <h3>错误响应</h3>
+        <pre><code class="language-json">{
+  "success": false,
+  "message": "错误信息",
+  "stack": "..." // 仅在开发环境显示
+}</code></pre>
+        <h2>API 列表</h2>
+        <ul>
+          <li><a href="#" onclick="showContent('api-user'); return false;">用户接口</a> - 用户相关的 CRUD 操作</li>
+        </ul>
+      </div>
+      <!-- 用户接口 -->
+      <div id="api-user" class="content-section">
+        <h1>用户接口</h1>
+        <p>用户相关的 CRUD 操作接口。</p>
+        <h2>获取用户列表</h2>
+        <p>获取所有用户列表。</p>
+        <h3>请求</h3>
+        <pre><code class="language-http">GET /api/user</code></pre>
+        <h3>响应</h3>
+        <pre><code class="language-json">{
+  "success": true,
+  "data": [
+    {
+      "id": 1,
+      "name": "张三",
+      "email": "zhangsan@example.com",
+      "createdAt": "2024-01-01T00:00:00.000Z"
+    },
+    {
+      "id": 2,
+      "name": "李四",
+      "email": "lisi@example.com",
+      "createdAt": "2024-01-01T00:00:00.000Z"
+    }
+  ]
+}</code></pre>
+        <h2>获取用户详情</h2>
+        <p>根据用户 ID 获取用户详情。</p>
+        <h3>请求</h3>
+        <pre><code class="language-http">GET /api/user/:id</code></pre>
+        <h3>路径参数</h3>
+        <table>
+          <thead>
+            <tr>
+              <th>参数</th>
+              <th>类型</th>
+              <th>说明</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr>
+              <td>id</td>
+              <td>number</td>
+              <td>用户ID</td>
+            </tr>
+          </tbody>
+        </table>
+        <h3>响应</h3>
+        <pre><code class="language-json">{
+  "success": true,
+  "data": {
+    "id": 1,
+    "name": "张三",
+    "email": "zhangsan@example.com",
+    "createdAt": "2024-01-01T00:00:00.000Z"
+  }
+}</code></pre>
+        <h3>错误响应</h3>
+        <pre><code class="language-json">{
+  "success": false,
+  "message": "User not found"
+}</code></pre>
+        <h2>创建用户</h2>
+        <p>创建新用户。</p>
+        <h3>请求</h3>
+        <pre><code class="language-http">POST /api/user
+Content-Type: application/json</code></pre>
+        <h3>请求体</h3>
+        <pre><code class="language-json">{
+  "name": "张三",
+  "email": "zhangsan@example.com"
+}</code></pre>
+        <h3>请求参数</h3>
+        <table>
+          <thead>
+            <tr>
+              <th>参数</th>
+              <th>类型</th>
+              <th>必填</th>
+              <th>说明</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr>
+              <td>name</td>
+              <td>string</td>
+              <td>是</td>
+              <td>用户姓名</td>
+            </tr>
+            <tr>
+              <td>email</td>
+              <td>string</td>
+              <td>是</td>
+              <td>用户邮箱</td>
+            </tr>
+          </tbody>
+        </table>
+        <h3>响应</h3>
+        <pre><code class="language-json">{
+  "success": true,
+  "data": {
+    "id": 1,
+    "name": "张三",
+    "email": "zhangsan@example.com",
+    "createdAt": "2024-01-01T00:00:00.000Z"
+  }
+}</code></pre>
+        <h2>更新用户</h2>
+        <p>更新用户信息。</p>
+        <h3>请求</h3>
+        <pre><code class="language-http">PUT /api/user/:id
+Content-Type: application/json</code></pre>
+        <h3>路径参数</h3>
+        <table>
+          <thead>
+            <tr>
+              <th>参数</th>
+              <th>类型</th>
+              <th>说明</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr>
+              <td>id</td>
+              <td>number</td>
+              <td>用户ID</td>
+            </tr>
+          </tbody>
+        </table>
+        <h3>请求体</h3>
+        <pre><code class="language-json">{
+  "name": "李四",
+  "email": "lisi@example.com"
+}</code></pre>
+        <h3>响应</h3>
+        <pre><code class="language-json">{
+  "success": true,
+  "data": {
+    "id": 1,
+    "name": "李四",
+    "email": "lisi@example.com",
+    "createdAt": "2024-01-01T00:00:00.000Z",
+    "updatedAt": "2024-01-02T00:00:00.000Z"
+  }
+}</code></pre>
+        <h2>删除用户</h2>
+        <p>删除指定用户。</p>
+        <h3>请求</h3>
+        <pre><code class="language-http">DELETE /api/user/:id</code></pre>
+        <h3>路径参数</h3>
+        <table>
+          <thead>
+            <tr>
+              <th>参数</th>
+              <th>类型</th>
+              <th>说明</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr>
+              <td>id</td>
+              <td>number</td>
+              <td>用户ID</td>
+            </tr>
+          </tbody>
+        </table>
+        <h3>响应</h3>
+        <pre><code class="language-http">204 No Content</code></pre>
+        <h3>错误响应</h3>
+        <pre><code class="language-json">{
+  "success": false,
+  "message": "User not found"
+}</code></pre>
+      </div>
+    </div>
+  </main>
+  <!-- Prism.js 代码高亮库 -->
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-core.min.js"></script>
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/plugins/autoloader/prism-autoloader.min.js"></script>
+  <!-- 文档内容配置 - 修改 docs-content.js 来更新导航菜单 -->
+  <script src="/docs/docs-content.js"></script>
+  <!-- 文档逻辑文件 - 修改 docs.js 来调整交互行为 -->
+  <script src="/docs/docs.js"></script>
+</body>
+</html>