介绍

企业微信自建应用接口对接，主要涉及以下几个方面：

  1. 模块Config
  2. 消息推送
  3. 网页登录
  4. 网页前端JSSDK
  5. 企业微信网页布局
  6. 企业微信API调用

1. 模块Config

CabloyJS提供了两种方式来配置Config参数：

  1. 后台管理页面：页面路径为系统应用/基础管理/认证管理

  2. 项目配置：直接在项目配置文件中覆盖模块Config中的参数，从而配置与企业微信有关的信息

关于如何覆盖模块Config，请参见：Config

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

  1. 1  // account.wxwork
  2. 2  config.account.wxwork = {
  3. 3    client: 'wxwork',
  4. 4    scope: 'snsapi_base',
  5. 5    // scenes
  6. 6    scenes: {
  7. 7      selfBuilt: {
  8. 8        title: 'AuthSelfBuiltApp',
  9. 9        corpId: '',
  10. 10        agentId: '',
  11. 11        secret: '',
  12. 12        message: {
  13. 13          token: appInfo.name,
  14. 14          encodingAESKey: '',
  15. 15          reply: {
  16. 16            default: 'You are welcome!',
  17. 17          },
  18. 18        },
  19. 19        jssdk: {
  20. 20          debug: false,
  21. 21          jsApiList,
  22. 22        },
  23. 23        jssdkAgent: {
  24. 24          jsApiList: jsApiListAgent,
  25. 25        },
  26. 26      },
  27. 27      contacts: {
  28. 28        title: 'Contacts',
  29. 29        secret: '',
  30. 30        message: {
  31. 31          token: appInfo.name,
  32. 32          encodingAESKey: '',
  33. 33        },
  34. 34      },
  35. 35    },
  36. 36  };
名称 说明
scenes 配置所有微信应用的参数，包括：企业微信内置应用、第三方应用，以及自建应用。如需访问其他应用提供的API接口，直接在scenes添加新的配置即可
scenes.selfBuilt 自建应用
scenes.contacts 企业微信内置应用 - 通讯录应用

2. 消息推送

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

关于event机制，请参见：后端事件

2.0 消息推送配置

名称 说明
服务器地址(URL) https://xxx.yyy.com/api/a/wxwork/message/wxwork/selfBuilt
令牌(Token) 随机值
消息加解密密钥(EncodingAESKey) 随机值

2.1 meta

test-wxwork/backend/src/meta.js

  1. 1event: {
  2. 2  implementations: {
  3. 3    'a-wxwork:wxworkMessage': 'wxworkMessage',
  4. 4  },
  5. 5},
名称 说明
a-wxwork:wxworkMessage 模块名称:事件名称
wxworkMessage 响应事件的Bean组件

2.2 定义Bean组件

在本示例中，响应事件a-wxwork:wxworkMessage，回复用户发送的消息

src/suite-vendor/test-party/modules/test-wxwork/backend/src/bean/event.wxworkMessage.js

  1. 1module.exports = ctx => {
  2. 2  // const moduleInfo = ctx.app.meta.mockUtil.parseInfoFromPackage(__dirname);
  3. 3  class eventBean {
  4. 4
  5. 5    async execute(context, next) {
  6. 6      const data = context.data;
  7. 7      const message = data.message;
  8. 8      if (message.MsgType === 'text') {
  9. 9        context.result = {
  10. 10          ToUserName: message.FromUserName,
  11. 11          FromUserName: message.ToUserName,
  12. 12          CreateTime: new Date().getTime(),
  13. 13          MsgType: 'text',
  14. 14          Content: `${ctx.text.locale('zh-cn', 'Reply')}: ${message.Content}`,
  15. 15        };
  16. 16        // break
  17. 17        return;
  18. 18      }
  19. 19      // next
  20. 20      await next();
  21. 21    }
  22. 22
  23. 23  }
  24. 24
  25. 25  return eventBean;
  26. 26};
名称 说明
context.data 外部传入的参数
next event采用洋葱圈模型，调用next从而允许其他事件实现的执行

2.3 注册Bean组件

