mm_api 0.0.0-stage → 1.1.0

package/lib/manager.js

@@ -0,0 +1,224 @@
+const Manager = require("mm_corejs").Manager;
+const Drive = require("./drive");
+
+/**
+ * Api接口类（Web API 网关管理器，基于 mm_corejs，无全局/原型扩展依赖）
+ * @class
+ * @augments {Manager}
+ */
+class Api extends Manager {
+  /**
+   * 配置参数
+   * @type {object}
+   */
+  static config = {
+    /**
+     * 名称
+     * @type {string}
+     */
+    name: "",
+    /**
+     * 标题
+     * @type {string}
+     */
+    title: "API接口",
+    /**
+     * 描述
+     * @type {string}
+     */
+    description: "这是API接口管理器",
+    /**
+     * 最大深度
+     * @type {number}
+     */
+    max_depth: 6,
+    /**
+     * 排序键（接口匹配排序用的配置字段名）
+     * @type {string}
+     */
+    sort_key: "sort",
+    /**
+     * 缓存实例获取函数（可选注入，返回 cache 实例；未配置则跳过接口缓存与缓存登录态）
+     * @type {Function|null}
+     */
+    get_cache: null,
+    /**
+     * 资源清单文件名（update 扫描目录时使用）
+     * @type {string}
+     */
+    filename: "api.json",
+  };
+
+  /**
+   * 构造函数
+   * @param {object} config 配置参数
+   * @param {object} parent 父级模块（仅作兼容传入，不使用）
+   */
+  constructor(config, parent) {
+    super({ ...Api.config, ...config }, parent);
+    // 插件注册表（方案B：手动注册，供驱动 plugin() 查找）
+    this.plugins = {};
+  }
+}
+
+/**
+ * Api驱动类
+ * @type {Drive}
+ */
+Api.prototype.Drive = Drive;
+
+/**
+ * 注册一个 api 驱动（方案B：手动注册，不扫描目录）
+ * @param {object} config 驱动配置（必须包含 name）
+ * @returns {object} 驱动实例
+ */
+Api.prototype.add = function (config) {
+  var drive = new Drive({ ...config }, this);
+  this.set(drive.config.name, drive);
+  return drive;
+};
+
+/**
+ * 注销一个 api 驱动（先停止再删除注册表项）
+ * @param {string} name 驱动名称
+ * @returns {Promise<boolean>} 是否删除成功
+ */
+Api.prototype.del = async function (name) {
+  var drive = this.get(name);
+  if (drive) {
+    await drive.stop();
+  }
+  return await Manager.prototype.del.call(this, name);
+};
+
+/**
+ * 重启一个 api 驱动（stop 后重新 start）
+ * 注意：生命周期状态机不支持 stopped 后再次 start，失败时需 del 后重新 add 实现手动重启
+ * @param {string} name 驱动名称
+ * @returns {Promise<boolean>} 是否执行成功
+ */
+Api.prototype.reload = async function (name) {
+  var drive = this.get(name);
+  if (!drive) {
+    this.log("warn", "驱动不存在，无法重启", name);
+    return false;
+  }
+  try {
+    await drive.stop();
+    await this._initDrive(drive);
+    await drive.start();
+    return true;
+  } catch (err) {
+    this.log("warn", "驱动重启失败（生命周期不支持停止后重启，请 del 后重新 add）", name, err);
+    return false;
+  }
+};
+
+/**
+ * 注册插件集合（供驱动 plugin() 查找，替代原全局插件池）
+ * @param {string} name 插件作用域名称（app 名）
+ * @param {object} obj 插件集合对象（需含 get 方法）
+ * @returns {object} 当前管理器实例
+ */
+Api.prototype.usePlugin = function (name, obj) {
+  this.plugins[name] = obj;
+  return this;
+};
+
+/**
+ * 初始化驱动实例（仅未初始化时执行生命周期 init，重复调用安全）
+ * @param {object} drive 驱动实例
+ * @returns {Promise<void>} 初始化完成
+ * @private
+ */
+Api.prototype._initDrive = async function (drive) {
+  if (drive.isState("created")) {
+    await drive.init();
+  }
+};
+
+/**
+ * 获取所有驱动配置列表（方案B：来自注册表，替代旧基类 getInfos）
+ * @returns {Array} 驱动配置数组
+ * @private
+ */
+Api.prototype._getInfos = function () {
+  return this.values().map((d) => d.config);
+};
+
+/**
+ * 获取按匹配优先级排序后的启用驱动列表
+ * 排序规则：路径长的优先，其次按排序键升序（保留原 _sort 的比较语义）
+ * @returns {Array} 驱动实例数组
+ * @private
+ */
+Api.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) => {
+    var p1 = m1.config.path || "";
+    var p2 = m2.config.path || "";
+    var n = p2.length - p1.length;
+    if (n) {
+      return n;
+    } else {
+      return m1.config[sort_key] - m2.config[sort_key];
+    }
+  });
+  return drives;
+};
+
+/**
+ * 匹配目标
+ * @param {string} str 目标
+ * @param {string} pattern 模式
+ * @returns {boolean} 是否匹配
+ */
+Api.prototype.isMatch = function (str, pattern) {
+  if (str === pattern) {
+    return true;
+  } else if (pattern.startsWith("*")) {
+    let clean = pattern.replaceAll("*", "");
+    if (pattern.endsWith("*")) {
+      return str.indexOf(clean) !== -1;
+    } else {
+      return str.endsWith(clean);
+    }
+  } else if (pattern.endsWith("*")) {
+    let clean = pattern.replaceAll("*", "");
+    return str.startsWith(clean);
+  } else {
+    return false;
+  }
+};
+
+/**
+ * 执行Api
+ * @param {object} ctx 请求上下文
+ * @param {object} db 数据管理器
+ * @returns {object | string} 返回一个对象或字符串
+ */
+Api.prototype.run = async function (ctx, options = {}) {
+  let path = ctx.request.path;
+  let drives = this._sortedDrives();
+
+  for (var i = 0; i < drives.length; i++) {
+    var mod = drives[i];
+    if (this.isMatch(path, mod.config.path)) {
+      if (!mod.isLoaded()) {
+        await mod.load();
+      }
+      var ret = await mod.run(ctx, options);
+      if (ret) {
+        db.ret = ret;
+        break;
+      }
+    }
+  }
+  return db.ret;
+};
+
+/**
+ * @module 导出API管理器类
+ */
+module.exports = Api;

