mm_api 0.0.0-stage → 1.1.1

package/README.md

@@ -1,3 +1,3 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## API框架
+用于实现web api和mvc模式路由请求
+负责配置路由路径、访问权限、校验机制

package/com.json

@@ -0,0 +1,5 @@
+{
+    "name": "Api",
+    "title": "API管理器",
+    "state": 1
+}

package/config.tpl.json

@@ -0,0 +1,41 @@
+{
+	// 路由路径
+	"path": "{path || '/'}",
+	// 名称, 用于动态增删改API配置
+	"name": "{name || 'api'}",
+	// 标题, 用于开发文档显示
+	"title": "{title || '示例接口'}",
+	// 描述, 用于介绍该路由的作用
+	"description": "{description || '描述接口使用方法'}",
+	// 函数文件, 用于驱动脚本, 实现业务 
+	"main": "{main || './index.js'}",
+	// 请求方法, 选填 GET, POST, ALL。 ALL指同时支持GET/POST
+	"method": "ALL",
+	// 开放域, 如果域未开放, 则只有特定的协议头才能访问该API, 同时API文档不接见
+	"scope": true,
+	// 是否启用
+	"state": 1,
+	// 缓存时长, 单位: 分钟。使用缓存后, 二次访问API直接从缓存读取, 不重复执行业务脚本
+	"cache": 0,
+	// 是否客户端缓存, 使用客户端则不再访问服务器, 直接从浏览器中拿; 使用服务端缓存则会访问服务器   
+	"client_cache": false,
+	// SQL配置路径, 用于将请求参数拼接成SQL, 实现比较复杂的查询
+	"sql_path": "./sql.json",
+	// 参数配置路径, 用于校验API请求参数是否正确, 同时显示在API文档中 
+	"param_path": "./param.json",
+	/* 授权协议 */
+	"oauth": {
+		// 是否需要登录, true表示需要登录才能访问该接口
+		"sign_in": false,
+		// 会员权限级别, 如果小于该值, 则无法访问, 0为不限制
+		"vip": 0,
+		// 管理员权限级别, 如果小于该值, 则无法访问, 0为不限制
+		"gm": 0,
+		// 商户/第三方权限级别, 如果小于该值, 则无法访问, 0为不限制
+		"mc": 0,
+		// 用户组, 允许访问该接口的普通用户群体, 传ID数组，例如: [1,5]
+		"user_group": [],
+		// 管理组, 允许访问该接口的管理员群体, 传ID数组，例如: [1,5]
+		"user_admin": []
+	}
+}

package/examples/README.md

@@ -0,0 +1,39 @@
+# mm_api 使用实例
+
+本目录演示 mm_api 的常见用法，所有示例可直接运行（需要已安装 `mm_sql`、`mm_sqlite` 等依赖）。
+
+## 示例列表
+
+| 示例 | 说明 | 运行命令 |
+| --- | --- | --- |
+| [basic.js](./basic.js) | 创建 API 管理器、注册接口并执行请求 | `node examples/basic.js` |
+| [param_api/](./param_api/) | 带参数校验的接口（mm_param） | `node examples/param_api/run.js` |
+| [sql_api/](./sql_api/) | 脚本内直接使用 mm_sql 操作 SQLite 数据库 | `node examples/sql_api/run.js` |
+
+## 目录结构
+
+```
+examples/
+├── helper.js          # 构造模拟 HTTP 请求上下文的辅助函数
+├── basic.js           # 基础用法示例（加载 hello_api）
+├── hello_api/         # 最简单的接口：api.json（路由配置）+ index.js（业务脚本）
+├── param_api/         # 参数校验示例：api.json + param.json + index.js + run.js
+└── sql_api/           # SQL 示例：api.json + index.js（脚本内直接使用 mm_sql）+ run.js
+```
+
+## 接口配置约定
+
+每个接口子目录由两部分组成：
+
+- `api.json`：路由配置（路径、请求方法、启用状态、参数/脚本路径等）
+- `index.js`：业务脚本，导出 `async main(params, ctx, options)` 主函数
+
+注册接口时通过 `api.add({ ...require('./xxx_api/api.json'), dir: __dirname, main: './index.js' })`
+补充脚本目录与入口，使路由驱动能定位到业务脚本。
+
+## 请求上下文说明
+
+`mm_api` 的 `run(params, ctx, options)` 接收两个参数：
+
+- `ctx`：HTTP 请求上下文，包含 `request`（路径、方法、参数、请求头）、`response`、`session` 等
+- `options`：数据管理器，`ret` 字段用于保存接口执行结果

