koa3-cli 1.0.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2020 WZC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,177 @@
+# Koa3 CLI
+
+基于 Koa3 的脚手架项目。
+
+- 📖 文档地址：https://atwzc.cn/
+- 🔗 Gitee 地址：https://gitee.com/wangziwl/koa3-cli
+
+## 项目结构
+
+```
+koa2-cli/
+├── app/                    # 应用代码目录
+│   ├── controller/        # 控制器目录
+│   │   ├── home.js        # 首页控制器
+│   │   └── user.js        # 用户控制器
+│   ├── service/           # 服务层目录
+│   │   └── user.js        # 用户服务
+│   ├── model/             # 数据模型目录
+│   │   └── user.js        # 用户模型
+│   ├── middleware/        # 中间件目录
+│   │   ├── index.js       # 中间件入口
+│   │   └── auth.js        # 认证中间件示例
+│   └── router.js          # 路由配置
+├── config/                # 配置文件目录
+│   ├── config.default.js  # 默认配置
+│   ├── config.local.js    # 本地开发配置
+│   └── config.prod.js     # 生产环境配置
+├── public/                # 静态资源目录
+│   └── index.html         # 首页
+├── app.js                 # 应用入口文件
+├── package.json           # 项目配置
+└── README.md             # 项目说明
+```
+
+## 特性
+
+- ✅ 基于 Koa2，轻量高效
+- ✅ 项目结构，清晰规范
+- ✅ 支持多环境配置（development/production）
+- ✅ MVC 架构（Controller/Service/Model）
+- ✅ 中间件支持
+- ✅ 统一的错误处理
+- ✅ RESTful API 示例
+
+## 快速开始
+
+### 安装依赖
+
+```bash
+npm install
+```
+
+### 启动项目
+
+开发环境（使用 nodemon 自动重启）：
+```bash
+npm run dev
+```
+
+生产环境：
+```bash
+npm start
+```
+
+### 访问应用
+
+- 首页: http://localhost:3000
+- API 示例: http://localhost:3000/api/user
+- 文档: http://localhost:3000/index.html
+
+### 文档开发
+
+启动 VuePress 文档开发服务器：
+```bash
+npm run docs:dev
+```
+
+构建文档为静态文件：
+```bash
+npm run docs:build
+```
+
+## 环境配置
+
+项目支持多环境配置，通过 `NODE_ENV` 环境变量控制：
+
+- `development` 或 `local`: 加载 `config.local.js`
+- `production`: 加载 `config.prod.js`
+- 默认: 加载 `config.default.js`
+
+可以通过 `.env` 文件配置环境变量（参考 `.env.example`）。
+
+## API 示例
+
+### 获取用户列表
+```bash
+GET /api/user
+```
+
+### 获取用户详情
+```bash
+GET /api/user/:id
+```
+
+### 创建用户
+```bash
+POST /api/user
+Content-Type: application/json
+
+{
+  "name": "张三",
+  "email": "zhangsan@example.com"
+}
+```
+
+### 更新用户
+```bash
+PUT /api/user/:id
+Content-Type: application/json
+
+{
+  "name": "李四",
+  "email": "lisi@example.com"
+}
+```
+
+### 删除用户
+```bash
+DELETE /api/user/:id
+```
+
+## 开发指南
+
+### 添加新的控制器
+
+1. 在 `app/controller/` 目录下创建控制器文件
+2. 在 `app/router.js` 中注册路由
+
+示例：
+```javascript
+// app/controller/product.js
+class ProductController {
+  async list(ctx) {
+    ctx.body = await productService.getList();
+  }
+}
+module.exports = new ProductController();
+
+// app/router.js
+const productController = require('./controller/product');
+router.get('/api/product', productController.list);
+```
+
+### 添加新的服务
+
+在 `app/service/` 目录下创建服务文件，处理业务逻辑。
+
+### 添加新的模型
+
+在 `app/model/` 目录下创建模型文件，处理数据访问。
+
+### 添加中间件
+
+在 `app/middleware/` 目录下创建中间件文件，然后在 `app/middleware/index.js` 中引入使用。
+
+## 技术栈
+
+- **Koa2**: Web 框架
+- **koa-router**: 路由
+- **koa-bodyparser**: 请求体解析
+- **koa-static**: 静态资源服务
+- **koa-views**: 模板引擎支持
+- **dotenv**: 环境变量管理
+
+## 许可证
+
+MIT

package/app/controller/home.js

@@ -0,0 +1,17 @@
+/**
+ * 首页控制器
+ */
+class HomeController {
+  /**
+   * 首页
+   */
+  async index(ctx) {
+    ctx.body = {
+      message: 'Welcome to Koa2 CLI',
+      version: '1.0.0',
+      timestamp: new Date().toISOString()
+    };
+  }
+}
+
+module.exports = new HomeController();

package/app/controller/user.js

