# @tmsfe/tms-cloud-sdk

> [TOC]

Latest version **0.0.6** (published 2022-07-15) · ISC license · 0 weekly downloads

## Install

```sh
npm install @tmsfe/tms-cloud-sdk
pnpm add @tmsfe/tms-cloud-sdk
yarn add @tmsfe/tms-cloud-sdk
bun add @tmsfe/tms-cloud-sdk
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.6 |
| Published | 2022-07-15 |
| First published | 2022-03-23 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 6 |
| Unpacked size | 120.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | TMSWeb |
| Maintainers | addunt, asforoneday, webberlin, odilewang, tms_account, tmsgo, gaoneng1850, yueqi |

## Links

- npm: https://www.npmjs.com/package/@tmsfe/tms-cloud-sdk
- npm.io page: https://npm.io/package/@tmsfe/tms-cloud-sdk

## Dependencies (6)

- [qs](https://npm.io/package/qs.md) ^6.10.3
- [fs-extra](https://npm.io/package/fs-extra.md) ^10.0.1
- [puppeteer](https://npm.io/package/puppeteer.md) ^13.5.1
- [handlebars](https://npm.io/package/handlebars.md) ^4.7.7
- [tcb-router](https://npm.io/package/tcb-router.md) ^1.1.2
- [wx-server-sdk](https://npm.io/package/wx-server-sdk.md) latest

## Recent versions

- 0.0.6 (latest) — 2022-07-15
- 0.0.5 — 2022-04-18
- 0.0.4 — 2022-03-31
- 0.0.3 — 2022-03-23
- 0.0.2 — 2022-03-23

## README

# @tmsfe/tms-cloud-sdk

[TOC]

---

## Thoughts
云开发提供了完整的一套服务端能力，可以让我们快速开发服务端业务逻辑而不用关注运维部署的细节。在过往的项目中，已经有一些典型的应用场景。

但是在云函数的开发和发布环节，还是有不少痛点，tms-cloud-sdk致力于解决云函数开发环节的痛点。部署环节的痛点另行方案解决，不在此讨论。

下面列举大家日常云开发联调过程中反馈的问题。我们围绕这些问题来封装公共能力。

---

### 重复且模板化的云函数框架初始代码

在每个云函数初始化时，都会存在类似的代码：

```javascript
const TcbRouter = require('tcb-router');
const cloud = require('wx-server-sdk');

cloud.init({ env: cloud.DYNAMIC_CURRENT_ENV });
const getWxContext = () => {
  const wxContext = cloud.getWXContext();

  return {
    openId: wxContext.OPENID,
    appId: wxContext.APPID,
    unionId: wxContext.UNIONID,
  };
};

// 云函数入口函数
exports.main = async (event) => {
  const app = new TcbRouter({ event });
  app.use(async (ctx, next) => {
    // 统一参数处理
    const { openId } = cloud.getWXContext()();
    const { event } = ctx._req; // eslint-disable-line
    Object.assign(ctx, { data: {
      openId,
      ...event,
    } });
    try {
      const resData = await next();
      Object.assign(ctx, { body: { errCode: 0, errMsg: 'success', resData } });
    } catch (e) {
      // 统一异常处理
      const { errCode, errMsg } = e;
      Object.assign(ctx, { body: { errCode, errMsg, resData: null } });
    }
  });

  app.router('xxx/xxx', () => {}); // 路由注册
  return app.serve();
};

