cloudbase-access 开发笔记

发表于 分类于 本文字数： 7.8k 阅读时长 ≈ 7 分钟

cloudbase-access 源码：https://github.com/hal-wang/cloudbase-access
cloudbase-access npm：https://www.npmjs.com/package/@hal-wang/cloudbase-access

Serverless 的开发模式一直在演进，各个云服务商也有自己的产品，其中代表性的就是云函数，也就是使用 NodeJS 写的 API。云函数比较轻量，不需要服务器即可实现运算。我最喜欢的是腾讯云 CloudBase 中的云函数，虽然腾讯云也有独立的云函数，但与其他云服务商的云函数都差不多，没什么特点。

为什么选择 CloudBase

CloudBase 中的云函数与其他云函数写法相同，使用 HTTP 调用的用法也类似，但它相比于独立的云函数，有以下优点：

  1. 在 CloudBase 中有个数据库，根据用法猜测这个数据库是基于 MongoDB 的，但是用法又改了一些。这个数据库不需要单独购买，属于 CloudBase 环境中的一环，因此在云函数中调用十分方便。
  2. VSCode 插件成熟，在 VSCode 中写 CloudBase 云函数还是很惬意的。

当然我觉得 CloudBase 也有要改进的地方，其中一个最重要的，就是对象存储无法生成上传连接。也就是说，想用 CloudBase 的对象存储，必须遵循 CloudBase 的权限规则。但是，对于一个想自己管理用户的后台来说，这是不现实的。因此目前最好还是把文件放在独立的对象存储中吧，免得被绑死了。

云函数痛点

云函数是微服务框架，在各个云服务商的云函数文档中，对于云函数的介绍或者示例，都是一个云函数实现一个简单的功能。这样做是也是为了实现微服务体系，达到轻量级服务。但是各个云函数彼此解耦，在写函数时，一些通用方法必然要写多份，这就造成了代码复用率很低，可能同样的代码要出现在几个云函数中。

当然也有对此的解决方案：

  1. 写单独通用云函数，通过云函数调用方式。这种方式会造成云函数调用频率过高，而且效率无法保证，也不能享受到代码智能提示。最重要的，还是太麻烦，写个新通用功能可能要折腾好几个步骤。

  2. 把通用功能打包发布至 npm，再在需要的云函数中 install。这种也十分麻烦，每次更改都需要 npm publish，各云函数需要 npm update。

因此解决方案只是妥协，并没有解决实质问题。

cloudbase-access 前身

苦于以上痛点，我想到了在一个云函数中实现多个功能，通过传入不同参数来分辨，这种不通用的方法，也算是临时解决了我的问题。

1
2
3
4
5
6
7
8
// https://***/api
{
  "path":"user/login",
  "data":{
    "account":"123",
    "password":"abcdef"
  }
}

但对代码有强迫症的我，看着这蹩脚的写法，越看越难受。后来偶然发现云函数调用的环境 event ，有个path字段，可以获取到访问路径，如调用 https://***/api/user/login，path 字段值为 /user/login，既然能获取到访问路径，就好办多了，开始重构！

初版 cloudbase-access

现有 API 已经使用了之前蹩脚的做法，重构的工程量稍大，因此就想着写个 npm 包，这也是我第一次尝试发布 npm 包。

把原来的 API 和路由有关的部分提出来，新写了个项目 cloudbase-access，目的是写出通用的 MVC API 框架。

做法

根据环境event中的path字段值，来访问位于controller中的action，这个 action 是个 js 文件，基本功能是在这个文件中实现。这种做法其实是参考了 asp.net mvc 的思想。

传参

重构之后，前面的传参就改成了下面这种：

1
2
3
4
5
// https://***/api/user/login
{
  "account":"123",
  "password":"abcdef"
}

现在就简单通用多了。

改用 ts

NodeJS 写 API 有一个很严重的问题，就是弱类型语言很容易带来错误，比如以下典型错误：

1
1 + "0" = "10"

在强类型语言种，我可以明确知道变量类型，但是在弱类型语言中，为了保证数据类型的正确性就得手动验证变量类型，必须验证接口参数的数据类型，因为你不知道是谁调用了这个接口。虽然手动验证也可以，但工作量太大，也容易出错。

目前对于 JS 类型检查，主要是Flow和TS，但 TS 目前以压倒性优势胜出。此外，作为 npm 包，应该使用 ts 来写，这样其他 ts 也好调用。

在2020.10.29改用了 TS，初次转 TS 只是把原先的功能使用 TS 实现，并没有更改逻辑和结构。