@@ -0,0 +1,89 @@
+/**
+ * 用户控制器
+ */
+const userService = require('../service/user');
+
+class UserController {
+  /**
+   * 获取用户列表
+   */
+  async list(ctx) {
+    try {
+      const users = await userService.getUserList();
+      ctx.body = users;
+    } catch (error) {
+      ctx.throw(500, error.message);
+    }
+  }
+
+  /**
+   * 获取用户详情
+   */
+  async detail(ctx) {
+    try {
+      const { id } = ctx.params;
+      const user = await userService.getUserById(id);
+      if (!user) {
+        ctx.status = 404;
+        ctx.body = { message: 'User not found' };
+        return;
+      }
+      ctx.body = user;
+    } catch (error) {
+      ctx.throw(500, error.message);
+    }
+  }
+
+  /**
+   * 创建用户
+   */
+  async create(ctx) {
+    try {
+      const userData = ctx.request.body;
+      const user = await userService.createUser(userData);
+      ctx.status = 201;
+      ctx.body = user;
+    } catch (error) {
+      ctx.throw(500, error.message);
+    }
+  }
+
+  /**
+   * 更新用户
+   */
+  async update(ctx) {
+    try {
+      const { id } = ctx.params;
+      const userData = ctx.request.body;
+      const user = await userService.updateUser(id, userData);
+      if (!user) {
+        ctx.status = 404;
+        ctx.body = { message: 'User not found' };
+        return;
+      }
+      ctx.body = user;
+    } catch (error) {
+      ctx.throw(500, error.message);
+    }
+  }
+
+  /**
+   * 删除用户
+   */
+  async delete(ctx) {
+    try {
+      const { id } = ctx.params;
+      const result = await userService.deleteUser(id);
+      if (!result) {
+        ctx.status = 404;
+        ctx.body = { message: 'User not found' };
+        return;
+      }
+      ctx.status = 204;
+    } catch (error) {
+      ctx.throw(500, error.message);
+    }
+  }
+}
+
+module.exports = new UserController();

package/app/middleware/auth.js

@@ -0,0 +1,30 @@
+/**
+ * 认证中间件示例
+ * 可以根据需要启用
+ */
+
+module.exports = async (ctx, next) => {
+  // 示例：简单的token验证
+  const token = ctx.headers.authorization;
+  
+  if (!token && ctx.path.startsWith('/api')) {
+    // 某些公开接口可以跳过认证
+    const publicPaths = ['/api/user'];
+    if (!publicPaths.includes(ctx.path)) {
+      ctx.status = 401;
+      ctx.body = {
+        success: false,
+        message: 'Unauthorized'
+      };
+      return;
+    }
+  }
+  
+  // 验证token逻辑（示例）
+  if (token) {
+    // 这里应该验证token的有效性
+    // ctx.user = await verifyToken(token);
+  }
+  
+  await next();
+};

package/app/middleware/index.js

@@ -0,0 +1,24 @@
+/**
+ * 中间件入口文件
+ * 可以在这里统一管理和导出所有中间件
+ */
+
+// 组合中间件：按顺序执行，确保 next 链正确传递
+module.exports = async (ctx, next) => {
+  // 1. 请求时间中间件
+  ctx.requestTime = Date.now();
+  
+  // 2. 等待后续中间件执行
+  await next();
+  
+  // 3. API响应格式中间件（在响应返回前处理）
+  // 如果是API请求，统一响应格式
+  if (ctx.path.startsWith('/api')) {
+    if (ctx.body && typeof ctx.body === 'object' && !ctx.body.success) {
+      ctx.body = {
+        success: true,
+        data: ctx.body
+      };
+    }
+  }
+};

package/app/model/user.js

@@ -0,0 +1,70 @@
+/**
+ * 用户数据模型
+ * 负责与数据库交互
+ */
+
+// 示例：模拟数据存储（实际项目中应该连接真实数据库）
+let users = [
+  { id: 1, name: '张三', email: 'zhangsan@example.com', createdAt: new Date() },
+  { id: 2, name: '李四', email: 'lisi@example.com', createdAt: new Date() }
+];
+
+class UserModel {
+  /**
+   * 查找所有用户
+   */
+  async findAll() {
+    // 实际项目中应该查询数据库
+    return users;
+  }
+
+  /**
+   * 根据ID查找用户
+   */
+  async findById(id) {
+    return users.find(user => user.id === parseInt(id));
+  }
+
+  /**
+   * 创建用户
+   */
+  async create(userData) {
+    const newUser = {
+      id: users.length > 0 ? Math.max(...users.map(u => u.id)) + 1 : 1,
+      ...userData,
+      createdAt: new Date()
+    };
+    users.push(newUser);
+    return newUser;
+  }
+
+  /**
+   * 更新用户
+   */
+  async update(id, userData) {
+    const index = users.findIndex(user => user.id === parseInt(id));
+    if (index === -1) {
+      return null;
+    }
+    users[index] = {
+      ...users[index],
+      ...userData,
+      updatedAt: new Date()
+    };
+    return users[index];
+  }
+
+  /**
+   * 删除用户
+   */
+  async delete(id) {
+    const index = users.findIndex(user => user.id === parseInt(id));
+    if (index === -1) {
+      return false;
+    }
+    users.splice(index, 1);
+    return true;
+  }
+}
+
+module.exports = new UserModel();

package/app/router.js

