koa3-cli 1.0.9 → 1.1.0

package/RELEASE.md

@@ -0,0 +1,159 @@
+# Release Guide
+
+本文档用于记录 Koa3 CLI 的发版流程，目标是让每次发布都能复现、可检查、可回滚。
+
+## 发布前检查
+
+1. 确认当前分支是 `master`，并且工作区干净。
+
+```bash
+git status --short --branch
+```
+
+2. 安装依赖并确认锁文件可用。
+
+```bash
+npm ci
+```
+
+3. 检查依赖安全风险。
+
+```bash
+npm audit
+```
+
+4. 运行自动化测试。
+
+```bash
+npm test
+```
+
+5. 检查 npm 发布包内容。
+
+```bash
+npm pack --dry-run
+```
+
+6. 确认 README、CHANGELOG 和文档站内容已经同步。
+
+## 版本更新
+
+根据变更范围选择版本类型：
+
+- `patch`：bug 修复、依赖补丁、文档修正。
+- `minor`：新增向后兼容能力，例如新模板、新命令、CI 或工程化能力。
+- `major`：不兼容的 CLI、模板结构或运行时行为变更。
+
+更新版本号：
+
+```bash
+npm version patch --no-git-tag-version
+npm version minor --no-git-tag-version
+npm version major --no-git-tag-version
+```
+
+如果需要指定版本：
+
+```bash
+npm version 1.1.0 --no-git-tag-version
+```
+
+版本号更新后，需要同步修改 `CHANGELOG.md`。
+
+## 提交与标签
+
+1. 提交版本变更。
+
+```bash
+git add package.json package-lock.json CHANGELOG.md RELEASE.md README.md
+git commit -m "chore: release v1.1.0"
+```
+
+2. 创建 Git tag。
+
+```bash
+git tag v1.1.0
+```
+
+3. 推送到 GitHub 和 Gitee。
+
+```bash
+git push github master
+git push github v1.1.0
+git push origin master
+git push origin v1.1.0
+```
+
+## 发布 npm
+
+发布前再次确认包内容：
+
+```bash
+npm pack --dry-run
+```
+
+发布到 npm：
+
+```bash
+npm publish
+```
+
+发布后确认 npm 最新版本：
+
+```bash
+npm view koa3-cli version
+```
+
+## GitHub Release
+
+在 GitHub 仓库创建 Release：
+
+- Tag：`v1.1.0`
+- Title：`v1.1.0`
+- Release notes：参考 `CHANGELOG.md` 对应版本内容
+
+建议 release notes 包含：
+
+- 本次新增能力
+- 依赖或安全修复
+- 迁移说明
+- 已知问题
+
+## 发布后验证
+
+1. 使用 npx 创建项目。
+
+```bash
+npx koa3-cli create koa3-release-test
+cd koa3-release-test
+npm install
+npm run dev
+```
+
+2. 验证基础接口。
+
+```bash
+curl http://localhost:3000/api/user
+```
+
+3. 验证文档站。
+
+```text
+https://hikerw.github.io/koa3-cli/
+```
+
+4. 确认 GitHub Actions 和 GitHub Pages 部署均成功。
+
+## 回滚策略
+
+如果 npm 发布后发现严重问题：
+
+1. 立即在 GitHub Release 说明中标记问题。
+2. 优先发布修复版，例如 `1.1.1`。
+3. 如必须撤回 npm 版本，需谨慎使用：
+
+```bash
+npm unpublish koa3-cli@1.1.0
+```
+
+注意：npm unpublish 有时间和生态限制，常规情况下更推荐发布修复版本。

package/app/setup.js

@@ -4,6 +4,7 @@
  */
 const path = require('path');
 const fs = require('fs');
+const cors = require('@koa/cors');
 const bodyParser = require('koa-bodyparser');
 const serveStatic = require('koa-static');
 const views = require('@ladjs/koa-views');
@@ -16,44 +17,44 @@ const router = require('./router');
 
 const rootDir = path.join(__dirname, '..');
 
