koa3-cli 1.0.5 → 1.0.7

package/app/middleware/errorHandler.js

@@ -0,0 +1,29 @@
+/**
+ * 全局错误处理中间件：捕获异常、记录日志、统一错误响应
+ */
+module.exports = function createErrorHandler(config, logger) {
+  return async function errorHandler(ctx, next) {
+    try {
+      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: firstDetailMessage || err.message || 'Internal Server Error',
+        ...(err.details && { errors: err.details })
+      };
+
+      logger.error('Request failed', {
+        requestId: ctx.state && ctx.state.requestId,
+        method: ctx.method,
+        url: ctx.originalUrl || ctx.url,
+        status: ctx.status,
+        message: err.message,
+        stack: err.stack
+      });
+
+      ctx.app.emit('error', err, ctx);
+    }
+  };
+};

package/app/middleware/notFound.js

@@ -0,0 +1,11 @@
+/**
+ * 404 兜底中间件：未匹配路由时返回统一格式
+ */
+module.exports = async function notFound(ctx) {
+  if (ctx.status === 404) {
+    ctx.body = {
+      success: false,
+      message: 'Not Found'
+    };
+  }
+};

package/app/middleware/requestLogger.js

@@ -1,27 +1,27 @@
-function createRequestId() {
-  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
-}
-
-module.exports = function requestLogger(logger) {
-  return async function requestLoggerMiddleware(ctx, next) {
-    const start = Date.now();
-    const requestId = ctx.get('x-request-id') || createRequestId();
-
-    ctx.state.requestId = requestId;
-    ctx.set('x-request-id', requestId);
-
-    try {
-      await next();
-    } finally {
-      const duration = Date.now() - start;
-      logger.access({
-        requestId,
-        method: ctx.method,
-        url: ctx.originalUrl || ctx.url,
-        status: ctx.status,
-        duration,
-        ip: ctx.ip
-      });
-    }
-  };
-};
+function createRequestId() {
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+module.exports = function requestLogger(logger) {
+  return async function requestLoggerMiddleware(ctx, next) {
+    const start = Date.now();
+    const requestId = ctx.get('x-request-id') || createRequestId();
+
+    ctx.state.requestId = requestId;
+    ctx.set('x-request-id', requestId);
+
+    try {
+      await next();
+    } finally {
+      const duration = Date.now() - start;
+      logger.access({
+        requestId,
+        method: ctx.method,
+        url: ctx.originalUrl || ctx.url,
+        status: ctx.status,
+        duration,
+        ip: ctx.ip
+      });
+    }
+  };
+};

package/app/processEvents.js

@@ -0,0 +1,14 @@
+/**
+ * 进程级错误监听：未捕获的 Promise 与异常
+ */
+function setupProcessEvents(logger) {
+  process.on('unhandledRejection', (reason) => {
+    logger.error('Unhandled promise rejection', reason);
+  });
+
+  process.on('uncaughtException', (error) => {
+    logger.error('Uncaught exception', error);
+  });
+}
+
+module.exports = setupProcessEvents;

package/app/router.js

@@ -1,4 +1,7 @@
 const { Router } = require('@koa/router');
+const { validate } = require('./lib/validator');
+const userSchema = require('./schema/user');
+
 const router = new Router();
 
 // 加载控制器
@@ -11,9 +14,9 @@ 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);
+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);
+router.delete('/api/user/:id', validate({ params: userSchema.idParam }), userController.delete);
 
 module.exports = router;

package/app/schema/user.js

@@ -0,0 +1,29 @@
+const { Joi } = require('../lib/validator');
+
+const idParam = Joi.object({
+  id: Joi.string().required().messages({ 'any.required': '用户 id 不能为空' })
+});
+
+const createUserBody = 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 updateUserBody = 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 });
+
+module.exports = {
+  idParam,
+  createUserBody,
+  updateUserBody
+};

package/app/setup.js

