jj.js 0.8.3 → 0.8.6

package/README.md

@@ -30,7 +30,7 @@ A simple and lightweight MVC framework built on nodejs+koa2（一个基于nodejs
 npm i jj.js
 ```
 
-> 运行环境要求：node.js >= v12
+> 运行环境要求：node.js >= v12 mysql >= 5.3
 
 ## Hello world !
 
@@ -105,7 +105,6 @@ node server.js
 - **public**：静态资源目录，主要存放css文件、js文件、图片等静态资源。在`./config/app.js`中通过`static_dir`参数可以设置或更改静态目录名字，为空时，则关闭静态访问（系统不会加载静态资源访问的逻辑，最大节省内容，也即所谓的轻量）
 - **server.js**：应用入口文件，名字可以任意改。
 
-> 
 ### 系统类库
 
 ```javascript
@@ -276,6 +275,16 @@ module.exports = Index;
 
 > 注意：所有的输出和跳转并不会阻止后续代码执行，所以要终止代码执行，需在前面加上`return`。
 
+> 方法：**async _init()** 控制器初始化
+
+异步方法，除了使用控制器中间件执行一些初始化或验证外，控制器提供了这个更简单的方法。一旦控制器定义了这个方法，在通过url访问控制器其他公开方法时，在执行完控制器中间件后，都会先执行这个函数，如果想终止后续代码执行，可以在方法里返回`false`。
+
+> 方法：**async _end()** 控制器结束
+
+如果定义了这个函数，在通过url访问控制器其他公开方法后，会调用这个函数。
+
+> 注意：因为系统默认注册了 `应用/控制器/方法` 的全局路由，所以控制器里的方法都能被直接访问，如果想作为私有方法不被访问，可以在方法前加下划线`_`前缀。
+
 ### Middleware中间件类
 
 > 方法：**$show(content)** 参照控制器类介绍
@@ -290,9 +299,9 @@ module.exports = Index;
 
 ### Db数据库类
 
-> 方法：**async startTrans(async fun)** 开启事务
+> 方法：**async startTrans(fun)** 开启事务
 
-异步方法，如果fun不为空，并且是函数，则开启事务后，会自动执行此函数，并提交事务，不用再手工提交或回滚事务。
+异步方法，如果`fun`不为空，并且是函数，则开启事务后，会自动执行此函数，并提交事务，不用再手工提交或回滚事务。`fun`为异步函数。
 
 > 方法：**async commit()** 提交事务
 
@@ -727,9 +736,9 @@ module.exports = route;
 
 应用配置不用每项都设置，只设置自己需要改的，默认会继承框架的默认配置，在控制器、中间件、模板类、模型类里都可以通过`this.$config.xxx`使用。
 
-app配置`.config/app.js`：
+- app配置`.config/app.js`：
 ```javascript
-{
+const app = {
     app_debug: true, // 调试模式
     app_multi: false, // 是否开启多应用
 
@@ -744,20 +753,22 @@ app配置`.config/app.js`：
 
     koa_body: null // koa-body配置参数，为''、null、false时，关闭koa-body，此时upload类将不可用，并且系统接收不到post参数。启用的话，建议配置：{multipart: true, formidable: {keepExtensions: true, maxFieldsSize: 10 * 1024 * 1024}}
 }
+module.exports = app;
 ```
-模板配置`.config/view.js`：
+- 模板配置`.config/view.js`：
 ```javascript
-{
+const view = {
     view_folder: 'view', // 模板目录名
     view_depr: '/', // 模版文件名分割符，'/'代表二级目录
     view_ext: '.htm', // 模版文件后缀
     view_engine: 'art-template', // 默认模版引擎，字符串或引擎类，咱不支持更换
     view_filter: {}, // 模版函数，配置注入模板的函数，默认会自动注入url函数
 }
+module.exports = view;
 ```
-数据库配置`.config/db.js`：可以配置多个，方便程序里切换使用。
+- 数据库配置`.config/db.js`：可以配置多个，方便程序里切换使用。
 ```javascript
-{
+const db = {
     default: {
         type      : 'mysql', // 数据库类型
         host      : '127.0.0.1', // 服务器地址
@@ -769,24 +780,27 @@ app配置`.config/app.js`：
         prefix    : 'jj_' // 数据库表前缀
     }
 }
+module.exports = db;
 ```