-/**
- * 生成静态资源缓存配置。
- *
- * SPA 的入口 index.html 会引用最新一批带 hash 的 JS/CSS 文件，如果入口文件被浏览器或 CDN
- * 长时间缓存，用户发布后仍会拿到旧入口，进而继续加载旧资源。这里仅禁止 index.html 缓存，
- * 其他静态资源继续使用配置里的 maxAge，保证发布更新及时生效且不影响资源缓存性能。
- *
- * @param {Object} staticOptions koa-static 原始配置项
- * @returns {Object} 注入 index.html 不缓存策略后的 koa-static 配置项
- */
-function createStaticOptions(staticOptions = {}) {
-  const userSetHeaders = staticOptions.setHeaders;
-
-  return {
-    ...staticOptions,
-    setHeaders(res, filePath, stats) {
-      if (typeof userSetHeaders === 'function') {
-        userSetHeaders(res, filePath, stats);
-      }
-
-      // koa-send 在启用 gzip/brotli 时传入的是 index.html.gz / index.html.br，
-      // 需要去掉压缩扩展名后再判断，避免预压缩入口文件继续被长缓存。
-      const normalizedFileName = path.basename(filePath).replace(/\.(br|gz)$/i, '');
-      if (normalizedFileName === 'index.html') {
-        res.setHeader('Cache-Control', INDEX_HTML_CACHE_CONTROL);
-        res.setHeader('Pragma', 'no-cache');
-        res.setHeader('Expires', '0');
-      }
-    }
-  };
+/**
+ * 生成静态资源缓存配置。
+ *
+ * SPA 的入口 index.html 会引用最新一批带 hash 的 JS/CSS 文件，如果入口文件被浏览器或 CDN
+ * 长时间缓存，用户发布后仍会拿到旧入口，进而继续加载旧资源。这里仅禁止 index.html 缓存，
+ * 其他静态资源继续使用配置里的 maxAge，保证发布更新及时生效且不影响资源缓存性能。
+ *
+ * @param {Object} staticOptions koa-static 原始配置项
+ * @returns {Object} 注入 index.html 不缓存策略后的 koa-static 配置项
+ */
+function createStaticOptions(staticOptions = {}) {
+  const userSetHeaders = staticOptions.setHeaders;
+
+  return {
+    ...staticOptions,
+    setHeaders(res, filePath, stats) {
+      if (typeof userSetHeaders === 'function') {
+        userSetHeaders(res, filePath, stats);
+      }
+
+      // koa-send 在启用 gzip/brotli 时传入的是 index.html.gz / index.html.br，
+      // 需要去掉压缩扩展名后再判断，避免预压缩入口文件继续被长缓存。
+      const normalizedFileName = path.basename(filePath).replace(/\.(br|gz)$/i, '');
+      if (normalizedFileName === 'index.html') {
+        res.setHeader('Cache-Control', INDEX_HTML_CACHE_CONTROL);
+        res.setHeader('Pragma', 'no-cache');
+        res.setHeader('Expires', '0');
+      }
+    }
+  };
 }
 
 function setup(app, config, logger) {
   // 静态资源
   if (config.static && config.static.enable !== false) {
     const staticPath = path.join(rootDir, config.static.dir || 'public');
-    if (fs.existsSync(staticPath)) {
-      app.use(serveStatic(staticPath, createStaticOptions(config.static.options || {})));
+    if (fs.existsSync(staticPath)) {
+      app.use(serveStatic(staticPath, createStaticOptions(config.static.options || {})));
     }
   }
 
@@ -65,6 +66,12 @@ function setup(app, config, logger) {
     }
   }
 
+  // CORS 默认关闭，避免脚手架生成的项目在未明确授权时开放跨域。
+  // 需要给前端应用或第三方调用方开放接口时，可通过 config.cors.enable 或 CORS_ENABLE 开启。
+  if (config.cors && config.cors.enable === true) {
+    app.use(cors(config.cors.options || {}));
+  }
+
   app.use(bodyParser(config.bodyParser || {}));
   app.use(createRequestLogger(logger));
 

package/bin/cli.js

@@ -25,7 +25,7 @@ Koa3 CLI - 快速创建 Koa3 项目脚手架
 示例:
   koa3-cli create my-app
 
-更多信息: https://gitee.com/wangziwl/koa3-cli
+更多信息: https://github.com/hikerw/koa3-cli
 `);
 }
 
@@ -180,7 +180,7 @@ function createProject(projectName) {
     console.log(`  cd ${projectName}`);
     console.log('  npm install');
     console.log('  npm run dev\n');
-    console.log('📖 文档: https://atwzc.cn/');
+    console.log('📖 文档: https://hikerw.github.io/koa3-cli/');
     console.log('🔗 Gitee: https://gitee.com/wangziwl/koa3-cli\n');
 
   } catch (error) {

package/config/config.default.js

@@ -14,6 +14,16 @@ module.exports = {
   // Cookie signing keys
   keys: process.env.KEYS ? process.env.KEYS.split(',') : ['koa3-cli-secret-key'],
 
+  // CORS configuration
+  // 默认关闭跨域，避免新项目在没有明确安全边界时暴露给任意来源。
+  // 如需开放给前端应用，可设置 CORS_ENABLE=true，并用 CORS_ORIGIN 指定允许的来源。
+  cors: {
+    enable: process.env.CORS_ENABLE === 'true',
+    options: {
+      origin: process.env.CORS_ORIGIN || '*'
+    }
+  },
+
   // Static assets
   static: {
     enable: true,

package/env.example

@@ -10,6 +10,11 @@ PORT=3000
 # 应用密钥（多个密钥用逗号分隔）
 KEYS=your-secret-key-1,your-secret-key-2
 
+# 跨域配置
+# 默认关闭跨域；如果前端和接口不在同一域名下，可设置为 true 并限制允许来源。
+CORS_ENABLE=false
+CORS_ORIGIN=*
+
 # 数据库配置
 DB_HOST=localhost
 DB_PORT=3306

package/package.json

@@ -1,38 +1,63 @@
 {
   "name": "koa3-cli",
-  "version": "1.0.9",
-  "description": "Koa3脚手架",
+  "version": "1.1.0",
+  "description": "面向 Koa 3 的现代 Node.js API 项目脚手架",
   "main": "app.js",
   "bin": {
     "koa3-cli": "bin/cli.js"
   },
+  "files": [
+    "app",
+    "bin",
+    "config",
+    "public",
+    "app.js",
+    "env.example",
+    "README.md",
+    "CHANGELOG.md",
+    "RELEASE.md",
+    "LICENSE",
+    ".gitignore",
+    ".npmignore"
+  ],
   "preferGlobal": true,
   "scripts": {
     "start": "node app.js",
     "dev": "nodemon app.js",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node --test"
   },
   "keywords": [
     "koa3",
+    "koa",
+    "koa-cli",
+    "nodejs",
+    "backend",
+    "rest-api",
     "scaffold",
     "cli"
   ],
   "author": "hikerw <965366906@qq.com>",
   "repository": {
     "type": "git",
-    "url": "https://gitee.com/wangziwl/koa3-cli"
+    "url": "git+https://github.com/hikerw/koa3-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hikerw/koa3-cli/issues"
   },
-  "homepage": "https://atwzc.cn/",
+  "homepage": "https://hikerw.github.io/koa3-cli/",
   "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
   "dependencies": {
-    "@koa/router": "^15.3.1",
+    "@koa/cors": "^5.0.0",
+    "@koa/router": "^15.6.0",
     "@ladjs/koa-views": "^9.0.0",
-    "dotenv": "^17.3.1",
+    "dotenv": "^17.4.2",
     "ejs": "^4.0.1",
-    "joi": "^17.13.3",
-    "koa": "^3.1.2",
+    "joi": "^17.13.4",
+    "koa": "^3.2.1",
     "koa-bodyparser": "^4.4.1",
-    "koa-cors": "^0.0.16",
     "koa-static": "^5.0.0"
   },
   "devDependencies": {

package/public/docs/docs-content.js

@@ -0,0 +1,180 @@
+/* ============================================
+   Koa3 CLI 文档内容数据文件
+   修改此文件来更新文档内容和导航菜单
+   ============================================ */
+
+/**
+ * 导航菜单配置
+ * 修改此配置来调整侧边栏导航
+ */
+const DOCS_NAVIGATION = [
+  {
+    title: '指南',
+    items: [
+      { id: 'home', label: '首页' },
+      { id: 'getting-started', label: '快速开始' },
+      { id: 'project-structure', label: '项目结构' },
+      { id: 'configuration', label: '配置说明' },
+      { id: 'development', label: '开发指南' }
+    ]
+  },
+  {
+    title: 'API',
+    items: [
+      { id: 'api-readme', label: 'API 文档' },
+      { id: 'api-user', label: '用户接口' }
+    ]
+  }
+];
+
+/**
+ * 文档内容配置
+ * 修改此配置来更新文档内容
+ */
+const DOCS_CONTENT = {
+  'home': {
+    title: 'Koa3 CLI',
+    subtitle: '基于 Koa3 的脚手架项目',
+    description: '2025年4月28日，Node.js 生态圈迎来了一场重磅升级——Koa.js 3.0 正式发布！自2017年启动开发计划，历经8年长跑，由 Express 原班人马打造的经典轻量级 Web 框架，终于以全新姿态回归视野。Koa 3.0 不仅是一次版本号的跃迁，更是 Node.js 现代化进程的重要里程碑。',
+    actionButton: {
+      text: '快速开始 →',
+      target: 'getting-started'
+    },
+    features: [
+      { icon: '🚀', title: '轻量高效', description: '基于 Koa3，性能优异，代码简洁' },
+      { icon: '📁', title: '清晰结构', description: '规范统一，易于维护' },
+      { icon: '🔧', title: '多环境配置', description: '支持 development/production 环境配置' },
+      { icon: '🏗️', title: 'MVC 架构', description: 'Controller/Service/Model 分层清晰' },
+      { icon: '🔌', title: '中间件支持', description: '灵活的中间件系统，易于扩展' },
+      { icon: '✅', title: '错误处理', description: '统一的错误处理机制' }
+    ]
+  },
+  'getting-started': {
+    title: '快速开始',
+    sections: [
+      {
+        type: 'h2',
+        content: '安装依赖'
+      },
+      {
+        type: 'code',
+        language: 'bash',
+        content: 'npm install'
+      },
+      {
+        type: 'h2',
+        content: '启动项目'
+      },
+      {
+        type: 'h3',
+        content: '开发环境'
+      },
+      {
+        type: 'p',
+        content: '使用 nodemon 自动重启：'
+      },
+      {
+        type: 'code',
+        language: 'bash',
+        content: 'npm run dev'
+      },
+      {
+        type: 'h3',
+        content: '生产环境'
+      },
+      {
+        type: 'code',
+        language: 'bash',
+        content: 'npm start'
+      },
+      {
+        type: 'h2',
+        content: '访问应用'
+      },
+      {
+        type: 'p',
+        content: '启动成功后，你可以访问：'
+      },
+      {
+        type: 'list',
+        items: [
+          '<strong>首页</strong>: http://localhost:3000',
+          '<strong>API 示例</strong>: http://localhost:3000/api/user',
+          '<strong>文档</strong>: http://localhost:3000/index.html'
+        ]
+      },
+      {
+        type: 'h2',
+        content: '环境配置'
+      },
+      {
+        type: 'p',
+        content: '项目支持多环境配置，通过 <code>NODE_ENV</code> 环境变量控制：'
+      },
+      {
+        type: 'list',
+        items: [
+          '<code>development</code> 或 <code>local</code>: 加载 <code>config.local.js</code>',
+          '<code>production</code>: 加载 <code>config.prod.js</code>',
+          '默认: 加载 <code>config.default.js</code>'
+        ]
+      },
+      {
+        type: 'p',
+        content: '可以通过 <code>.env</code> 文件配置环境变量（参考 <code>env.example</code>）。'
+      },
+      {
+        type: 'h2',
+        content: '下一步'
+      },
+      {
+        type: 'list',
+        items: [
+          '了解 <a href="#" onclick="showContent(\'project-structure\'); return false;">项目结构</a>',
+          '查看 <a href="#" onclick="showContent(\'configuration\'); return false;">配置说明</a>',
+          '阅读 <a href="#" onclick="showContent(\'development\'); return false;">开发指南</a>'
+        ]
+      }
+    ]
+  },
+  // 其他内容可以继续添加...
+  // 为了简化，这里只展示结构，实际使用时可以将完整的 HTML 内容放在这里
+};
+
+/**
+ * 渲染导航菜单
+ */
+function renderNavigation() {
+  const sidebar = document.getElementById('sidebar');
+  if (!sidebar) return;
+
+  let html = '';
+  DOCS_NAVIGATION.forEach(group => {
+    html += '<div class="sidebar-group">';
+    html += `<div class="sidebar-group-title">${group.title}</div>`;
+    group.items.forEach(item => {
+      const isActive = item.id === 'home' ? 'active' : '';
+      html += `<a href="#" class="sidebar-link ${isActive}" onclick="showContent('${item.id}'); return false;">${item.label}</a>`;
+    });
+    html += '</div>';
+  });
+  sidebar.innerHTML = html;
+}
+
+/**
+ * 渲染文档内容
+ * 注意：由于内容较长，这里提供一个简化的渲染函数
+ * 实际使用时，可以将完整的 HTML 内容直接放在 HTML 文件中，或者使用模板引擎
+ */
+function renderContent() {
+  // 这个方法可以根据 DOCS_CONTENT 配置动态生成内容
+  // 但为了简单和性能，建议直接在 HTML 中写内容
+  // 这里只是提供一个结构示例
+}
+
+// 页面加载时渲染导航
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', renderNavigation);
+} else {
+  renderNavigation();
+}