mm_api 0.0.0-stage → 1.1.1

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 };

package/tests/index.test.js

@@ -0,0 +1,45 @@
+'use strict';
+
+/**
+ * index.js 导出与工厂函数测试
+ * @description 覆盖模块入口的全部导出与 apiAdmin / admin 分支
+ */
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const mod = require('../index.js');
+
+test('导出结构', () => {
+  assert.ok(mod.Manager, '应导出 Manager');
+  assert.ok(mod.admin, '应导出 admin');
+  assert.strictEqual(typeof mod.apiAdmin, 'function', '应导出 apiAdmin 函数');
+});
+
+test('apiAdmin 无参时使用 os 作用域', () => {
+  const inst = mod.apiAdmin();
+  assert.ok(inst instanceof mod.Manager, '应返回 Manager 实例');
+  assert.strictEqual(inst.config.name, 'os');
+});
+
+test('apiAdmin 指定作用域创建实例', () => {
+  const inst = mod.apiAdmin('test_scope');
+  assert.ok(inst instanceof mod.Manager, '应返回 Manager 实例');
+  assert.strictEqual(inst.config.name, 'test_scope');
+});
+
+test('apiAdmin 同作用域返回缓存实例', () => {
+  const first = mod.apiAdmin('cached_scope');
+  assert.strictEqual(mod.apiAdmin('cached_scope'), first, '同作用域应返回同一实例');
+});
+
+test('apiAdmin 传入配置可覆盖标题', () => {
+  const inst = mod.apiAdmin('title_scope', { title: '自定义标题' });
+  assert.strictEqual(inst.config.name, 'title_scope');
+  assert.strictEqual(inst.config.title, '自定义标题');
+});
+
+test('admin.get 返回 Manager 实例', () => {
+  const inst = mod.admin.get('admin_scope');
+  assert.ok(inst instanceof mod.Manager, 'admin.get 应返回 Manager 实例');
+  assert.strictEqual(inst.config.name, 'admin_scope');
+});

package/tests/manager.test.js