```

分析这段代码，不同云函数之间有差异的只是路由注册的部分，参数预处理的中间件完全可以复用。

我们也有必要统一所有云函数的基础中间件，以实现日志打印的标准化；之前遇到部分云函数日志打印不全，需要排查时无从查起的尴尬场面；如果我们将日志打印标准化在基础中间件里，就可以避免此类问题。

---

### 海报图开发调试效率低下

很多时候我们需要绘制一张动态的还报图片，有很多云函数有写过这个逻辑，现在也有一个 ```canvasImg``` 的云函数来画图；其思路是在Node端用canvas画图，然后将canvas保存成图片。这种实现思路，开发联调的效率必然不高。

我们没有现成的可视化canvas画图工具，只能边改边发布云函数来调试，且此方案依赖的node-canvas包，在云函数环境无法正常安装，本地和云端需要兼容不同的node_modules依赖，见[云函数中特殊npm包的分层解决方案](https://iwiki.woa.com/pages/viewpage.action?pageId=1295596724)。

换个思路，如果我们不去画canvas，而是去写HTML页面，这样本地就可以快速完成复杂视觉的HTML开发，云函数要做的只是将这个HTML渲染，保存成图片即可。且云函数环境已默认集成 ```puppeteer``` 包，不存在依赖安装问题。

按照这个思路，我们在tms-cloud-sdk中封装了画图的公共方法，拿来即用。

---

### 生成小程序码还要依赖后端

云函数中可以免鉴权调用微信的开放接口，直接生成小程序码，在一些业务场景需要生成动态小程序码让用户分享，前端可自己完成。

我们在tms-cloud-sdk中封装了生成小程序码的接口，在微信开放能力的基础上做了扩展，支持上传到云存储或转base64，方便大家拿来即用。

---
### 内容安全检测不能拿来即用

云函数中可以免鉴权调用微信的内容安全检测接口，但接口需要传很多定制参数，需要了解上下文背景。我们对这个接口做了一层封装，使用时只需传要检测的内容即可。

---

## Documentation

### serve 云函数初始化

serve方法是tms-cloud-sdk提供的云函数入口高阶函数，业务只需传入路由表和自定义中间件即可。serve方法中封装了统一的参数预处理，包括对不同调用方(小程序端、定时任务、微信回调、HTTP访问)的入参标准化。

同时，serve方法统一增加了云函数出入参的日志打印中间件。

---

**参数**

**Object routes**

路由表，Object类型，key为路由路径，value为处理函数


**Array middleware**

自定义中间件，Array类型，每一项为独立中间件函数

---


**返回值**

**Function fn**

返回云函数入口函数，可以直接用于云函数初始化。

---

**示例代码**

```javascript
const tmsCloud = require('@tmsfe/tms-cloud-sdk');

const routes = {
  'testfn/testroute': (ctx) => console.log(ctx),
};

const middleware = [async (ctx, next) => {
  tmsCloud.logger.info(ctx);
  return await next();
}];

exports.main = tmsCloud.serve(routes, middleware);
```

---


### html2img 将HTML渲染为图片

顾名思义，将html渲染成图片，适用于动态生成海报图、分享图等业务场景。

此方法是对 ```puppeteer``` 的二次封装，拓展了对图片文件的处理，可以拿来即用。

---
> **性能优化提示:**
> 
> 云函数运行时环境内置了 ```puppeteer```, 我们的实现思路是用 ```puppeteer``` 在 ```headless``` 模式下打开要绘制的html页面,然后调用 ```screenshot``` 方法截图。
> 
> 在这个过程中，初始化 ```puppeteer``` 实例需要时间，加载html页面需要时间，截图也需要时间，尤其是加载html页面，这个过程的耗时取决于html中加载的资源体量。如果在页面中使用了大量网络资源(图片、css)等时，加载耗时会明显增加。
> 
> 因此建议在html中严格控制使用的网络资源，尽可能用 ```base64``` 的方式嵌入在html中。
> 

在绘制图片时，难免会用到一些特殊字体，我们已经将常用的字体以css文件的形式存放在cdn上，在html中可以直接用link标签引用。
如有其他字体包定制需求，请参照下面的base64字体css文件，或联系petegao协助处理。
```html
<!--腾讯体W3-->
<link rel="stylesheet" href="https://static.img.tai.qq.com/web/fonts/TencentSans-W3.css">
<!--腾讯体W7-->
<link rel="stylesheet" href="https://static.img.tai.qq.com/web/fonts/TencentSans-W3.css">
<!--苹果平方标准体-->
<link rel="stylesheet" href="https://static.img.tai.qq.com/web/fonts/PingFang-Normal.css">
<!--DIN-Alternate-->
<link rel="stylesheet" href="https://static.img.tai.qq.com/web/fonts/DIN-Alternate.css">
```


---


**参数**

**Object options**

绘图配置

| 属性         | 类型   | 默认值   | 必填 | 说明 |
| ----------- | -------|-----    |-----|  ----   |
| output      | string |         |否 |生成图片的云函数本地路径，只需指定目录路径，文件名自动生成;为空时不保存本地文件|
| cloudOutput  | string |    |否 |生成图片的云存储路径，只需指定云存储目录路径，文件名自动生成;为空时不存储|
| html  | string |    |是|要渲染的html内容，支持本地html文件路径、云存储fileID、网络https文件路径、或直接传html字符串|
| content  | string |    |否|handlebars模板内容，传入后将把html视为handlebars模板来渲染|
| transparent  | boolean | false |否|绘制的图片是否透明背景|
| encoding | string | binary | 否 |绘制图片的编码格式，支持 binary/base64, 默认为binary|
| selector | string |body |否|要绘制的元素，默认是body，可以通过css选择器标识要绘制的元素|
| type | string | png|否|生成图片的文件类型，jpeg/png，默认为png|


---


**返回值**

**Object rsp**


| 属性         | 类型    | 说明 |
| ----------- | -------|  ----   |
| localPath   | string |生成图片的云函数本地路径，入参传入output时有效|
| fileContent | binary/base64 |生成的图片内容，内容格式为binary/base64，取决于入参的encoding|
| encoding | string |与入参的encoding相同|
| fileID | string |云存储文件ID，当入参传cloudOutput时有效|
| tempFileURL | string |云存储文件http访问链接，当入参传cloudOutput时有效|


---

**示例代码**

```javascript
const tmsCloud = require('@tmsfe/tms-cloud-sdk');

