介绍

微信小程序接口对接,主要涉及以下几个方面:

  1. 模块Config
  2. 客服系统
  3. 小程序登录
  4. CabloyJS后端调用
  5. 微信API调用

1. 模块Config

我们可以通过在项目Config文件中覆盖模块Config中的参数,从而配置与微信公众号有关的信息

关于如何覆盖模块Config,请参见:Config

a-wechat/backend/src/config/config.js

  // account.minis
  config.account.minis = {
    default: {
      appID: '',
      appSecret: '',
      token: appInfo.name,
      encodingAESKey: '',
    },
  };
  • minis: 支持多个微信小程序。为了实际开发上的便利,我们默认提供一个default小程序。如果需要开发其他微信小程序,直接在minis添加新的配置即可

2. 客服系统

模块a-wechat已经对客服系统的通讯机制进行了封装,并且通过event机制进行扩展。如果我们要对用户发送的消息进行定制化的回复,可以这样操作:

关于event机制,请参见:后端事件

2.0 消息推送配置

名称 说明
服务器地址(URL) https://xxx.yyy.com/api/a/wechat/messageMini/${scene}
令牌(Token) 随机值
消息加解密密钥(EncodingAESKey) 随机值
消息加解密方式 安全模式(推荐)
数据格式 JSON
名称 说明
scene 小程序名,默认为default

2.1 meta

test-wechat/backend/src/meta.js

event: {
      implementations: {
        'a-wechat:wechatMessageMini': 'event/wechatMessageMini',
    },

声明一个event实现,通过api路由event/wechatMessageMini来响应事件a-wechat:wechatMessageMini,从而实现自定义的消息响应逻辑

2.2 路由

test-wechat/backend/src/routes.js

{ method: 'post', path: 'event/wechatMessageMini', controller: event, middlewares: 'inner,wechat', meta: { auth: { enable: false } } },
名称 说明
middlewares: inner 声明该api只能被内部调用
middlewares: wechat 注入wechat api对象,便于通过ctx.meta.wechat来调用微信api接口
auth: { enable: false } 由于是内部调用,所以禁用中间件auth,从而不需要对ctx.user进行处理

2.3 Controller

test-wechat/backend/src/controller/event.js

    async wechatMessageMini() {
      const res = await this.service.event.wechatMessageMini({
        event: this.ctx.request.body.event,
        data: this.ctx.request.body.data,
      });
      this.ctx.success(res);
    }

2.4 Service

test-wechat/backend/src/service/event.js

    async wechatMessageMini({ event, data }) {
      // scene
      const scene = data.scene;
      // message
      const message = data.message;
      if (message.MsgType === 'text') {
        event.break = true;
        const text = `${this.ctx.text.locale('zh-cn', 'Reply')}: ${message.Content}`;
        await this.ctx.meta.wechat.mini[scene].sendText(message.FromUserName, text);
      }
    }
名称 说明
scene 小程序名
event.break=true 由于同一个事件可以有多个模块进行订阅,并提供自定义的逻辑。如果想阻止后续的订阅响应,可以通过event.break=true进行终止

3. 小程序登录

测试模块test-wechat已经包含了一个微信小程序的demo程序

如何导入demo程序,请参见:快速开始 - 如何访问系统

这里对demo中涉及到的登录机制进行说明:

3.1 app.js

当小程序启动时,Cabloy SDK会通过wx.loginwx.getUserInfo获取用户信息,并调用CabloyJS后端接口,自动注册用户信息,从而完成用户登录,并返回用户数据

test-wechat/front/demo/miniprogram/app.js

    // 初始化cabloy
    this.cabloy = Cabloy(this, { scene: 'default' });
    // 登录
    this.cabloy.util.login().then(res => {
      // 由于 login 是网络请求,可能会在 Page.onLoad 之后才返回
      // 所以此处加入 callback 以防止这种情况
      if (this.cabloyLoginReadyCallback) {
        this.cabloyLoginReadyCallback(res);
      }
    }).catch(err => {
      console.log(err);
    });
  1. 首先要初始化一个cabloy实例
  2. 其次调用cabloy.util.login进行登录

3.2 pages/index/index.js

因为获取更详细的用户信息,需要用户授权。所以在进入首页后,判断如果没有得到用户授权,仍然可以显示按钮: 获取头像昵称,其属性为open-type="getUserInfo"。响应此按钮事件,当用户授权后会调用方法getUserInfo。在此方法可以再一次调用cabloy.util.login进行登录,并返回用户数据

test-wechat/front/demo/miniprogram/pages/index/index.js

  getUserInfo(e) {
    // 登录
    app.cabloy.util.login({ detail: e.detail }).then(res => {
      this.setData({
        user: res.op,
        hasUserInfo: !!res.op.userName,
      });
    }).catch(err => {
      console.log(err);
    });
  },

4. CabloyJS后端调用

Cabloy SDK提供了便捷工具,用于小程序前端访问CabloyJS的后端API接口,具体细节请参见:

test-wechat/front/demo/miniprogram/cabloy/api.js

下面以小程序后台登录为例,演示基本用法:

test-wechat/front/demo/miniprogram/cabloy/util.js

    __login({ scene, code, detail }) {
      // 后台登录
      const url = cabloy.data.wxwork ? '/a/wxwork/authMini/login' : '/a/wechat/authMini/login';
      return cabloy.api.post(url, { scene, code, detail }).then(data => {
        // user
        cabloy.data.user = data.user;
        // config
        cabloy.data.config = data.config;
        // instance
        cabloy.data.instance = data.instance;
        // ok
        return data.user;
      });
    },

5. 微信API调用

模块a-wechat通过中间件机制提供了一个中间件wechat,如果要在后端API接口中访问微信API,只需要在API接口路由中指定中间件wechat即可。然后按如下方式调用微信API

this.ctx.meta.wechat.mini.${scene}

名称 说明
scene 小程序名,默认为default

微信API基于node-webot/co-wechat-api。为了便于更灵活的添加新API,CabloyJS对主仓库发起了一个新分支,详细的API清单请参见:co-wechat-api

6. 如何判断是否在微信小程序

由于CabloyJS后端架构的普适性,我们有时候需要判断当前是否在微信小程序中,从而做出相应的处理

6.1 通过中间件判断

可以通过中间件inWechat来判断该api接口是否被微信小程序调用,如果不是则自动阻止后续逻辑的执行

src/module/test-wechat/backend/src/routes.js

  { method: 'post', path: 'test/getOpenidMini', controller: test, middlewares: 'inWechat',
      meta: {
        inWechat: {
          scene: 'wechatmini',
        },
      },
    },
名称 说明
meta.inWechat 指定中间件inWechat的参数
scene 如果指定wechatmini,表示该api只能被微信小程序调用

scene支持以下值:

名称 说明
空字符串 默认为wechat,代表微信公众号
wechatweb 代表微信Web应用
wechatmini 代表微信小程序
wechatmini${scene} 指定更明确的某个小程序,如wechatminidefault
wechat,wechatweb,wechatmini 该api可被任何一个指定的场景调用

6.2 通过代码判断

可以直接通过代码进行判断

this.ctx.meta.wechat.util.in(scene)

名称 说明
scene 场景名,如wechatmini