@@ -0,0 +1,184 @@
+'use strict';
+
+/**
+ * ApiManager 管理器测试
+ * @description 覆盖接口驱动的注册、注销、路径匹配、排序与路由执行
+ */
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { Manager, apiAdmin } = require('../index.js');
+const { makeCtx, makeOptions } = require('./helper.js');
+
+test('add 注册接口驱动', () => {
+  const mgr = apiAdmin('mgr_add');
+  const drive = mgr.add({
+    name: 'hello',
+    path: '/hello',
+    method: 'ALL',
+    dir: __dirname,
+    main: './fixtures/hello.js'
+  });
+  assert.ok(drive, 'add 应返回驱动实例');
+  assert.ok(mgr.has('hello'), '注册后应能查到驱动');
+  assert.strictEqual(mgr.size(), 1);
+});
+
+test('get 获取接口驱动', () => {
+  const mgr = apiAdmin('mgr_get');
+  mgr.add({
+    name: 'hello',
+    path: '/hello',
+    method: 'ALL',
+    dir: __dirname,
+    main: './fixtures/hello.js'
+  });
+  const drive = mgr.get('hello');
+  assert.ok(drive, 'get 应返回驱动实例');
+  assert.strictEqual(drive.config.name, 'hello');
+  assert.strictEqual(drive.config.path, '/hello');
+});
+
+test('del 注销接口驱动', async () => {
+  const mgr = apiAdmin('mgr_del');
+  mgr.add({
+    name: 'hello',
+    path: '/hello',
+    method: 'ALL',
+    dir: __dirname,
+    main: './fixtures/hello.js'
+  });
+  const bl = await mgr.del('hello');
+  assert.strictEqual(bl, true, 'del 应返回 true');
+  assert.strictEqual(mgr.has('hello'), false, '注销后驱动应不存在');
+});
+
+test('isMatch 路径匹配', () => {
+  const mgr = new Manager({ name: 'isMatch' });
+  // 精确匹配
+  assert.strictEqual(mgr.isMatch('/hello', '/hello'), true);
+  // 尾通配：/api/* 匹配 /api/hello
+  assert.strictEqual(mgr.isMatch('/api/hello', '/api/*'), true);
+  // 头通配：*hello 匹配 /hello
+  assert.strictEqual(mgr.isMatch('/hello', '*hello'), true);
+  // 头尾通配：*hello* 包含匹配
+  assert.strictEqual(mgr.isMatch('/api/hello', '*hello*'), true);
+  // 不匹配
+  assert.strictEqual(mgr.isMatch('/other', '/hello'), false);
+});
+
+test('_sortedDrives 按路径长度降序排序', () => {
+  const mgr = apiAdmin('mgr_sort');
+  mgr.add({
+    name: 'short',
+    path: '/a',
+    method: 'ALL',
+    state: 1,
+    sort: 1,
+    dir: __dirname,
+    main: './fixtures/hello.js'
+  });
+  mgr.add({
+    name: 'long',
+    path: '/a/b',
+    method: 'ALL',
+    state: 1,
+    sort: 1,
+    dir: __dirname,
+    main: './fixtures/hello.js'
+  });
+  const drives = mgr._sortedDrives();
+  assert.strictEqual(drives[0].config.name, 'long', '路径长的应优先');
+  assert.strictEqual(drives[1].config.name, 'short');
+});
+
+test('_sortedDrives 过滤未启用驱动', () => {
+  const mgr = apiAdmin('mgr_state');
+  mgr.add({
+    name: 'disabled',
+    path: '/a',
+    method: 'ALL',
+    state: 0,
+    dir: __dirname,
+    main: './fixtures/hello.js'
+  });
+  mgr.add({
+    name: 'enabled',
+    path: '/b',
+    method: 'ALL',
+    state: 1,
+    dir: __dirname,
+    main: './fixtures/hello.js'
+  });
+  const drives = mgr._sortedDrives();
+  assert.strictEqual(drives.length, 1);
+  assert.strictEqual(drives[0].config.name, 'enabled');
+});
+
+test('run 匹配路由并返回脚本结果', async () => {
+  const mgr = apiAdmin('mgr_run');
+  mgr.add({
+    name: 'hello',
+    path: '/hello',
+    method: 'ALL',
+    dir: __dirname,
+    main: './fixtures/hello.js'
+  });
+  const ctx = makeCtx({ path: '/hello', method: 'GET' });
+  const options = makeOptions();
+  const ret = await mgr.run(ctx, options);
+  assert.ok(ret, 'run 应返回结果');
+  assert.deepStrictEqual(JSON.parse(ret), {
+    code: 0,
+    message: '成功',
+    data: { hello: 'world' }
+  });
+  assert.strictEqual(options.ret, ret, '结果应写入数据管理器 ret');
+});
+
+test('run 方法不匹配时返回 null', async () => {
+  const mgr = apiAdmin('mgr_method');
+  mgr.add({
+    name: 'hello',
+    path: '/hello',
+    method: 'POST',
+    dir: __dirname,
+    main: './fixtures/hello.js'
+  });
+  const ctx = makeCtx({ path: '/hello', method: 'GET' });
+  const ret = await mgr.run(ctx, makeOptions());
+  assert.strictEqual(ret, null);
+});
+
+test('run 路径不匹配时返回 null', async () => {
+  const mgr = apiAdmin('mgr_path');
+  mgr.add({
+    name: 'hello',
+    path: '/hello',
+    method: 'ALL',
+    dir: __dirname,
+    main: './fixtures/hello.js'
+  });
+  const ctx = makeCtx({ path: '/other', method: 'GET' });
+  const ret = await mgr.run(ctx, makeOptions());
+  assert.strictEqual(ret, null);
+});
+
+test('reload 重启接口驱动', async () => {
+  const mgr = apiAdmin('mgr_reload');
+  mgr.add({
+    name: 'hello',
+    path: '/hello',
+    method: 'ALL',
+    dir: __dirname,
+    main: './fixtures/hello.js'
+  });
+  const bl = await mgr.reload('hello');
+  assert.strictEqual(bl, true, 'reload 应返回 true');
+});
+
+test('reload 不存在的驱动返回 false', async () => {
+  const mgr = apiAdmin('mgr_reload_miss');
+  const bl = await mgr.reload('not_exist');
+  assert.strictEqual(bl, false);
+});