这次改 TS 的过程，也让我发现了一些现有的很多不足：

  1. 返回值封装不完善
  2. 路由功能简单，扩展性弱
  3. 权限验证功能简单，扩展性弱
  4. action 没有封装，写法容易出错
  5. 没有单元测试
  6. 没有 Demo

后续改进，一个一个解决。

返回值

云函数返回的 HTTP 网关，必须符合特定格式，因此在 cloudbase-access 中封装了返回结构。

此前使用 JS，没有过多的封装，返回值也只是个 JSON 对象，有一些内置函数，可以生成返回的对象，但是使用起来总是不方便：需要先加引用再使用，而且没有智能提示。

以前的 JS 返回结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// base.js
module.exports = function (statusCode, body, headers) {
  return {
    isBase64: false,
    statusCode: statusCode,
    headers: Object.assign(
      {
        'Content-Type': 'application/json',
        'Access-Control-Allow-Origin': '*'
      },
      headers || {}
    ),
    body: body
  }
}
1
2
3
4
5
6
// ok.js
const base = require('./base')

module.exports = function (body, headers) {
  return base(200, body, headers)
}

改用 ts 后封装了返回值 HttpResult，该类有个 get 属性 result，可以获得最终结果，并且加了通用返回头部、返回结果验证等功能。

现在的 TS 返回结果：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
export default class HttpResult {
  constructor(
    public readonly statusCode: number,
    public readonly body?: unknown,
    public readonly headers?: Record<string, unknown>
  ) {}

  get result(): Record<string, unknown> {
    return <Record<string, unknown>>{
      isBase64: false,
      statusCode: this.statusCode,
      headers: Object.assign(HttpResult.baseHeaders, this.headers),
      body: this.body,
    };
  }

  get isSuccess(): boolean {
    return this.statusCode >= 200 && this.statusCode < 300;
  }

  static readonly baseHeaders = <Record<string, unknown>>{
    "Content-Type": "application/json",
    "Access-Control-Allow-Origin": "*",
    "nodejs-api": "cloudbase-access",
  };

  static base = function (
    statusCode: number,
    body?: unknown,
    headers?: Record<string, unknown>
  ): HttpResult {
    return new HttpResult(statusCode, body, headers);
  };
  static ok = function (body?: unknown): HttpResult {
    return new HttpResult(200, body);
  };
  // more
}

中间件

此前路由功能过于简单，只能通过路径调用对应 action，而且封装的也不够完善，只用了函数封装，没有使用类，扩展性也弱。

现在给路由加个新功能 中间件 ，这样能极大的提高路由功能。

中间件类别

中间件分为了几种，分别在云函数不同的生命周期调用。类别使用枚举声明：

1
2
3
4
5
6
7
export const enum MiddlewareType {
  BeforeStart = 1, // the action object is not inited
  BeforeAction, // exec before action doing, the action object is inited
  BeforeEnd, // exec after action doing
  BeforeSuccessEnd, // exec after action doing, if the result is succeeded
  BeforeErrEnd, // exec after action doing, if the result is error
}

基类

中间件有个基类，所有中间件都从此基类派生，并且实现 do 方法。

1
2
3
4
5
6
7
8
9
export default abstract class Middleware {
  constructor(public readonly type: MiddlewareType) {}

  /**will be set before doing */
  requestParams: RequestParams = RequestParams.empty;

  /** if success, return null */
  abstract async do(): Promise<HttpResult | null>;
}

权限验证

现在权限验证也转而使用中间件，定义个新类Authority并继承Middleware，实际使用中，权限验证需要继承此类。

1
2
3
4
5
6
7
8
export default abstract class Authority extends Middleware {
  constructor() {
    super(MiddlewareType.BeforeAction);
  }

  /**will be set before doing*/
  public roles: Array<string> = new Array<string>();
}

与其他中间件一样，需要实现 do 方法，比如权限验证不通过时，do 方法返回

1
return HttpResult.forbidden("登陆失败");

封装 Action

使用 JS 时，并没有对 Action 封装，只是约定 Action 文件返回一个特定的结构，但是约定容易出错，不如限制。

现在定义了个类Action，所有 action 都应从此类派生，并实现 do 方法，返回 HttpResult

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
export default abstract class Action {
  constructor(public readonly roles: Array<string> = new Array<string>()) {}