const routes = {
  'testfn/drawimg': async () => {
    const html = `
      <!DOCTYPE html>
      <html>
      <head>
      <style>
      #myHeader {
        background-color: lightblue;
        color: black;
        padding: 40px;
        text-align: center;
      } 
      </style>
      </head>
      <body>

      <h2>{{title}}</h2>
      <p>{{desc}}</p>

      <h1 id="myHeader">My Header</h1>

      </body>
      </html>
    `;
    const { tempFileURL } = await tmsCloud.html2img({
      html,
      content: {
        title: 'Yehuda',
        desc: 'Katz',
      }
      cloudOutput: 'testfn/',
    });
    return { tempFileURL };
  },
};

exports.main = tmsCloud.serve(routes);
```

---


### callSinanServer 在云函数中调用SinanServer

在云函数中以L5的方式调用接入层SinanServer。

**注意调用此方法的云函数必须是由微信环境(小程序调用/定时任务调用)触发，否则会提示微信cloudApiToken错误。**

---

**参数**

**String path**

要请求的接口路径

**Object param**

要携带的参数，注意必须携带userId、token、wxAppId、seqId这几个公共参数，这些参数小程序里通过 tms.callCloudFunc 调用云函数时都有，直接透传即可。

**String method**

请求方法，支持 get/post

**String env**

请求的SinanServer环境，支持 test/production，分别对应SinanServer测试/生产环境

---

**返回值**

**Object rsp**


| 属性         | 类型    | 说明 |
| ----------- | -------|  ----   |
| errCode   | string |接口错误码|
|errMsg | string |接口错误信息描述|
| resData | object |业务数据|

---


**示例代码**

```javascript
const tmsCloud = require('@tmsfe/tms-cloud-sdk');

const routes = {
  'testfn/callsinan': async (ctx) => {
    const { userId, token, seqId, wxAppId } = ctx.event;
    const res = await tmsCloud.callSinanServer(
      'user/carlist',
      { userId, token, seqId, wxAppId },
      'post',
      'production'
    );
    return res;
  },
};