@@ -0,0 +1,48 @@
+/**
+ * 应用挂载：静态资源、视图、中间件、路由等
+ * 保持 app.js 只做「创建实例 + 调用 setup + 监听 + 启动」
+ */
+const path = require('path');
+const fs = require('fs');
+const bodyParser = require('koa-bodyparser');
+const serveStatic = require('koa-static');
+const views = require('@ladjs/koa-views');
+
+const createRequestLogger = require('./middleware/requestLogger');
+const createErrorHandler = require('./middleware/errorHandler');
+const notFound = require('./middleware/notFound');
+const middleware = require('./middleware');
+const router = require('./router');
+
+const rootDir = path.join(__dirname, '..');
+
+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, config.static.options || {}));
+    }
+  }
+
+  // 视图
+  if (config.view && config.view.enable !== false) {
+    const viewPath = path.join(rootDir, config.view.root || 'app/view');
+    if (fs.existsSync(viewPath)) {
+      app.use(views(viewPath, config.view.options || { extension: 'ejs' }));
+    }
+  }
+
+  app.use(bodyParser(config.bodyParser || {}));
+  app.use(createRequestLogger(logger));
+
+  if (middleware && typeof middleware === 'function') {
+    app.use(middleware);
+  }
+
+  app.use(createErrorHandler(config, logger));
+  app.use(router.routes()).use(router.allowedMethods());
+  app.use(notFound);
+}
+
+module.exports = setup;

package/app.js

@@ -1,119 +1,38 @@
-const Koa = require('koa');
-const bodyParser = require('koa-bodyparser');
-const serveStatic = require('koa-static');
-const views = require('@ladjs/koa-views');
-const path = require('path');
-const fs = require('fs');
-const { createLogger } = require('./app/lib/logger');
-const createRequestLogger = require('./app/middleware/requestLogger');
-
-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) {
-  // Ignore missing env config override.
-}
-const config = Object.assign({}, defaultConfig, envConfig);
-
-const middleware = require('./app/middleware');
-const router = require('./app/router');
-
-const app = new Koa();
-const logger = createLogger({
-  ...(config.logger || {}),
-  appName: config.name || 'koa3-cli',
-  cwd: __dirname
-});
-
-app.keys = config.keys || ['koa3-cli-secret-key'];
-app.context.logger = logger;
-
-if (config.static && config.static.enable !== false) {
-  const staticPath = path.join(__dirname, config.static.dir || 'public');
-  if (fs.existsSync(staticPath)) {
-    app.use(serveStatic(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 || {}));
-app.use(createRequestLogger(logger));
-
-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 })
-    };
-
-    logger.error('Request failed', {
-      requestId: ctx.state && ctx.state.requestId,
-      method: ctx.method,
-      url: ctx.originalUrl || ctx.url,
-      status: ctx.status,
-      message: err.message,
-      stack: err.stack
-    });
-
-    ctx.app.emit('error', err, ctx);
-  }
-});
-
-app.use(router.routes()).use(router.allowedMethods());
-
-app.use(async (ctx) => {
-  if (ctx.status === 404) {
-    ctx.body = {
-      success: false,
-      message: 'Not Found'
-    };
-  }
-});
-
-app.on('error', (err, ctx) => {
-  logger.error('Server error event', {
-    requestId: ctx && ctx.state && ctx.state.requestId,
-    message: err.message,
-    stack: err.stack
-  });
-});
-
-process.on('unhandledRejection', (reason) => {
-  logger.error('Unhandled promise rejection', reason);
-});
-
-process.on('uncaughtException', (error) => {
-  logger.error('Uncaught exception', error);
-});
-
-const port = config.port || 3000;
-app.listen(port, () => {
-  logger.info(`Server is running on http://localhost:${port}`);
-  logger.info(`Environment: ${config.env}`);
-});
-
+require('dotenv').config();
+
+const Koa = require('koa');
+const { loadConfig } = require('./config/loader');
+const { createLogger } = require('./app/lib/logger');
+const setup = require('./app/setup');
+const setupProcessEvents = require('./app/processEvents');
+
+const config = loadConfig();
+const app = new Koa();
+const logger = createLogger({
+  ...(config.logger || {}),
+  appName: config.name || 'koa3-cli',
+  cwd: __dirname
+});
+
+app.keys = config.keys || ['koa3-cli-secret-key'];
+app.context.logger = logger;
+
+setup(app, config, logger);
+
+app.on('error', (err, ctx) => {
+  logger.error('Server error event', {
+    requestId: ctx && ctx.state && ctx.state.requestId,
+    message: err.message,
+    stack: err.stack
+  });
+});
+
+setupProcessEvents(logger);
+
+const port = config.port || 3000;
+app.listen(port, () => {
+  logger.info(`Server is running on http://localhost:${port}`);
+  logger.info(`Environment: ${config.env}`);
+});
+
 module.exports = app;