-日志配置`.config/log.js`：log_handle可以自定义日志handle
+- 日志配置`.config/log.js`：log_handle可以自定义日志handle
 ```javascript
-{
+const log = {
     log_level: [], // [error, warning, info, debug, http, sql]
     log_handle: function(msg, level) {console.log(`[${format('YY-mm-dd HH:ii:ss')}] [${level}] ${typeof msg == 'String' ? msg : JSON.stringify(msg)}`);} //function(msg, level) {}
 }
+module.exports = log;
 ```
-缓存配置`.config/cache.js`：
+- 缓存配置`.config/cache.js`：
 ```javascript
-{
+const cache = {
     cache_time: 60 * 60 * 24, // 默认缓存时间（1天），为空或false则为10年
     clear_time: undefined // (undefined: 一天清理一次, 0: 关闭自动清理, >0: 为自动清理周期)
 }
+module.exports = cache;
 ```
-分页配置`.config/page.js`：
+- 分页配置`.config/page.js`：
 ```javascript
-{
+const page = {
     page_key    : 'page', // 默认分页标识
     key_origin    : 'query', // query 或 params
     page_size   : 10, // 默认分页大小
@@ -810,22 +824,65 @@ app配置`.config/app.js`：
     //渲染模版
     template   : '<div class="pagination"><ul class="page">${index}${prev}${list}${next}${end}</ul>${info}</div>'
 }
+module.exports = page;
 ```
-跳转模板配置`.config/tpl.js`：模板可以配置为自定义的
+- 跳转模板配置`.config/tpl.js`：模板可以配置为自定义的
 ```javascript
-{
+const tpl = {
     jump: require('./tpl/jump'), // 跳转模板
     exception: require('./tpl/exception') //  异常页面模板
 }
+module.exports = tpl;
 ```