package/lib/oauth.js

@@ -0,0 +1,277 @@
+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;
+}
+
+/**
+ * Oauth身份验证驱动类
+ * @class
+ */
+class Oauth {
+  static config = {
+    // 是否登录
+    'sign_in': false,
+    // 要求会员级别
+    'vip': 0,
+    // 要求管理级别
+    'gm': 0,
+    // 要求商户级别
+    'mc': 0,
+    // 要求用户组
+    'user_group': [],
+    // 要求管理组
+    'user_admin': [],
+    // 文件路径, 当调用函数不存在时，会先从文件中加载
+    'main': '',
+    // 当前目录（方案B：由驱动传入，替代旧基类 getDir）
+    'dir': '',
+    // 登录token请求头键名（替代原全局 dict 中的 token 键）
+    'token_key': 'token',
+    // 会话缓存键前缀（替代原全局 dict 中的 session_id 键）
+    'session_key': 'mm:uuid',
+    // 缓存实例获取函数（可选注入，未配置则跳过缓存登录态）
+    'get_cache': null
+  };
+  /**
+   * 构造函数
+   * @param {object} config 配置参数（含 dir/token_key/session_key/get_cache）
+   * @class
+   */
+  constructor(config) {
+    // 配置参数
+    this.config = { ...Oauth.config, ...config };
+  }
+}
+
+/**
+ * 获取当前目录（方案B：来自构造注入的 dir）
+ * @returns {string} 当前目录
+ */
+Oauth.prototype.getDir = function () {
+  return this.config.dir || __dirname;
+};
+
+/**
+ * 加载配置对象
+ * @param {object} obj 配置对象
+ */
+Oauth.prototype.loadObj = function (obj) {
+  _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);
+      }
+    }
+  }
+};
+
+/**
+ * 身份验证主程序
+ * @param {object} ctx HTTP请求上下文
+ * @returns {object} 验证失败返回错误提示，验证通过返回null
+ */
+Oauth.prototype.main = async function (ctx) {
+  return null;
+};
+
+/**
+ * 小校验
+ * @param {object} ctx HTTP请求上下文
+ */
+Oauth.prototype.checkSub = async function (ctx) {
+
+};
+
+/**
+ * 验证身份
+ * @param {object} ctx HTTP请求上下文
+ * @returns {object} 验证失败返回错误提示，验证通过返回null
+ */
+Oauth.prototype.check = async function (ctx) {
+  // 无需登录则不验证身份和权限
+  var cg = this.config;
+  var user = await this._getUser(ctx);
+  if (!cg.sign_in) {
+    return null;
+  }
+  var error = await this.main(ctx);
+  if (error) {
+    return error;
+  }
+  if (!user) {
+    return {
+      code: 60000,
+      message: '账户未登录!'
+    };
+  }
+  if (await this._checkAccess(user, cg)) {
+    return {
+      code: 70000,
+      message: '没有访问权限'
+    };
+  }
+  return null;
+};
+
+/**
+ * 获取用户信息
+ * @param {object} ctx HTTP请求上下文
+ * @returns {object|null} 用户信息
+ * @private
+ */
+Oauth.prototype._getUser = async function (ctx) {
+  var user = ctx.session?.user;
+  if (user) {
+    return user;
+  }
+  var token = ctx.headers[this.config.token_key];
+  if (!token) {
+    return null;
+  }
+  var cache = typeof this.config.get_cache === 'function' ? this.config.get_cache() : null;
+  if (!cache) {
+    return null;
+  }
+  var u = await cache.get(this.config.session_key + '_' + token);
+  if (!u) {
+    return null;
+  }
+  var user_info = this._extractUserFromCache(u);
+  if (user_info) {
+    ctx.session.user = user_info;
+  }
+  return user_info;
+};
+
+/**
+ * 从缓存中提取用户信息
+ * @param {object|string} u 缓存数据
+ * @returns {object|null} 用户信息
+ * @private
+ */
+Oauth.prototype._extractUserFromCache = function (u) {
+  var type = typeof (u);
+  if (type === 'string') {
+    var o = string.toJson(u);
+    return o.user;
+  } else if (type === 'object' && Object.keys(u).length > 0) {
+    return u.user;
+  }
+  return null;
+};
+
+/**
+ * 检查用户访问权限
+ * @param {object} user 用户信息
+ * @param {object} config 配置信息
+ * @returns {boolean} 是否无权限
+ * @private
+ */
+Oauth.prototype._checkAccess = function (user, config) {
+  return this._checkAccessLevels(user, config) ||
+    this._checkUserGroups(user, config) ||
+    this._checkAdminGroups(user, config);
+};
+
+/**
+ * 检查用户级别权限
+ * @param {object} user 用户信息
+ * @param {object} config 配置信息
+ * @returns {boolean} 是否无权限
+ * @private
+ */
+Oauth.prototype._checkAccessLevels = function (user, config) {
+  return (config.gm !== 0 && user.gm < config.gm) ||
+    (config.vip !== 0 && user.vip < config.vip) ||
+    (config.mc !== 0 && user.mc < config.mc);
+};
+
+/**
+ * 检查用户组权限
+ * @param {object} user 用户信息
+ * @param {object} config 配置信息
+ * @returns {boolean} 是否无权限
+ * @private
+ */
+Oauth.prototype._checkUserGroups = function (user, config) {
+  if (config.user_group.length === 0) {
+    return false;
+  }
+  var user_groups = user.user_group.split(',');
+  var has_group = config.user_group.some(group => user_groups.includes(group));
+  return !has_group;
+};
+
+/**
+ * 检查管理组权限
+ * @param {object} user 用户信息
+ * @param {object} config 配置信息
+ * @returns {boolean} 是否无权限
+ * @private
+ */
+Oauth.prototype._checkAdminGroups = function (user, config) {
+  if (config.user_admin.length === 0) {
+    return false;
+  }
+  var admin_groups = user.user_admin.split(',');
+  var has_admin = config.user_admin.some(group => admin_groups.includes(group));
+  return !has_admin;
+};
+
+module.exports = Oauth;

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "mm_api",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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"
+  }
+}