src/suite-vendor/test-party/modules/test-wxwork/backend/src/beans.js

  1. 1const eventWxworkMessage = require('./bean/event.wxworkMessage.js');
  2. 2
  3. 3module.exports = app => {
  4. 4  const beans = {
  5. 5    // event
  6. 6    'event.wxworkMessage': {
  7. 7      mode: 'ctx',
  8. 8      bean: eventWxworkMessage,
  9. 9    },
  10. 10  };
  11. 11  return beans;
  12. 12};
注册名称 场景 所属模块 global beanFullName
wxworkMessage event test-wxwork false test-wxwork.event.wxworkMessage

3. 网页登录

模块a-wxwork自动判断，如果当前网页处于企业微信app中，会自动转向企业微信登录，然后自动进行用户认证

4. 网页前端JSSDK

模块a-wxwork提供了便捷的组件，可以自动注入微信JSSDK，并且自动进行config配置

测试模块test-wxwork演示了如何调用微信的二维码扫描操作：

src/suite-vendor/test-party/modules/test-wxwork/front/src/pages/test/index.vue

  1. 1  created() {
  2. 2    const action = {
  3. 3      actionModule: 'a-wxwork',
  4. 4      actionComponent: 'jssdk',
  5. 5      name: 'config',
  6. 6    };
  7. 7    this.$meta.util.performAction({ ctx: this, action }).then(res => {
  8. 8      this.wx = res && res.wx;
  9. 9    }).catch(e => {
  10. 10      this.$view.toast.show({ text: e.message });
  11. 11    })
  12. 12  },
  13. 13  methods: {
  14. 14    onPerformScanQRCode() {
  15. 15      this.wx.scanQRCode({
  16. 16        needResult: 1,
  17. 17        scanType: ['qrCode', 'barCode'],
  18. 18        success: res => {
  19. 19          this.$view.toast.show({ text: res.resultStr });
  20. 20        },
  21. 21        fail: res => {
  22. 22          this.$view.toast.show({ text: res.errMsg });
  23. 23        }
  24. 24      });
  25. 25    },
  26. 26  }
  1. 先通过this.$meta.util.performAction调用模块a-wxwork提供的组件，返回wx对象
  2. 调用wx对象执行扫描二维码的微信接口

5. 企业微信网页布局

CabloyJS可以创建App应用，一个App应用是菜单页面+主页+用户页面组合。我么可以专门针对企业微信场景定义一个专属的App应用

测试模块test-wxwork演示了如何定制企业微信场景下的App应用：

  • App应用配置：src/suite-vendor/test-party/modules/test-wxwork/backend/src/config/static/app/appTest.js

  • App菜单页面配置：src/suite-vendor/test-party/modules/test-wxwork/backend/src/config/static/layout/layoutAppMenuTest.js

6. 企业微信API调用

模块a-wxwork提供了全局Bean组件wxwork，用于调用所有企业微信API，格式如下：

ctx.bean.wxwork.app.{providerScene}

名称 说明
providerScene 场景名称，比如selfBuilt(自建应用)

企业微信API基于songbug1024/co-wxwork-api。为了便于更灵活的添加新API，CabloyJS对主仓库发起了一个新分支，详细的API清单请参见：co-wxwork-api

下面以JSSDK Config为例：

src/module-system/a-wxwork/backend/src/service/jssdk.js

  1. 1async jsconfig({ url }) {
  2. 2  ...
  3. 3  return await this.ctx.bean.wxwork.app.selfBuilt.getJsConfig(params);
  4. 4}

7. 如何判断是否在企业微信中

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

7.1 通过中间件判断

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

src/suite-vendor/test-party/modules/test-wxwork/backend/src/routes.js

  1. 1  { method: 'post', path: 'test/getMemberId', controller: test, middlewares: 'inWxwork',
  2. 2      meta: {
  3. 3        inWxwork: {
  4. 4          providerName: 'wxwork',
  5. 5          providerScene: null,
  6. 6        },
  7. 7      },
  8. 8    },
名称 说明
meta.inWxwork 中间件inWxwork的参数
providerName 认证提供者名称，如果指定wxwork，表示该api只能被企业微信调用
providerScene 如果认证提供者支持多个场景，这里可以指定场景名

7.2 通过代码判断

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

  1. 1ctx.bean.wxwork.util.in({ providerName, providerScene })