package/examples/basic.js

@@ -0,0 +1,37 @@
+'use strict';
+
+/**
+ * mm_api 基础使用示例
+ * 演示：创建 API 管理器、注册路由接口、执行请求
+ * 运行：node examples/basic.js
+ */
+const path = require('path');
+const { apiAdmin } = require('mm_api');
+const { makeCtx } = require('./helper.js');
+
+/**
+ * 主流程
+ * @returns {Promise<void>}
+ */
+async function main() {
+  // 1. 创建 API 管理器（指定作用域 demo，不同作用域实例相互隔离）
+  const api = apiAdmin('demo', { title: '示例 API' });
+
+  // 2. 注册接口：配置来自 api.json，补充脚本目录与入口
+  api.add({
+    ...require('./hello_api/api.json'),
+    dir: path.join(__dirname, 'hello_api'),
+    main: './index.js'
+  });
+
+  // 3. 构造请求上下文并执行路由
+  const ctx = makeCtx('/hello', 'GET', { name: '张三' });
+  const options = { ret: null };
+  const ret = await api.run(params, ctx, options);
+  console.log('接口返回:', ret);
+}
+
+main().catch((err) => {
+  console.error('执行失败:', err);
+  process.exit(1);
+});

package/examples/hello_api/api.json

@@ -0,0 +1,18 @@
+{
+  "name": "hello",
+  "title": "问候接口",
+  "description": "演示最简单的接口",
+  "path": "/hello",
+  "method": "ALL",
+  "state": 1,
+  "cache": 0,
+  "client_cache": false,
+  "oauth": {
+    "sign_in": false,
+    "vip": 0,
+    "gm": 0,
+    "mc": 0,
+    "user_group": [],
+    "user_admin": []
+  }
+}

package/examples/hello_api/index.js

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

package/examples/helper.js

@@ -0,0 +1,28 @@
+'use strict';
+
+/**
+ * 构造模拟 HTTP 请求上下文
+ * @param {string} path 请求路径
+ * @param {string} method 请求方法
+ * @param {object} query URL 参数
+ * @returns {object} 请求上下文
+ */
+function makeCtx(path, method, query) {
+  const req = {
+    path,
+    method: method || 'GET',
+    query: query || {},
+    body: {},
+    headers: {},
+    type: 'json',
+    url: path
+  };
+  return {
+    request: req,
+    response: { type: '' },
+    session: {},
+    headers: req.headers
+  };
+}
+
+module.exports = { makeCtx };

package/examples/param_api/api.json

@@ -0,0 +1,17 @@
+{
+  "name": "param",
+  "title": "参数校验接口",
+  "description": "演示带参数校验的接口",
+  "path": "/param",
+  "method": "ALL",
+  "state": 1,
+  "param_path": "./param.json",
+  "oauth": {
+    "sign_in": false,
+    "vip": 0,
+    "gm": 0,
+    "mc": 0,
+    "user_group": [],
+    "user_admin": []
+  }
+}

package/examples/param_api/index.js

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

package/examples/param_api/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/examples/param_api/run.js

@@ -0,0 +1,38 @@
+'use strict';
+
+/**
+ * mm_api 参数校验示例
+ * 演示：缺少必填参数时返回错误，参数正确时正常执行
+ * 运行：node examples/param_api/run.js
+ */
+const path = require('path');
+const { apiAdmin } = require('mm_api');
+const { makeCtx } = require('../helper.js');
+
+/**
+ * 主流程
+ * @returns {Promise<void>}
+ */
+async function main() {
+  const api = apiAdmin('param_demo', { title: '参数校验示例' });
+  api.add({
+    ...require('./api.json'),
+    dir: path.join(__dirname),
+    main: './index.js'
+  });
+
+  // 1. 缺少必填参数 name，应返回参数错误
+  const ctx_bad = makeCtx('/param', 'GET', {});
+  const ret_bad = await api.run(ctx_bad, { ret: null });
+  console.log('缺少参数时返回:', ret_bad);
+
+  // 2. 参数正确
+  const ctx_ok = makeCtx('/param', 'GET', { name: '张三' });
+  const ret_ok = await api.run(ctx_ok, { ret: null });
+  console.log('参数正确时返回:', ret_ok);
+}
+
+main().catch((err) => {
+  console.error('执行失败:', err);
+  process.exit(1);
+});

