cmd-cloud-router

基于洋葱圈模型的云函数路由库，编写类 RESTful 资源路由

介绍

简易 koa 洋葱圈模型执行，koa-router 路由风格编写云函数。

• 每个云函数是一个独立进程，使用路由分为多部分
• 使用 path-to-regexp 函数库解析路由参数 /user/:str/:foo
• 函数需要使用 nodejs12 版本以上, 中间件使用 Promise 函数。

函数-API

应用对象（Application）

Application 是请求级别的全局应用对象，监听云函数执行。基于洋葱圈模型，请求从第一个中间件开始并按其方式顺序运行。

| 函数 | 名称 | 说明 | | :------- | :----------- | :--------------------------------- | | use | 注册使用中间件 | 使用给定中间件加入程序执行过程 | | listen | 监听程序请求 | 将云函数请求数据加入到应用程序对象 |

客户端调用云函数时传入的参数数据

| 参数 | 说明 | | :------- | :------------------------------------ | | url | 必传参数，请求已定义的路由路径 | | method | 可选参数，路由路径指定的请求方法，默认GET方法 | | data | 可选参数，传入可能需要的参数数据 |

使用示例：

const { Application } = require("cmd-cloud-router");
const app = new Application();

// 使用中间件，请使用异步函数保证执行顺序
app.use(async (ctx, next) => {
    console.time("计时");

    let sum = 0;
    for (let i = 0; i < 99; i++) {
        for (let j = 0; j < i; j++) {
            sum += j;
        }
    }

    await next();

    // 响应结果要用 ctx.body
    ctx.body = `求和：${sum}`;

    console.timeEnd("计时");
});


// 客户端调用云函数时传入的参数
const event = {
    url: "/add",
    method: "post",
    data: {
        value: 99
    },
};

// 客户端调用云函数时的系统运行环境参数
const context = {
    text: "云函数请求环境",
    SOURCE: "云函数调用来源",
};

// 传入全局配置
const config = {
  name: "测试配置",
  value: "1.0.0",
};

// 对请求参数监听 返回Promise对象
app.listen(event, context, config).then(res => {
    console.log("响应ctx.body的结果：", res);
})
.catch(err => {
    console.log("错误结果：", err);
});

上下文 Context

Context 是请求级别的对象，封装了请求的信息，对每一次请求都会重新初始上下文参数属性。

请求上下文对象信息：

| 取值 | 说明 | 类型 | | :------- | :----------- | :--------------------------------- | | event | 客户端调用云函数时传入的参数 | object | | app | 客户端调用云函数时的系统运行环境参数 | object | | url | 请求资源 | string | | method | 请求方法 | string | | data | 请求参数 | object | | path | url路径 | string | | querystring | url查询字符串 | string | | query | url查询参数 | object | | params | url路由参数 | object | | body | 程序执行后通过该属性返回结果，函数内 return 是没有效果的 | object | | config | 可选的传入全局配置参数 | object | | * | 可选的中间件进行属性参数传递 | 任意值 |

中间件 Middleware

Middleware 是请求级别的函数，在程序执行过程前或后加入处理逻辑，实现程序拦截过滤等功能。

module.exports = async (ctx, next) => {
  console.time("logger");
  // 定义属性参数
  ctx.logger = "日志中间件";
  // 中间件放行
  await next();
  console.timeEnd("logger");
};

1. 如果没有触发next()函数，会终止程序并返回上下文 body 属性的结果。
2. 确保执行结果符合洋葱模型，请使用 Promise 对象的函数。
3. 上下文可以定义属性参数，数据生命周期只存在当前请求。

路由对象（Router）

Router 路由命名 URL 路由规则风格，支持 http 方法声明路由，可以只针对单个路由使用中间件，处理每一次请求。

| 函数 | 名称 | 说明 | | :--------- | :----------- | :------------------------- | | prefix | 路由前缀 | 统一定义路由前缀 | | register | 注册路由 | 创建并注册路由路径 | | get | GET路由请求 | 注册指定的get请求方法路由路径 | | post | POST路由请求 | 注册指定的post请求方法路由路径 | | put | PUT路由请求 | 注册指定的put请求方法路由路径 | | delete | DELETE路由请求 | 注册指定的delete请求方法路由路径 | | routes | 路由表中间件函数 | 添加到应用对象中，执行请求匹配的路由函数 |

云函数调用来源为 timing 定时触发器会将 cron 表达式转换为 PUT 方法路由（hex 编码化）
转换例如 cron:0 0 * * * * => 63726f6e3a302030202a202a202a202a

使用示例：

const { Router } = require("cmd-cloud-router");
const router = new Router();

// 使用指定方法路由
// router.["get" | "post" | "put" | "delete"](<URL路径>, <函数>, <其他参数>);

router.post(
  "/index",
  async ctx => {
    ctx.body = "成功";
  }, {
    middleware:  [
      async (ctx, next) => {
        await next();
      },
    ]
  }
);

// 使用自定义方法路由
// router.register(<请求方法>, <URL路径>, <函数>, <其他参数>);

router.register(
  "post",
  "/index",
  async ctx => {
    ctx.body = "成功";
  }, {
    middleware:  [
      async (ctx, next) => {
        await next();
      },
    ]
  }
);

// 云函数调用来源为 timing 定时cron表达式转换路由 hex编码化
const cronPath = Buffer.from("cron:0 0 * * * *", "utf-8").toString("hex");
router.put(cronPath, async ctx => {
  console.log("执行 ==> %s - %s <==", ctx.method, ctx.path);
  // 定时任务没有需要响应的 ctx.body
});

// 注册到应用对象中间件中使用
// app.user(router.routes());

注解-API

• 路由控制器：Controller
• 路由方法：RequestMapping, Get, Post, Put, Del

将控制器声明的Class类文件进行扫描加入路由：ScanController

声明注解需要在编译环境下支持，已在使用 vite + ts 方式进行打包部署测试。

鸣谢

• 参考 koa
• 参考 koa-router
• 参考 koa-compose
• 使用 uniCloud 云函数