-自定义配置`.config/self.js`：自定义配置同样可以直接通过`this.$config.self`使用。
+- 自定义配置`.config/self.js`：自定义配置同样可以直接通过`this.$config.self`使用。
 ```javascript
-{
+const self = {
     option1: ''
     option2: ''
     ...
 }
+module.exports = self;
+```
+- 路由配置`.config/routes.js`：
+路由功能基于`@koa/router`开发，关于url匹配规则可以参考官方文档：[文档地址](https://www.npmjs.com/package/@koa/router)
+
+> 本框架默认内置 `应用/控制器/方法` 的全局路由，即如果不需要定制url，可以直接访问，无需配置路由。
+
+> 路由配置为一个数组，每一项为一条规则，项属性包含url规则，path访问路径，name规则名字，type路由类型。url一旦匹配，即会停止，如果需要继续向下匹配，需在程序内调用 `await this.$next();`，路由配置参考示例：
+```javascript
+routes = [
+    {url: '/', path: 'app/index/index2'}, // 访问'/'，会定位到app应用的index控制的index2方法
+    {url: '/article/:id.html', path: 'app/article/article', name: 'article'}, // 访问'/article/123.html'，会定位到app应用的article控制的article方法；通过this.ctx.params.id可以获取到参数id；通过article可以反编译网址，执行this.$url.build(':article', {id: 123}); 生成'/article/123.html'
+    {url: '/admin', path: 'app/admin/check', type: 'middleware'}, // 访问'/admin'，会定位到app应用的admin中间件的check方法
+    {url: '/about', path: 'app/about/index', type: 'view'}, // 访问'/about'，会定位到app应用的view模板目录about目录下的index.htm文件，并直接输出文件内容
+    {url: '/:cate/list_:page.html', path: 'cate/cate', name: 'cate_page'}, // 多参数分页示例
+    {url: '/hello', path: async (ctx, next) => {ctx.body = 'hello world, hello jj.js!';}} // 直接路由到函数
+];
+
+module.exports = routes;
+```
+> 注意：本路由配置示例前两条规则为常规用法，后面的非常规用法，不建议使用。如果是单应用模式，可以去掉path参数里的app。
+
+### 应用入口文件
+
+应用入口文件放在项目的根目录，名字可以任意改。
+
+示例文件 `./server.js`
+```javascript
+const {app, Logger} = require('jj.js');
+
+app.run(3000, '127.0.0.1', function(err){
+    !err && Logger.info('http server is ready on 3000');
+});
 ```
+其中`app`是一个koa实例，可以使用`use`方法添加应用级中间件，使用方法参考koa文档。`app`的`run`方法经过了封装，仅允许调用一次。其中`Logger`因为是一个静态类，所以可以直接调用`info`方法输出日志。
+
+## 总结
+
+通过以上文档，可以看到：
+1. jj.js是一个轻量的mvc框架，几乎所有文件不使用就不会调用。
+2. 同时也是个功能强大的框架，支持应用级、路由级、控制器级三级中间件。
+3. 类库自动加载，只要是继承自`Context`的类库，都可以在方法内使用包含`$`前缀的属性自动加载其他资源。
 
 ## 应用案例
 

package/lib/db.js

@@ -66,10 +66,10 @@ class Db extends Context
         if(pool.has(this._config)) {
             pool.get(this._config).end(err => {
                 if(err) {
-                    const message = '连接池销毁失败：' + err['message'];
+                    const message = '连接池销毁失败：' + err.message;
                     this.$logger.sql(message);
                     this.$logger.error(message);
-                    throw new Error(message);
+                    throw new Error('DbError: ' + message);
                 } else {
                     pool.delete(this._config);
                     this.$logger.sql(`连接池销毁成功：{poolTotal: ${pool.size}}`);
@@ -95,10 +95,10 @@ class Db extends Context
         return new Promise((resolve, reject) => {
             p.getConnection((err, connection) => {
                 if(err) {
-                    const message = '获取数据库连接失败：' + err['message'];
+                    const message = '获取数据库连接失败：' + err.message;
                     this.$logger.sql(message);
                     this.$logger.error(message);
-                    reject(new Error(message));
+                    reject(new Error('DbError: ' + message));
                 } else {
                     this.$logger.sql(`获取数据库连接：{limit: ${p.config.connectionLimit}, all: ${p._allConnections.length}, acquiring: ${p._acquiringConnections.length}, free: ${p._freeConnections.length}, queue: ${p._connectionQueue.length}}`);
                     resolve(connection);
@@ -134,10 +134,10 @@ class Db extends Context
         return new Promise((resolve, reject) => {
             conn.beginTransaction(async (err) => {
                 if(err) {
-                    const message = '开启事务失败：' + err['message'];
+                    const message = '开启事务失败：' + err.message;
                     this.$logger.sql(message);
                     this.$logger.error(message);
-                    reject(new Error(message));
+                    reject(new Error('DbError: ' + message));
                 } else {
                     const message = '开启事务成功！';
                     this.$logger.sql(message);
@@ -195,11 +195,11 @@ class Db extends Context
         return new Promise((resolve, reject) => {
             conn.commit((err) => {
                 if(err) {
-                    const message = '事务提交失败：' + err['message'];
+                    const message = '事务提交失败：' + err.message;
                     this.$logger.sql(message);
                     this.$logger.error(message);
                     this.rollback();
-                    reject(new Error(message));
+                    reject(new Error('DbError: ' + message));
                 } else {
                     trans.delete(this.ctx);
                     const message = '事务提交成功！';
@@ -220,10 +220,10 @@ class Db extends Context
         return new Promise((resolve, reject) => {
             conn.query(sql, params, (err, data) => {
                 if(err) {
-                    const message = '数据操作失败，SQL：' + this.format(sql, params) + '（' + err['message'] + '）';
+                    const message = '数据操作失败，' + err.message + "\r\nSQL：" + this.format(sql, params);
                     this.$logger.sql(message);
                     this.$logger.error(message);
-                    reject(new Error(message));
+                    reject(new Error('DbError: ' + message));
                 } else {
                     this.$logger.sql('数据操作成功，SQL：' + this.format(sql, params));
                     resolve(data);
@@ -506,7 +506,7 @@ class Db extends Context
         if(!where[0]) {
             const message = 'update方法必须传入where参数';
             this.$logger.sql(message);
-            throw new Error(message);
+            throw new Error('DbError: ' + message);
         }
         params = params.concat(where[1]);
 
@@ -539,7 +539,7 @@ class Db extends Context
         if(!where[0]) {
             const message = 'delete方法必须传入where参数';
             this.$logger.sql(message);
-            throw new Error(message);
+            throw new Error('DbError: ' + message);
         }
         params = params.concat(where[1]);
 

package/lib/router.js

@@ -9,7 +9,7 @@ if (cfg_routes) {
     for(let item of cfg_routes){
         item.method || (item.method = 'all');
         if(!~methods.indexOf(item.method)) {
-            throw new Error(`未知路由方法：${item.method}`);
+            throw new Error(`RouteError: 未知路由方法：${item.method}`);
         }
         if(typeof item.path === 'function'){
             router[item.method](item.url, item.path);

package/lib/run.js

@@ -7,9 +7,13 @@ const compose = require('koa-compose');
 const Logger = require('./logger');
 
 async function run(ctx, next, control_type=cfg_app.controller_folder) {
-    Logger.debug(ctx.request);
-    Logger.debug(`Router: {APP: '${ctx.APP}', CONTROLLER: '${ctx.CONTROLLER}', ACTION: '${ctx.ACTION}'}`);
-    Logger.debug('Params/Get/Post:', ctx.params, ctx.query, ctx.request.body);
+    if(cfg_app.app_debug) {
+        Logger.debug(ctx.request);
+        Logger.debug(`Router(${control_type}): {APP: '${ctx.APP}', CONTROLLER: '${ctx.CONTROLLER}', ACTION: '${ctx.ACTION}'}`);
+        Object.keys(ctx.params).length && Logger.debug({Params: ctx.params});
+        Object.keys(ctx.query).length && Logger.debug({Get: ctx.query});
+        Object.keys(ctx.request.body || {}).length && Logger.debug({Post: ctx.request.body});
+    }
     
     // 设置根加载器
     ctx.$ = loader('./', ctx);
@@ -26,12 +30,12 @@ async function run(ctx, next, control_type=cfg_app.controller_folder) {
 
     // 应用、控制器、方法名字验证
     if (~ctx.APP.indexOf('.') || ~ctx.CONTROLLER.indexOf('.') || ~ctx.ACTION.indexOf('.')) {
-        throw new Error(`应用、控制器或方法名字不合法！`);
+        throw new Error(`RunError: 应用、控制器或方法名字不合法！`);
     }
 
     if (ctx.APP[0] == '_' || ctx.APP[0] == '$' || !ctx._[ctx.APP]) {
         if(cfg_app.app_debug) {
-            throw new Error(`应用:${ctx.APP}不存在！`);
+            throw new Error(`RunError: 应用:${ctx.APP}不存在！`);
         } else {
             return false;
         }
@@ -39,7 +43,7 @@ async function run(ctx, next, control_type=cfg_app.controller_folder) {
 
     if (!ctx._[ctx.APP][control_type]) {
         if(cfg_app.app_debug) {
-            throw new Error(`目录:${ctx.APP}/${control_type}不存在！`);
+            throw new Error(`RunError: 目录:${ctx.APP}/${control_type}不存在！`);
         } else {
             return false;
         }
@@ -49,7 +53,7 @@ async function run(ctx, next, control_type=cfg_app.controller_folder) {
     if(control_type == cfg_view.view_folder) {
         const content = await readFile(path.join(ctx._[ctx.APP][control_type].__node.path, ctx.CONTROLLER + cfg_view.view_depr + ctx.ACTION + cfg_view.view_ext));
         if(!content) {
-            throw new Error(`模板文件:${ctx.APP}/${control_type}/${ctx.CONTROLLER + cfg_view.view_depr + ctx.ACTION + cfg_view.view_ext}不存在！`);
+            throw new Error(`RunError: 模板文件:${ctx.APP}/${control_type}/${ctx.CONTROLLER + cfg_view.view_depr + ctx.ACTION + cfg_view.view_ext}不存在！`);
         }
         ctx.body = content;
         return;
@@ -60,7 +64,7 @@ async function run(ctx, next, control_type=cfg_app.controller_folder) {
 
     if (ctx.CONTROLLER[0] == '_' || ctx.CONTROLLER[0] == '$' || typeof Controller != 'function') {
         if(cfg_app.app_debug) {
-            throw new Error(`class文件:${ctx.APP}/${control_type}/${ctx.CONTROLLER}不存在！`);
+            throw new Error(`RunError: class文件:${ctx.APP}/${control_type}/${ctx.CONTROLLER}不存在！`);
         } else {
             return false;
         }
@@ -73,7 +77,7 @@ async function run(ctx, next, control_type=cfg_app.controller_folder) {
 
     if (ctx.ACTION[0] == '_' || ctx.ACTION[0] == '$' || typeof $controller[action] != 'function') {
         if(cfg_app.app_debug) {
-            throw new Error(`class方法:${ctx.APP}/${control_type}/${ctx.CONTROLLER}/${humpAction}不存在！`);
+            throw new Error(`RunError: class方法:${ctx.APP}/${control_type}/${ctx.CONTROLLER}/${humpAction}不存在！`);
         } else {
             return false;
         }
@@ -93,18 +97,18 @@ async function run(ctx, next, control_type=cfg_app.controller_folder) {
                 return stack.concat(async (ctx, next) => {
                     const [METHOD = action, MIDDLEWARE = ctx.CONTROLLER, APP = ctx.APP] = middle.middleware.split('/').reverse();
                     if(!ctx._[APP]) {
-                        throw new Error(`中间件应用:${APP}不存在！`);
+                        throw new Error(`RunError: 中间件应用:${APP}不存在！`);
                     }
                     if(!ctx._[APP]['middleware']) {
-                        throw new Error(`中间件目录:${APP}/middleware不存在！`);
+                        throw new Error(`RunError: 中间件目录:${APP}/middleware不存在！`);
                     }
                     const Middleware = ctx._[APP]['middleware'][MIDDLEWARE];
                     if(!Middleware || typeof Middleware != 'function') {
-                        throw new Error(`中间件文件:${APP}/middleware/${MIDDLEWARE}不存在！`);
+                        throw new Error(`RunError: 中间件文件:${APP}/middleware/${MIDDLEWARE}不存在！`);
                     }
                     const $middleware = new Middleware(ctx, next);
                     if(!$middleware[METHOD] || typeof $middleware[METHOD] != 'function') {
-                        throw new Error(`中间件方法:${APP}/middleware/${MIDDLEWARE}/${METHOD}不存在！`);
+                        throw new Error(`RunError: 中间件方法:${APP}/middleware/${MIDDLEWARE}/${METHOD}不存在！`);
                     }
 
                     // 执行中间件方法

package/lib/url.js

@@ -12,7 +12,7 @@ const {toLine} = require('./utils/str');
 class Url extends Context
 {
     build(url='', vars, ext='', domain='') {
-        if(typeof vars != 'object') {
+        if(vars && typeof vars != 'object') {
             [vars, ext, domain] = [{}, vars, ext];
         }
         const query = {...vars};
@@ -56,6 +56,7 @@ class Url extends Context
 
         if(~url.indexOf(':')) {
             url = url.replace(/\:([^./]+)/g, (match, key) => {
+                key = key.split('(')[0];
                 if(key in query) {
                     const value = query[key];
                     delete query[key];

package/lib/utils/error.js

@@ -1,29 +1,33 @@
+const fs = require('./fs.js');
+
 function parseError(err) {
-    let stack = err.stack;
-    stack = stack.replace(/(\r\n)|(\n)/g, '#split#');
-    stack = stack.split('#split#');
-    let msg = err.name;
+    let msg = err.message;
+    let stack = err.stack.replace(/(\r\n)/g, "\n").split("\n");
+
     if(err.name == 'TemplateError') {
-        msg = stack.pop();
+        msg = 'TemplateError: ' + stack.pop();
+        stack = [stack.shift().replace('TemplateError:', "at")];
     } else {
-        msg = stack.shift();
+        stack = stack.filter(text => {return /^    at /.test(text);});
     }
-    let file_info = stack[0].split(' ').slice(-1)[0].replace(/(\()|(\))/g, '').split(':');
+
+    const file_info = stack[0].split(' ').slice(-1)[0].replace(/(\()|(\))/g, '').split(':');
     const column = parseInt(file_info.pop());
     const row = parseInt(file_info.pop());
     const file_path = file_info.join(':');
     let begin = row - 10;
     let end = row + 10;
+    let nth = 0;
     let code = '';
     if(begin < 0) {
         end -= begin;
         begin = 0;
     }
-    if(file_path == 'anonymous') {
+    if(file_path == 'anonymous' || !file_path || !fs.isFileSync(file_path)) {
         code = stack;
     } else {
         code = require('fs').readFileSync(file_path);
-        code = code.toString().split("\n");
+        code = code.toString().replace(/(\r\n)/g, "\n").split("\n");
         if(begin < 0) {
             end -= begin;
             begin = 0;
@@ -36,9 +40,6 @@ function parseError(err) {
             begin = 0;
         }
         code = code.slice(begin, end);
-        if(err.name == 'TemplateError') {
-            stack = [stack[0]];
-        }
         nth = row - begin;
     }
     

package/lib/view.js

@@ -71,7 +71,7 @@ class View extends Context
         }
         if(!is_file) {
             file_name = this.parsePath(template, this._folder, this._depr);
-            throw new Error(`文件不存在(${file_name})`);
+            throw new Error(`ViewError: 文件不存在(${file_name})`);
         }
         return file_name;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jj.js",
-  "version": "0.8.3",
+  "version": "0.8.6",
   "description": "A simple and lightweight MVC framework built on nodejs+koa2",
   "main": "jj.js",
   "scripts": {