package/examples/sql_api/api.json

@@ -0,0 +1,16 @@
+{
+  "name": "sql",
+  "title": "SQL 接口",
+  "description": "演示脚本内直接使用 mm_sql 操作数据库",
+  "path": "/sql",
+  "method": "ALL",
+  "state": 1,
+  "oauth": {
+    "sign_in": false,
+    "vip": 0,
+    "gm": 0,
+    "mc": 0,
+    "user_group": [],
+    "user_admin": []
+  }
+}

package/examples/sql_api/index.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { Sql } = require('mm_sql');
+
+/**
+ * 创建 SQLite 实例并建表
+ * @returns {Promise<object>} Sql 实例
+ */
+async function createSql() {
+  const db_dir = path.join(__dirname, '.db');
+  fs.mkdirSync(db_dir, { recursive: true });
+  const sql = new Sql({
+    way: 'sqlite',
+    sqlite: { dir: db_dir, database: 'example_api' }
+  });
+  await sql.exec(
+    'CREATE TABLE IF NOT EXISTS t_user (id INTEGER PRIMARY KEY, name TEXT)'
+  );
+  return sql;
+}
+
+module.exports = {
+  /**
+   * 接口主函数：演示脚本内直接使用 mm_sql
+   * @param {object} ctx HTTP上下文
+   * @param {object} options 数据管理器
+   * @returns {object} 执行结果
+   */
+  async main(params, ctx, options) {
+    const { query } = ctx.request;
+    const sql = await createSql();
+    try {
+      if (query.method === 'add') {
+        await sql.exec('INSERT INTO t_user (name) VALUES (?)', [query.name || '']);
+        return { code: 0, message: '添加成功' };
+      }
+      // 查询前重置数据，保证示例结果可重复
+      await sql.exec('DELETE FROM t_user');
+      await sql.exec('INSERT INTO t_user (name) VALUES (?)', ['张三']);
+      await sql.exec('INSERT INTO t_user (name) VALUES (?)', ['李四']);
+      const list = await sql.run('SELECT * FROM t_user');
+      return { code: 0, message: '成功', data: list };
+    } finally {
+      await sql.close();
+    }
+  }
+};

package/examples/sql_api/run.js

@@ -0,0 +1,33 @@
+'use strict';
+
+/**
+ * mm_api SQL 使用示例
+ * 演示：接口脚本内直接使用 mm_sql 操作 SQLite 数据库
+ * 运行：node examples/sql_api/run.js
+ */
+const path = require('path');
+const { apiAdmin } = require('mm_api');
+const { makeCtx } = require('../helper.js');
+
+/**
+ * 主流程
+ * @returns {Promise<void>}
+ */
+async function main() {
+  const api = apiAdmin('sql_demo', { title: 'SQL 接口示例' });
+  api.add({
+    ...require('./api.json'),
+    dir: path.join(__dirname),
+    main: './index.js'
+  });
+
+  // 查询数据
+  const ctx = makeCtx('/sql', 'GET', {});
+  const ret = await api.run(ctx, { ret: null });
+  console.log('查询结果:', ret);
+}
+
+main().catch((err) => {
+  console.error('执行失败:', err);
+  process.exit(1);
+});

package/index.js

@@ -0,0 +1,21 @@
+const Manager = require('./lib/manager');
+const Admin = require('mm_corejs').Admin;
+
+/**
+ * API管理器实例（Admin 工厂）
+ * 支持 os.js 调用：require('mm_api').admin.setServer(os) -> admin.get('os', config)
+ */
+let admin = new Admin();
+admin.setClass(Manager);
+
+module.exports = {
+  Api: require('./lib/api'),
+  Manager,
+  admin,
+  apiAdmin(scope, config) {
+    if (!scope) {
+      scope = 'os';
+    }
+    return admin.get(scope, config);
+  }
+};