package/config/config.default.js

@@ -1,83 +1,83 @@
-/**
- * Default config loaded in all environments.
- */
-module.exports = {
-  // Application name
-  name: 'koa3-cli',
-
-  // Runtime env: development, production, test
-  env: process.env.NODE_ENV || 'development',
-
-  // Server port
-  port: process.env.PORT || 3000,
-
-  // Cookie signing keys
-  keys: process.env.KEYS ? process.env.KEYS.split(',') : ['koa3-cli-secret-key'],
-
-  // Static assets
-  static: {
-    enable: true,
-    dir: 'public',
-    options: {
-      maxAge: 365 * 24 * 60 * 60 * 1000,
-      gzip: true
-    }
-  },
-
-  // Docs build config
-  docs: {
-    enable: true,
-    buildDir: 'public/docs'
-  },
-
-  // View engine
-  view: {
-    enable: true,
-    root: 'app/view',
-    options: {
-      extension: 'ejs',
-      map: {
-        html: 'ejs'
-      }
-    }
-  },
-
-  // bodyParser
-  bodyParser: {
-    enableTypes: ['json', 'form', 'text'],
-    jsonLimit: '10mb',
-    formLimit: '10mb'
-  },
-
-  // Database (example)
-  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 (example)
-  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
-  logger: {
-    level: process.env.LOG_LEVEL || 'info',
-    dir: process.env.LOG_DIR || 'logs',
-    enableConsole: process.env.LOG_ENABLE_CONSOLE !== 'false',
-    enableFile: process.env.LOG_ENABLE_FILE !== 'false'
-  }
+/**
+ * Default config loaded in all environments.
+ */
+module.exports = {
+  // Application name
+  name: 'koa3-cli',
+
+  // Runtime env: development, production, test
+  env: process.env.NODE_ENV || 'development',
+
+  // Server port
+  port: process.env.PORT || 3000,
+
+  // Cookie signing keys
+  keys: process.env.KEYS ? process.env.KEYS.split(',') : ['koa3-cli-secret-key'],
+
+  // Static assets
+  static: {
+    enable: true,
+    dir: 'public',
+    options: {
+      maxAge: 365 * 24 * 60 * 60 * 1000,
+      gzip: true
+    }
+  },
+
+  // Docs build config
+  docs: {
+    enable: true,
+    buildDir: 'public/docs'
+  },
+
+  // View engine
+  view: {
+    enable: true,
+    root: 'app/view',
+    options: {
+      extension: 'ejs',
+      map: {
+        html: 'ejs'
+      }
+    }
+  },
+
+  // bodyParser
+  bodyParser: {
+    enableTypes: ['json', 'form', 'text'],
+    jsonLimit: '10mb',
+    formLimit: '10mb'
+  },
+
+  // Database (example)
+  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 (example)
+  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
+  logger: {
+    level: process.env.LOG_LEVEL || 'info',
+    dir: process.env.LOG_DIR || 'logs',
+    enableConsole: process.env.LOG_ENABLE_CONSOLE !== 'false',
+    enableFile: process.env.LOG_ENABLE_FILE !== 'false'
+  }
 };

package/config/loader.js

@@ -0,0 +1,25 @@
+/**
+ * 配置加载器：合并 default + 环境配置
+ */
+const path = require('path');
+
+const defaultConfig = require('./config.default');
+
+function loadConfig() {
+  const env = process.env.NODE_ENV || 'development';
+  let envConfig = {};
+
+  try {
+    if (env === 'production') {
+      envConfig = require('./config.prod');
+    } else if (env === 'local' || env === 'development') {
+      envConfig = require('./config.local');
+    }
+  } catch (e) {
+    // 忽略缺失的环境配置文件
+  }
+
+  return Object.assign({}, defaultConfig, envConfig);
+}
+
+module.exports = { loadConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koa3-cli",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "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",