mm_api 1.1.0 → 1.1.2

package/lib/manager.js

@@ -1,12 +1,12 @@
-const Manager = require("mm_corejs").Manager;
-const Drive = require("./drive");
+const Manager = require('mm_machine').Manager;
+const Api = require("./api");
 
 /**
- * Api接口类（Web API 网关管理器，基于 mm_corejs，无全局/原型扩展依赖）
+ * ApiManager接口类（Web API 网关管理器，基于 mm_corejs，无全局/原型扩展依赖）
  * @class
  * @augments {Manager}
  */
-class Api extends Manager {
+class ApiManager extends Manager {
   /**
    * 配置参数
    * @type {object}
@@ -55,25 +55,50 @@ class Api extends Manager {
    * @param {object} parent 父级模块（仅作兼容传入，不使用）
    */
   constructor(config, parent) {
-    super({ ...Api.config, ...config }, parent);
-    // 插件注册表（方案B：手动注册，供驱动 plugin() 查找）
-    this.plugins = {};
+    super({ ...ApiManager.config, ...config }, parent);
   }
 }
 
 /**
- * Api驱动类
+ * ApiManager驱动类
  * @type {Drive}
  */
-Api.prototype.Drive = Drive;
+ApiManager.prototype.Drive = Api;
+
+/**
+ * 初始化桥接（生命周期汇聚点：init() 与 do('init') 均调用，触发 onInit）
+ * @returns {Promise<void>} 初始化完成
+ * @private
+ */
+ApiManager.prototype._init = async function () {
+  await this.onInit();
+};
+
+/**
+ * 启动桥接（生命周期汇聚点，触发 onStart）
+ * @returns {Promise<void>} 启动完成
+ * @private
+ */
+ApiManager.prototype._start = async function () {
+  await this.onStart();
+};
+
+/**
+ * 停止桥接（生命周期汇聚点，触发 onStop）
+ * @returns {Promise<void>} 停止完成
+ * @private
+ */
+ApiManager.prototype._stop = async function () {
+  await this.onStop();
+};
 
 /**
  * 注册一个 api 驱动（方案B：手动注册，不扫描目录）
  * @param {object} config 驱动配置（必须包含 name）
  * @returns {object} 驱动实例
  */
-Api.prototype.add = function (config) {
-  var drive = new Drive({ ...config }, this);
+ApiManager.prototype.add = function (config) {
+  var drive = new this.Drive(config, this);
   this.set(drive.config.name, drive);
   return drive;
 };
@@ -83,7 +108,7 @@ Api.prototype.add = function (config) {
  * @param {string} name 驱动名称
  * @returns {Promise<boolean>} 是否删除成功
  */
-Api.prototype.del = async function (name) {
+ApiManager.prototype.del = async function (name) {
   var drive = this.get(name);
   if (drive) {
     await drive.stop();
@@ -97,7 +122,7 @@ Api.prototype.del = async function (name) {
  * @param {string} name 驱动名称
  * @returns {Promise<boolean>} 是否执行成功
  */
-Api.prototype.reload = async function (name) {
+ApiManager.prototype.reload = async function (name) {
   var drive = this.get(name);
   if (!drive) {
     this.log("warn", "驱动不存在，无法重启", name);
@@ -115,26 +140,13 @@ Api.prototype.reload = async function (name) {
 };
 
 /**
- * 注册插件集合（供驱动 plugin() 查找，替代原全局插件池）
- * @param {string} name 插件作用域名称（app 名）
- * @param {object} obj 插件集合对象（需含 get 方法）
- * @returns {object} 当前管理器实例
- */
-Api.prototype.usePlugin = function (name, obj) {
-  this.plugins[name] = obj;
-  return this;
-};
-
-/**
- * 初始化驱动实例（仅未初始化时执行生命周期 init，重复调用安全）
+ * 初始化驱动实例（执行生命周期 init）
  * @param {object} drive 驱动实例
  * @returns {Promise<void>} 初始化完成
  * @private
  */
-Api.prototype._initDrive = async function (drive) {
-  if (drive.isState("created")) {
-    await drive.init();
-  }
+ApiManager.prototype._initDrive = async function (drive) {
+  await drive.init();
 };
 
 /**
@@ -142,7 +154,7 @@ Api.prototype._initDrive = async function (drive) {
  * @returns {Array} 驱动配置数组
  * @private
  */
-Api.prototype._getInfos = function () {
+ApiManager.prototype._getInfos = function () {
   return this.values().map((d) => d.config);
 };
 
@@ -152,7 +164,7 @@ Api.prototype._getInfos = function () {
  * @returns {Array} 驱动实例数组
  * @private
  */
-Api.prototype._sortedDrives = function () {
+ApiManager.prototype._sortedDrives = function () {
   var sort_key = this.config.sort_key || "sort";
   var drives = this.values().filter((d) => d.config.state === 1);
   drives.sort((m1, m2) => {
@@ -174,7 +186,7 @@ Api.prototype._sortedDrives = function () {
  * @param {string} pattern 模式
  * @returns {boolean} 是否匹配
  */
-Api.prototype.isMatch = function (str, pattern) {
+ApiManager.prototype.isMatch = function (str, pattern) {
   if (str === pattern) {
     return true;
   } else if (pattern.startsWith("*")) {
@@ -193,32 +205,51 @@ Api.prototype.isMatch = function (str, pattern) {
 };
 
 /**
- * 执行Api
- * @param {object} ctx 请求上下文
- * @param {object} db 数据管理器
+ * 获取运行参数：兼容 run(ctx, options) 与历史写法 run(params, ctx, options)
+ * @param {object} first 请求上下文或参数对象
+ * @param {object} second 数据管理器或请求上下文
+ * @param {object} third 数据管理器
+ * @returns {object} 含 params、ctx、options 的参数集合
+ */
+ApiManager.prototype._getRunArgs = function (first, second, third) {
+  if (first && first.request) {
+    return { params: first.params || {}, ctx: first, options: second || {} };
+  }
+  return { params: first || {}, ctx: second || {}, options: third || {} };
+};
+
+/**
+ * 执行ApiManager
+ * @param {object} ctx 请求上下文，或历史写法中的参数对象
+ * @param {object} options 数据管理器，如: { next: async function{}, ret: {} }
  * @returns {object | string} 返回一个对象或字符串
  */
-Api.prototype.run = async function (ctx, options = {}) {
-  let path = ctx.request.path;
+ApiManager.prototype.run = async function (ctx, options = {}) {
+  let args = this._getRunArgs(ctx, options, arguments[2]);
+  let path = args.ctx.request.path;
   let drives = this._sortedDrives();
+  let result = null;
 
   for (var i = 0; i < drives.length; i++) {
     var mod = drives[i];
     if (this.isMatch(path, mod.config.path)) {
-      if (!mod.isLoaded()) {
+      if (!(await mod.isLoaded())) {
         await mod.load();
       }
-      var ret = await mod.run(ctx, options);
+      var ret = await mod.run(args.params, args.ctx, args.options);
       if (ret) {
-        db.ret = ret;
+        // 同时写入上下文与数据管理器，兼容两种结果读取方式
+        args.ctx.result = ret;
+        args.options.ret = ret;
+        result = ret;
         break;
       }
     }
   }
-  return db.ret;
+  return result;
 };
 
 /**
  * @module 导出API管理器类
  */
-module.exports = Api;
+module.exports = ApiManager;

package/lib/oauth.js

@@ -1,59 +1,6 @@
 const fs = require("fs");
 const path = require("path");
-const { string } = require("mm_helper");
-
-/**
- * 转换值类型（等价复刻 mm_expand 的 convertValue）
- * @param {any} target_val 目标值
- * @param {any} source_val 源值
- * @returns {any} 转换后的值
- */
-function _convertValue(target_val, source_val) {
-  var target_type = typeof target_val;
-  if (target_type === "number") {
-    var num = Number(source_val);
-    return isNaN(num) ? 0 : num;
-  } else if (target_type === "boolean") {
-    if (source_val === "0" || source_val === "false" || source_val === "False") {
-      return false;
-    } else if (source_val === "1" || source_val === "true" || source_val === "True") {
-      return true;
-    } else {
-      return Boolean(source_val);
-    }
-  } else if (target_type === "string") {
-    return String(source_val);
-  } else {
-    return source_val;
-  }
-}
-
-/**
- * 添加对象属性（替代原全局 push，等价复刻 mm_expand 的 push）
- * @param {object} target 被添加的对象
- * @param {object} source 用作添加的对象
- * @param {boolean} supplement 是否补充没有的对象
- * @returns {object} 修改后的目标对象
- */
-function _push(target, source, supplement = false) {
-  if (!target || !source || typeof target !== "object" || typeof source !== "object") {
-    return target;
-  }
-  for (var key in source) {
-    if (target.hasOwnProperty(key)) {
-      var target_val = target[key];
-      var source_val = source[key];
-      if (typeof target_val === "object" && typeof source_val === "object") {
-        _push(target_val, source_val, supplement);
-      } else if (typeof target_val === typeof source_val) {
-        target[key] = _convertValue(target_val, source_val);
-      }
-    } else if (supplement) {
-      target[key] = source[key];
-    }
-  }
-  return target;
-}
+const { string, object } = require("mm_helper");
 
 /**
  * Oauth身份验证驱动类
@@ -108,14 +55,14 @@ Oauth.prototype.getDir = function () {
  * @param {object} obj 配置对象
  */
 Oauth.prototype.loadObj = function (obj) {
-  _push(this.config, obj);
+  object.push(this.config, obj);
   var f = this.config.main;
   if (f) {
     var file = path.isAbsolute(f) ? f : path.resolve(this.getDir(), f);
     if (fs.existsSync(file)) {
       var cs = require(file);
       if (cs) {
-        _push(this, cs, true);
+        object.push(this, cs, true);
       }
     }
   }

package/package.json

@@ -1,29 +1,35 @@
 {
-  "name": "mm_api",
-  "version": "1.1.0",
-  "description": "API框架，用于实现web api和mvc模式路由请求，负责配置路由路径、访问权限、校验机制；基于 mm_corejs，内置管理器池，无全局/原型扩展依赖",
-  "main": "index.js",
-  "keywords": [
-    "mm_mod",
-    "mm_port",
-    "mm_in_port",
-    "api",
-    "mvc",
-    "router",
-    "oauth",
-    "API管理器"
-  ],
-  "layer": "port",
-  "group": "web",
-  "author": "邱文武",
-  "license": "ISC",
-  "dependencies": {
-    "mm_corejs": "^1.1.4",
-    "mm_param": "^1.1.0",
-    "mm_helper": "^1.0.0",
-    "mm_sql": "^1.8.0"
-  },
-  "scripts": {
-    "test": "node test.js"
-  }
+    "name": "mm_api",
+    "version": "1.1.2",
+    "description": "API框架，用于实现web api和mvc模式路由请求，负责配置路由路径、访问权限、校验机制；基于 mm_corejs，内置管理器池，无全局/原型扩展依赖",
+    "main": "index.js",
+    "keywords": [
+        "mm_mod",
+        "mm_port",
+        "mm_in_port",
+        "api",
+        "mvc",
+        "router",
+        "oauth",
+        "API管理器"
+    ],
+    "layer": "port",
+    "group": "web",
+    "author": "邱文武",
+    "license": "ISC",
+    "repository": {
+        "type": "git",
+        "url": "git+https://gitee.com/qiuwenwu91/mm_api.git"
+    },
+    "dependencies": {
+        "mm_corejs": "^1.1.4",
+        "mm_helper": "^1.0.0",
+        "mm_machine": "^3.5.4",
+        "mm_param": "^1.1.0",
+        "mm_ret": "^1.4.8",
+        "mm_sql": "^1.8.0"
+    },
+    "scripts": {
+        "test": "node test.js && node --test tests/*.test.js"
+    }
 }

package/script.tpl.js

@@ -6,7 +6,7 @@ module.exports = {
    * @param {object} db 数据管理器,如: { next: async function{}, ret: {} }
    * @returns {object} 执行结果
    */
-  async main(ctx, options) {
+  async main(params, ctx, options) {
     // 获取请求参数
     var req = ctx.request;
     var {

package/tests/api.test.js

@@ -0,0 +1,167 @@
+'use strict';
+
+/**
+ * Api 接口驱动测试
+ * @description 覆盖脚本加载、请求执行、方法过滤、参数校验与异常路径
+ */
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const Api = require('../lib/api.js');
+const { makeCtx, makeOptions } = require('./helper.js');
+
+test('load 加载脚本并挂载 main', () => {
+  const api = new Api({
+    name: 'hello',
+    path: '/hello',
+    dir: __dirname,
+    main: './fixtures/hello.js'
+  });
+  assert.strictEqual(api.isLoaded(), false, '初始未加载');
+  const mod = api.load();
+  assert.ok(mod, 'load 应返回脚本模块');
+  assert.strictEqual(api.isLoaded(), true, '加载后应标记已加载');
+  assert.strictEqual(typeof api.main, 'function', 'main 应挂载为函数');
+});
+
+test('load 不存在的脚本返回 null', () => {
+  const api = new Api({
+    name: 'miss',
+    path: '/miss',
+    dir: __dirname,
+    main: './fixtures/not_exist.js'
+  });
+  const mod = api.load();
+  assert.strictEqual(mod, null);
+  assert.strictEqual(api.isLoaded(), false);
+});
+
+test('run 执行脚本返回 JSON 字符串', async () => {
+  const api = new Api({
+    name: 'hello',
+    path: '/hello',
+    method: 'ALL',
+    dir: __dirname,
+    main: './fixtures/hello.js'
+  });
+  assert.ok(api.load(), '应先加载脚本');
+  const ctx = makeCtx({ path: '/hello', method: 'GET' });
+  const ret = await api.run({}, ctx, makeOptions());
+  assert.ok(ret, 'run 应返回结果');
+  assert.deepStrictEqual(JSON.parse(ret), {
+    code: 0,
+    message: '成功',
+    data: { hello: 'world' }
+  });
+});
+
+test('run 回显查询参数与正文', async () => {
+  const api = new Api({
+    name: 'echo',
+    path: '/echo',
+    method: 'ALL',
+    dir: __dirname,
+    main: './fixtures/echo.js'
+  });
+  assert.ok(api.load(), '应先加载脚本');
+  const ctx = makeCtx({
+    path: '/echo',
+    method: 'POST',
+    query: { a: '1' },
+    body: { b: '2' }
+  });
+  const ret = await api.run({}, ctx, makeOptions());
+  assert.deepStrictEqual(JSON.parse(ret), {
+    query: { a: '1' },
+    body: { b: '2' }
+  });
+});
+
+test('run 方法不匹配返回 null', async () => {
+  const api = new Api({
+    name: 'hello',
+    path: '/hello',
+    method: 'POST',
+    dir: __dirname,
+    main: './fixtures/hello.js'
+  });
+  const ctx = makeCtx({ path: '/hello', method: 'GET' });
+  const ret = await api.run({}, ctx, makeOptions());
+  assert.strictEqual(ret, null);
+});
+
+test('run 脚本抛错返回错误响应', async () => {
+  const api = new Api({
+    name: 'error',
+    path: '/error',
+    method: 'ALL',
+    dir: __dirname,
+    main: './fixtures/error.js'
+  });
+  const ctx = makeCtx({ path: '/error', method: 'GET' });
+  const ret = await api.run({}, ctx, makeOptions());
+  assert.ok(ret, 'run 应返回结果');
+  const obj = JSON.parse(ret);
+  assert.ok(obj.error, '应返回错误对象');
+  assert.strictEqual(obj.error.code, 10000);
+});
+
+test('main 未定义脚本返回错误响应', async () => {
+  const api = new Api({
+    name: 'hello',
+    path: '/hello',
+    method: 'ALL',
+    dir: __dirname,
+    main: './fixtures/hello.js'
+  });
+  // 覆盖 main 为 null，模拟脚本无主函数
+  api.main = null;
+  const ctx = makeCtx({ path: '/hello', method: 'GET' });
+  const ret = await api.run({}, ctx, makeOptions());
+  assert.ok(ret);
+  const obj = JSON.parse(ret);
+  assert.ok(obj.error, '应返回错误对象');
+  assert.strictEqual(obj.error.code, 10000);
+});
+
+test('加载参数配置并校验通过', () => {
+  const api = new Api({
+    name: 'param',
+    path: '/param',
+    method: 'ALL',
+    dir: __dirname,
+    param_path: './fixtures/param.json'
+  });
+  assert.ok(api.param, '应加载参数驱动');
+  const error = api.checkParam({ name: '张三' }, {}, 'GET');
+  assert.strictEqual(error, null, '参数正确时校验应通过');
+});
+
+test('参数校验失败返回错误', () => {
+  const api = new Api({
+    name: 'param',
+    path: '/param',
+    method: 'ALL',
+    dir: __dirname,
+    param_path: './fixtures/param.json'
+  });
+  assert.ok(api.param, '应加载参数驱动');
+  const error = api.checkParam({}, {}, 'GET');
+  assert.ok(error, '缺少必填参数应返回错误');
+  assert.ok(error.error, '错误应为响应格式');
+  assert.strictEqual(error.error.code, 30001, '必填缺失错误码应为 30001');
+});
+
+test('check 包含参数校验与身份校验', async () => {
+  const api = new Api({
+    name: 'hello',
+    path: '/hello',
+    method: 'ALL',
+    dir: __dirname,
+    main: './fixtures/hello.js',
+    check_param: false
+  });
+  const ctx = makeCtx({ path: '/hello', method: 'GET' });
+  const error = await api.check({}, ctx, makeOptions());
+  assert.strictEqual(error, null, '无需登录且无参数校验时应通过');
+});

package/tests/fixtures/echo.js

@@ -0,0 +1,14 @@
+'use strict';
+
+module.exports = {
+  /**
+   * 接口主函数
+   * @param {object} ctx HTTP上下文
+   * @param {object} options 数据管理器
+   * @returns {object} 执行结果
+   */
+  async main(params, ctx, options) {
+    const req = ctx.request;
+    return { query: req.query, body: req.body };
+  }
+};

package/tests/fixtures/error.js

@@ -0,0 +1,13 @@
+'use strict';
+
+module.exports = {
+  /**
+   * 接口主函数（总是抛错，用于测试异常路径）
+   * @param {object} ctx HTTP上下文
+   * @param {object} options 数据管理器
+   * @returns {object} 执行结果
+   */
+  async main(params, ctx, options) {
+    throw new Error('模拟脚本异常');
+  }
+};

package/tests/fixtures/hello.js

@@ -0,0 +1,13 @@
+'use strict';
+
+module.exports = {
+  /**
+   * 接口主函数
+   * @param {object} ctx HTTP上下文
+   * @param {object} options 数据管理器
+   * @returns {object} 执行结果
+   */
+  async main(params, ctx, options) {
+    return { code: 0, message: '成功', data: { hello: 'world' } };
+  }
+};

package/tests/fixtures/param.json

@@ -0,0 +1,19 @@
+{
+  "name": "param",
+  "title": "参数配置",
+  "get": {
+    "query": ["name"],
+    "query_required": ["name"]
+  },
+  "list": [
+    {
+      "name": "name",
+      "title": "名称",
+      "type": "string",
+      "string": {
+        "not_empty": true,
+        "max": 10
+      }
+    }
+  ]
+}

package/tests/helper.js

@@ -0,0 +1,57 @@
+'use strict';
+
+/**
+ * 构造模拟 HTTP 请求上下文
+ * @param {object} cfg 配置项
+ * @param {string} cfg.path 请求路径
+ * @param {string} cfg.method 请求方法
+ * @param {object} cfg.query URL 参数
+ * @param {object} cfg.body 正文参数
+ * @param {object} cfg.headers 请求头
+ * @param {string} cfg.type 请求类型
+ * @returns {object} 请求上下文
+ */
+function makeCtx(cfg = {}) {
+  const req = {
+    path: cfg.path || '/',
+    method: cfg.method || 'GET',
+    query: cfg.query || {},
+    body: cfg.body || {},
+    headers: cfg.headers || {},
+    type: cfg.type || 'json',
+    url: cfg.url || (cfg.path || '/')
+  };
+  return {
+    request: req,
+    response: { type: '' },
+    session: {},
+    headers: req.headers,
+    set(key, value) {
+      this.response[key] = value;
+    },
+    get status() {
+      return this.response.status;
+    },
+    set status(value) {
+      this.response.status = value;
+    }
+  };
+}
+
+/**
+ * 构造数据管理器
+ * @returns {object} 数据管理器
+ */
+function makeOptions() {
+  return {
+    ret: null,
+    new() {
+      return this;
+    },
+    getObj() {
+      return null;
+    }
+  };
+}
+
+module.exports = { makeCtx, makeOptions };