  protected readonly base = HttpResult.base;
  protected readonly ok = HttpResult.ok;
  protected readonly accepted = HttpResult.accepted;
  protected readonly noContent = HttpResult.noContent;
  protected readonly partialContent = HttpResult.partialContent;
  protected readonly badRequest = HttpResult.badRequest;
  protected readonly forbidden = HttpResult.forbidden;
  protected readonly notFound = HttpResult.notFound;
  protected readonly errRequest = HttpResult.errRequest;

  /** will be set before doing */
  requestParams: RequestParams = RequestParams.empty;
  /** will be set before doing */
  middlewares: Array<Middleware> = new Array<Middleware>();

  abstract async do(): Promise<HttpResult>;
}

构造函数传入的是身份验证规则，如

1
2
3
["login"]

["admin", "root"]

可在实现 Authority 时，在 do 函数中根据身份角色判断当前用户能否访问该 API。

在 Action 中，内置了一些 HttpResult 静态函数以方便调用

1
2
// 在 action do方法中
return this.noContent()

根据 Action 类，action 写法就不容易出错了。

单元测试

写单元测试是每个程序员必备的技能和习惯！

以前我也不喜欢写单元测试，总觉得没必要专门写代码测试，甚至有些单元测试还有重复代码。

但是尝试用了单元测试之后，嗯~ 真香！

每写个功能，就写一个或多个单元测试，不仅可以测试代码有没有问题，还能梳理一遍代码逻辑。

我认为最重要的一点，就是后续增改功能时，跑一边单元测试全绿，就不怕新的增改影响旧功能，能让代码维护起来更顺畅。

对比了 TS 主流单元测试框架 Mocha和Jest，虽然Mocha在 JS 中更流行，但Jest对 ts 更友好，因此选用了 Jest 作为 cloudbase-access 的单元测试框架。

比如测试路由能否正确访问到 loginAuth action，并且能够执行成功。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
test("router test login access", async function () {
  const router = new Router(
    {
      headers: {
        account: global.users[0].account,
        password: global.users[0].password,
      },
      path: "/actions/loginAuth",
    },
    new Auth(),
    "test"
  );

  const result = (await router.do()).result;
  expect(result.statusCode).toBe(200);
});

Demo

本想着如果别人用 cloudbase-access 只要参考单元测试即可，但我把现有代码迁移到 cloudbase-access 时，发现可能会有一些细节我没注意到，但是又阻挡别人使用，所以只有单元测试可能不够，就着手写个 Demo。

之前是单独项目，后面又整合至源码中了。

这个 Demo 也使用 TS 写的，模仿真实使用环境，是一个简单的 todo API。

cba-map

考虑到增加更多 RESTFul 的路由适配，如 get /user/:id 的方式，在此前是没有的，因为路由仅仅是简单的文件路径匹配。

生成 map

在 2020-12-25 着手改进路由匹配。于是加了个 cba-map 脚本，在 API 发布前，找到所有 Action 并生成文件地址的 map。

新写一个 MapCreater 类，用于找到所有 Action 并获取 map。

由于有些开发者可能在发布前不使用 cba-map 脚本，因此在调用 API 时，如果包括 cba-map.json 文件，就从文件中获取 map，否则将在运行阶段获取 map。

经过测试，使用 cba-map 匹配路由的方式速度更快。

改进路由匹配

在有了所有 Action 地址后，路由匹配就变得简单起来，为了适配 RESTFul，需要满足以下功能：

地址包含查询

如 get user/:userId/todo/:todoId 等访问路径，不但要正确匹配路由，还要得到对应的查询参数。

但在文件系统的命名中，是不允许有 : 存在的，因此在 cba 中使用 ^ 代替。

区分 httpMethod

由于云函数是允许任意方式访问的，并且操作与 httpMethod (get/post/put/patch/delete) 完全无关。

在创建 Action 文件时，以 httpMethod 命名，以此来区分 httpMethod 并匹配。

Demo 改进

在 2021-01-11 收到 cloudbase-framework 团队的优秀案例邀请，去看了一下其他优秀案例，都有 一键部署，并且都有一个完整的 demo 或成品。

看一下自己写的及其简陋的 demo，不好意思放上去，于是改进一下之前的简单 demo，写个包含前后端的 todo list 小网站 cba-todo。

在写 api 时，参考了 github api，尽力写个符合 RESTFul 规范的 API。

API 写差不多时，才开始写网站。网站是使用 Vue + ts 写的，只有两个页面，比较简单。

根据 cloudbase-framework 文档，编辑 cloudbaserc.json，完美支持一键部署，测试一键部署一切良好，感叹腾讯云 cloudbase 一键部署这一方面做的非常完善。

ipare

后改为更通用化、模块化的 ipare