开发指南

API 文档

接口

最近更新时间:2022-03-18 11:03:49

单页模板通过开放的接口来与业务已有业务系统进行交互。接口分为2类,调用关系不同。

  • 标准接口:业务方主动调用的接口,根据来源不同分为如下 小程序端、服务端
  • 自定义接口:模块主动调用业务的接口,模块定义好出入参需要由业务侧来实现。例如:签到打卡模块内发积分、发虚拟奖励,需要有额外的积分模块、奖品模块提供接口来实现发放。
说明:

@cloudbase/page-module 同一个 SDK 支持小程序以及服务端。

标准接口

小程序端接口

最低基础库2.13.0
小程序端最低基础库版本为2.13.0,建议前往 设置最低基础库版本

引入 SDK

小程序组件自带 SDK
小程序组件导入时自带 @cloudbase/page-module 的 npm 包,可直接使用,无需额外引入。

miniprogram 根目录下安装
详情请参见 小程序使用 Npm 包 进行引入。

  1. miniprogram 下执行命令 npm install @cloudbase/page-module
  2. 构建 npm,单击开发者工具中的菜单栏:工具 > 构建 npm
  3. 勾选“使用 npm 模块”选项
  4. 构建完成后即可使用 npm 包。

代码示例

// 方式1:可使用相对路径引用场景模块下的npm模块 ../sign-up/miniprogram_npm/@cloudbase/page-module
import { PageModule } from '../sign-up/miniprogram_npm/@cloudbase/page-module'
// 方式2:推荐 在全局安装一份即可 
import { PageModule } from '@cloudbase/page-module'

// 初始化模块名称
const pageModule = new PageModule('sign-up')

// promise风格的调用
pageModule.callMethod('doRemind', {
  openId: XXX,
  temid: XXX,
  page: XXX
})
.then(res => {
  console.log(res.result)
})
.catch(console.error)

服务端接口

安装 npm

npm install @cloudbase/page-module wx-server-sdk -s

代码示例

// 安装npm依赖`npm install @cloudbase/page-module wx-server-sdk`
const {PageModule} = require('@cloudbase/page-module')
// 初始化模块名称,如果是在云函数里则无需 secretId和secretKey。云函数外,需要先获取访问密钥 https://developers.weixin.qq.com/miniprogram/dev/wxcloud/reference-http-api/utils/getQcloudToken.html
const pageModule = new PageModule('sign-up', {
secretId: 'your-secret-id',
secretKey: 'your-secret-key'
})

// promise风格的调用
pageModule.callMethod('getPrizeRule', {})
.then(res => {
console.log(res.result)
})
.catch(console.error)

OpenAPI

当前仅支持 Node.js 版本的 SDK,其他语言将通过 OpenAPI 进行支持(预期4月发布)。

自定义接口

自定义接口由模块定义接口名、入参、出参,业务方来实现接口逻辑。模块会调用自定义接口来实现与业务已有系统的数据打通,接口调用与 服务端接口 一致。

场景举例:用户签到后发放积分,签到模块会先调用业务实现的 发积分 接口,积分发放成功则完成签到。

连接到云函数

云开发相关操作,可前往 云开发 了解详情。

  1. 选择云开发环境,部署示例云函数。
  2. 确认接口协议前往实现。
  3. 请前往微信开发者工具,切换云开发的环境。
  4. 右键云函数文件夹进行代码下载。
  5. 在云函数下新建 /api/send_prize.js 文件并实现该接口。
  6. 上传云函数。
  7. 测试云函数,在控制台内可先对接口进行测试。
  8. 单击下一步,确认连接到云函数。

连接到相应模块

开发者无需开发,一键配置即可打通2个模块。

例如:签到打卡中得到的积分直接发到积分中心模块。

实现规范

一个模块下有多个自定义接口,开发者可选择一个云开发环境,系统会部署一个示例云函数到该环境下。开发者在该函数内实现该模块的所有自定义接口。

目录结构

.
├── README.md
├── api # 存放api实现的文件,文件名对应接口名
│ ├── demo.js # demo示例文件
├── example # 模块给的示例实现,可以接入使用
│ ├── set_remind.js
│ └── set_remind.md
├── index.js # 入口文件
└── package.json # 依赖声明

实现接口

例如,当前需要实现的自定义接口为 send_prize,则编辑 /api/send_prize.js 文件。

const objCloud = require('wx-server-sdk');
/**
* 具体的业务函数,在这里实现您发奖,发积分的逻辑,data 入参是固定的,出参必须遵循规范
* @param { object } data - 业务入参
* @returns { object } - 返回参数
* @returns { number } code 返回的状态标记,成功返回0, 非0代表错误
* @returns { string } msg 如果成功,则可以不返回,如果失败把相应的错误原因中文描述放在这里
* @returns { object } result 接口调用返回的信息
*
*/

module.exports = async (data) => {
console.log("参数:", data);
// 这里实现您具体的业务逻辑,例如发积分,发奖

return {
code:0,
msg:'suc',
// 出参需要遵守自定接口规范
result: {
sendResult: true
}};
};

运维指引

前往云开发 > 云函数 > 日志页面,按照函数维度进行日志查看。

code 错误码如下,重点关注业务自身实现代码异常 METHOD_EXEC_FAILURE:

  • PERMISSION_DENIED 无权限调用。
  • METHOD_NOT_FOUND 方法未找到。
  • METHOD_NOT_FUNCTION 实现上为非 function。
  • METHOD_EXEC_FAILURE 用户自定义实现的 function 失败。
  • UNKNOWN_ERROR 未知错误。
目录