package/tests/oauth.test.js

@@ -0,0 +1,107 @@
+'use strict';
+
+/**
+ * Oauth 身份验证测试
+ * @description 覆盖免登录、登录校验与权限级别校验
+ */
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const Oauth = require('../lib/oauth.js');
+const { makeCtx } = require('./helper.js');
+
+test('无需登录时 check 返回 null', async () => {
+  const oauth = new Oauth({ sign_in: false });
+  const ctx = makeCtx({ path: '/hello', method: 'GET' });
+  const ret = await oauth.check(ctx);
+  assert.strictEqual(ret, null);
+});
+
+test('需登录但未登录时返回 60000', async () => {
+  const oauth = new Oauth({ sign_in: true });
+  const ctx = makeCtx({ path: '/hello', method: 'GET' });
+  const ret = await oauth.check(ctx);
+  assert.ok(ret, '应返回错误对象');
+  assert.strictEqual(ret.code, 60000);
+  assert.strictEqual(ret.message, '账户未登录!');
+});
+
+test('已登录且权限足够时返回 null', async () => {
+  const oauth = new Oauth({
+    sign_in: true,
+    vip: 1,
+    gm: 1,
+    mc: 1,
+    user_group: [],
+    user_admin: []
+  });
+  const ctx = makeCtx({ path: '/hello', method: 'GET' });
+  ctx.session.user = {
+    user_id: 1,
+    vip: 9,
+    gm: 9,
+    mc: 9,
+    user_group: '',
+    user_admin: ''
+  };
+  const ret = await oauth.check(ctx);
+  assert.strictEqual(ret, null, '权限足够时应通过');
+});
+
+test('权限不足返回 70000', async () => {
+  const oauth = new Oauth({
+    sign_in: true,
+    gm: 5
+  });
+  const ctx = makeCtx({ path: '/hello', method: 'GET' });
+  ctx.session.user = {
+    user_id: 1,
+    vip: 9,
+    gm: 1,
+    mc: 9,
+    user_group: '',
+    user_admin: ''
+  };
+  const ret = await oauth.check(ctx);
+  assert.ok(ret, '应返回错误对象');
+  assert.strictEqual(ret.code, 70000);
+  assert.strictEqual(ret.message, '没有访问权限');
+});
+
+test('用户组不匹配返回 70000', async () => {
+  const oauth = new Oauth({
+    sign_in: true,
+    user_group: ['1', '5']
+  });
+  const ctx = makeCtx({ path: '/hello', method: 'GET' });
+  ctx.session.user = {
+    user_id: 1,
+    vip: 9,
+    gm: 9,
+    mc: 9,
+    user_group: '2,3',
+    user_admin: ''
+  };
+  const ret = await oauth.check(ctx);
+  assert.ok(ret, '应返回错误对象');
+  assert.strictEqual(ret.code, 70000);
+});
+
+test('管理组不匹配返回 70000', async () => {
+  const oauth = new Oauth({
+    sign_in: true,
+    user_admin: ['1', '5']
+  });
+  const ctx = makeCtx({ path: '/hello', method: 'GET' });
+  ctx.session.user = {
+    user_id: 1,
+    vip: 9,
+    gm: 9,
+    mc: 9,
+    user_group: '',
+    user_admin: '2,3'
+  };
+  const ret = await oauth.check(ctx);
+  assert.ok(ret, '应返回错误对象');
+  assert.strictEqual(ret.code, 70000);
+});