exports.main = tmsCloud.serve(routes);
```

---



### getAppCode 生成小程序码

在云函数中生成小程序码。

此方法是对微信开放能力 ```cloud.openapi.wxacode.getUnlimited``` 的二次封装，拓展了对小程序码图片文件的处理，可以拿来即用。

**注意调用此方法的云函数必须是由微信环境(小程序调用/定时任务调用)触发，否则会提示微信cloudApiToken错误。**


---

**参数**

**Object config**

生成小程序码的配置


| 属性         | 类型   | 默认值   | 必填 | 说明 |
| ----------- | -------|-----    |-----|  ----   |
| page | string |  |否 |页面 page，例如 pages/index/index，根路径前不要填加 /，不能携带参数（参数请放在scene字段里），如果不填写这个字段，默认跳主页面|
| scene | string |  |否 |query参数，会拼在page后，在扫码打开的页面onLoad可以拿到。最大32个可见字符，只支持数字，大小写英文以及部分特殊字符：!#$&'()*+,/:;=?@-._~，其它字符请自行编码为合法字符（因不支持%，中文无法使用 urlencode 处理，请使用其他编码方式）|
| checkPath | boolean | true | 否 |检查 page 是否存在，为 true 时 page 必须是已经发布的小程序存在的页面（否则报错）；为 false 时允许小程序未发布或者 page 不存在， 但 page 有数量上限（60000个）请勿滥用|
| envVersion | string | release | 否 |要打开的小程序版本。正式版为 release，体验版为 trial，开发版为 develop|
| width | number |  | 否 |二维码的宽度，单位 px，最小 280px，最大 1280px|
| autoColor | boolean |  | 否 |自动配置线条颜色，如果颜色依然是黑色，则说明不建议配置主色调，默认 false|
| lineColor | object |  | 否 |autoColor 为 false 时生效，使用 rgb 设置颜色 例如 {"r":"xxx","g":"xxx","b":"xxx"} 十进制表示|
| isHyaline | boolean | false | 否 |是否需要透明底色，为 true 时，生成透明底色的小程序|
| saveToCloud | boolean | false | 否 |是否包存到云存储，默认false，传true时将自动上传至云存储，并返回文件ID与http访问链接|

---

**返回值**

**Object rsp**

| 属性         | 类型    | 说明 |
| ----------- | -------|  ----   |
| contentType   | string |小程序码图片类型，png/jpeg|
|buffer | buffer |小程序码图片文件流|
| string64 | string |小程序码base64字符串，可直接用于 image 标签 src 展示 |
| fileID | string |云存储文件ID，当入参saveToCloud为true时有效，可直接用于 image 标签 src 展示 |
| tempFileURL | string |云存储文件http访问链接 |

---


**示例代码**

```javascript
const tmsCloud = require('@tmsfe/tms-cloud-sdk');

const routes = {
  'testfn/wxacode': async () => {
    const { tempFileURL, fileID, string64 } = await tmsCloud.getAppCode({
      page: 'modules/car/index/index',
      scene: 'wecarId=xxxx',
      checkPath: true,
      envVersion: 'release',
      saveToCloud: true,
    });
    return { tempFileURL, fileID, string64 };
  },
};

exports.main = tmsCloud.serve(routes);
```

---

### msgSecCheck 文本内容安全检测

检查一段文本是否含有违法违规内容。

此方法是对 ```cloud.openapi.security.msgSecCheck``` 的封装，简化了调用参数。

**注意调用此方法的云函数必须是由微信环境(小程序调用/定时任务调用)触发，否则会提示微信cloudApiToken错误。**

---

**参数**

**String openid**

用户的openid，可以从云函数请求上下文中获取


**String content**

需检测的文本内容，文本字数的上限为2500字，需使用UTF-8编码


---

**返回值**

**Object result**


| 属性         | 类型    | 说明 |
| ----------- | -------|  ----   |
| label   | number |命中标签枚举值，100 正常；10001 广告；20001 时政；20002 色情；20003 辱骂；20006 违法犯罪；20008 欺诈；20012 低俗；20013 版权；21000 其他|
|suggest | string |建议，有risky、pass、review三种值|

---


**示例代码**

```javascript
const tmsCloud = require('@tmsfe/tms-cloud-sdk');

const routes = {
  'testfn/msgcheck': async (ctx) => {
    const { OPENID } = ctx.wx_context;
    const { label, suggest } = await tmsCloud.msgSecCheck(OPENID, 'xxxxx');
    return { label, suggest };
  },
};

exports.main = tmsCloud.serve(routes);
```

---


### cloud

```javascript
require('@tmsfe/tms-cloud-sdk').cloud
```

等价于

```javascript
require('wx-server-sdk').cloud
```

---


### logger

```javascript
require('@tmsfe/tms-cloud-sdk').logger
```

等价于

```javascript
require('wx-server-sdk').cloud.logger()
```

---


## Contributing

在日常云开发过程中，肯定还有很多痛点，大家有想法欢迎随时提出需求，当然如果大家能协同共建，贡献代码，自然是最好的。

---
_Source: https://npm.io/package/@tmsfe/tms-cloud-sdk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