@@ -0,0 +1,19 @@
+const Router = require('koa-router');
+const router = new Router();
+
+// 加载控制器
+const homeController = require('./controller/home');
+const userController = require('./controller/user');
+
+// 路由配置
+// 首页
+router.get('/', homeController.index);
+
+// 用户相关路由
+router.get('/api/user', userController.list);
+router.get('/api/user/:id', userController.detail);
+router.post('/api/user', userController.create);
+router.put('/api/user/:id', userController.update);
+router.delete('/api/user/:id', userController.delete);
+
+module.exports = router;

package/app/service/user.js

@@ -0,0 +1,50 @@
+/**
+ * 用户服务层
+ * 处理业务逻辑，与数据模型交互
+ */
+const userModel = require('../model/user');
+
+class UserService {
+  /**
+   * 获取用户列表
+   */
+  async getUserList() {
+    // 这里应该从数据库获取数据
+    // 示例：返回模拟数据
+    return await userModel.findAll();
+  }
+
+  /**
+   * 根据ID获取用户
+   */
+  async getUserById(id) {
+    return await userModel.findById(id);
+  }
+
+  /**
+   * 创建用户
+   */
+  async createUser(userData) {
+    // 数据验证
+    if (!userData.name || !userData.email) {
+      throw new Error('Name and email are required');
+    }
+    return await userModel.create(userData);
+  }
+
+  /**
+   * 更新用户
+   */
+  async updateUser(id, userData) {
+    return await userModel.update(id, userData);
+  }
+
+  /**
+   * 删除用户
+   */
+  async deleteUser(id) {
+    return await userModel.delete(id);
+  }
+}
+
+module.exports = new UserService();

package/app.js

@@ -0,0 +1,112 @@
+const Koa = require('koa');
+const Router = require('koa-router');
+const bodyParser = require('koa-bodyparser');
+const static = require('koa-static');
+const views = require('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 app = new Koa();
+
+// 应用配置
+app.keys = config.keys || ['koa2-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`);
+});
+
+// 注册路由
+app.use(router.routes()).use(router.allowedMethods());
+
+// 404 处理（必须在路由之后）
+app.use(async (ctx) => {
+  if (ctx.status === 404) {
+    ctx.body = {
+      success: false,
+      message: 'Not Found'
+    };
+  }
+});
+
+// 错误事件监听
+app.on('error', (err, ctx) => {
+  console.error('Server error:', err);
+});
+
+// 启动服务器
+const port = config.port || 3000;
+app.listen(port, () => {
+  console.log(`Server is running on http://localhost:${port}`);
+  console.log(`Environment: ${config.env}`);
+});
+
+module.exports = app;

package/config/config.default.js

@@ -0,0 +1,82 @@
+/**
+ * 默认配置文件
+ * 所有环境都会加载此配置
+ */
+module.exports = {
+  // 应用名称
+  name: 'koa2-cli',
+  
+  // 运行环境: development, production, test
+  env: process.env.NODE_ENV || 'development',
+  
+  // 服务端口
+  port: process.env.PORT || 3000,
+  
+  // 密钥，用于加密cookie等
+  keys: process.env.KEYS ? process.env.KEYS.split(',') : ['koa2-cli-secret-key'],
+  
+  // 静态资源配置
+  static: {
+    enable: true,
+    dir: 'public',
+    options: {
+      maxAge: 365 * 24 * 60 * 60 * 1000, // 1年
+      gzip: true
+    }
+  },
+  
+  // VuePress 文档配置
+  docs: {
+    enable: true,
+    buildDir: 'public/docs'
+  },
+  
+  // 视图配置
+  view: {
+    enable: true,
+    root: 'app/view',
+    options: {
+      extension: 'ejs',
+      map: {
+        html: 'ejs'
+      }
+    }
+  },
+  
+  // bodyParser配置
+  bodyParser: {
+    enableTypes: ['json', 'form', 'text'],
+    jsonLimit: '10mb',
+    formLimit: '10mb'
+  },
+  
+  // 数据库配置（示例）
+  database: {
+    client: 'mysql',
+    connection: {
+      host: process.env.DB_HOST || 'localhost',
+      port: process.env.DB_PORT || 3306,
+      user: process.env.DB_USER || 'root',
+      password: process.env.DB_PASSWORD || '',
+      database: process.env.DB_NAME || 'test'
+    },
+    pool: {
+      min: 2,
+      max: 10
+    }
+  },
+  
+  // Redis配置（示例）
+  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: {
+    level: process.env.LOG_LEVEL || 'info',
+    dir: 'logs'
+  }
+};

package/config/config.local.js

@@ -0,0 +1,24 @@
+/**
+ * 本地开发环境配置
+ * 只在本地开发时加载，会覆盖 config.default.js 中的配置
+ */
+module.exports = {
+  env: 'development',
+  port: 3000,
+  
+  // 开发环境可以开启更详细的日志
+  logger: {
+    level: 'debug'
+  },
+  
+  // 开发环境数据库配置示例
+  database: {
+    connection: {
+      host: 'localhost',
+      port: 3306,
+      user: 'root',
+      password: '',
+      database: 'test_dev'
+    }
+  }
+};