package/script.tpl.js

@@ -0,0 +1,32 @@
+
+module.exports = {
+  /**
+   * 接口主函数
+   * @param {object} ctx HTTP上下文
+   * @param {object} db 数据管理器,如: { next: async function{}, ret: {} }
+   * @returns {object} 执行结果
+   */
+  async main(ctx, options) {
+    // 获取请求参数
+    var req = ctx.request;
+    var {
+      query,
+      body
+    } = req;
+    // return "hello world" + JSON.stringify(body);
+
+    // 操作sql模板
+    var m = query.method;
+    if (m === 'add') {
+
+    } else if (m === 'del') {
+
+    } else if (m === 'set') {
+
+    } else {
+
+    }
+    var ret = await this.sql.run(query, body, db);
+    return ret;
+  }
+};

package/test.js

@@ -0,0 +1,18 @@
+'use strict';
+const assert = require('assert');
+const mod = require('./index.js');
+
+// 验证导出结构
+assert.ok(mod.Manager, '应导出 Manager');
+assert.ok(mod.admin, '应导出 admin');
+assert.strictEqual(typeof mod.apiAdmin, 'function', '应导出 apiAdmin 函数');
+
+// 验证通过工厂函数获取实例
+const inst = mod.apiAdmin('test');
+assert.ok(inst instanceof mod.Manager, 'apiAdmin 返回的实例应为 Manager 类型');
+
+// 验证通过 admin 获取实例
+const inst2 = mod.admin.get('test2');
+assert.ok(inst2 instanceof mod.Manager, 'admin.get 返回的实例应为 Manager 类型');
+
+console.log('mm_api 模块测试通过');