koa-wechat-public-qs

v0.1.17

Published

8 months ago

一款基于koa的微信公众号开发中间件

Downloads

0High
0Medium
0Low

hyongnim

koa koa-wechat koa-middleware wechat weixin 微信公众号微信公众号

一款基于Koa的微信公众号开发框架

koa-wechat

介绍

koa-wetchat 需要node v7.6.0+ 来支持 ES2015 和 async
依赖koa-xml-body 中间件
可结合koa-router,也可以直接单当做koa的中间件来使用
github: 仓库地址
增加了微信服务器消息5秒未回应消息重发的处理机制

安装

$ npm install koa-wechat-public

yarn

$ yarn add koa-wechat-public

使用

const Koa = require('koa') 
const XmlParser = require ('koa-xml-body') 
const Wetchat = require('koa-wechat-public')
const app = new Koa()

//配置你的公众号参数
const wechatApp = new Wetchat({
token: TOKEN,
appId: APPID,
appSecret: APPSECRET
})

//编写一个接受消息的处理器
wechatApp.text('你好', async acc=>{ 
acc.send.sendTxtMsg("你也好")
})


app.use(new XmlParser()) 
app.use(wechatApp.start()) 
app.listen(3001)

一款基于Koa的微信公众号开发框架

功能

1. 微信公众号验证

全URL路径验证

首先在微信微信公众平台配置账号信息,获取需要配置的 APPID，APPSECRET，TOKEN; 填写你的服务器 URL 如(http://example.com/) 。
在 new 构造函数中传入必须的参数 appId,token,appSecret
使用实例的 start 方法完成接入验证。 微信服务器接入验证使用get请求，其他的消息数据均用post请求该url地址。

上面的例子中Wetchat的实例对象(我们下面简称:wechatApp) 会自动判断请求的类型，如果是get请求则做接入验证，如果是post请求则调用对应的处理器执行。

结合koa-router 接入验证

router.all('/wechat',wechat.start())

上面的写法等价于

router.get('/wechat',wechat.auth())  //接入验证
router.post('/wechat',wechat.handle())  //处理微信服务器发送的消息

这时候需要在你的微信公众平台修改服务器URL为 http://example.com/wechat 。

2. 微信公众号信息加密

如果你的微信公众号后台配置的不是明文模式，那么每次微信服务器发送到你服务器上的数据都是加密过后的。这时候wechatApp实例会自动判断消息是否是加密的如果是加密模式则会自动解密，并会已加密的模式将数据返回给服务器，无需开发者处理繁琐的加密解密的步骤。

需要在实例时传入 encodingAESKey秘钥串：

const wechatApp = new Wetchat({
token: TOKEN,
appId: APPID,
appSecret: APPSECRET,
encodingAESKey:ENCODINGAESKEY
})

3. 获取access_token

在实例上有一个 getAccessToken 的原型方法。该方法返回一个Promise<access_token:string> 。

使用示例:

wechatApp.text('token', async acc=>{ 
	 const token =  await acc.context.getAccessToken() 
acc.send.sendTxtMsg(token)		
})

在公众号发送消息:token,返回公众号的 access_token,开发者可以拿取这个access_token做进一步的操作。

Tip: 当调用处理器(用户编写的异步函数)时,实例在接受到匹配消息或事件时会将此次请求的一些上下文信息(如消息内容,发送者的openid...)包裹起来传入处理器第一个参数:acc。开发者这是候可以通过获取acc上的一些对象或方法进行下一步操作。

上面这个例子中的 context属性指向实例:wechatApp

4. 接收普通消息

普通消息的接受的数据字段可以参考普通消息数据字段

文本消息的接收.text

wechatApp.text(
'text', 
async acc=>{ 
const {toUser,fromUser,createTime,msgType,content,msgId} = acc         				 	 	
acc
.send
.sendTxtMsg([toUser,fromUser,createTime,msgType,content,msgId].join('\n')) 
})

图片消息的接收.image

wechatApp.image(async acc=>{ 
const {toUser,fromUser,createTime,msgType,msgId,picUrl,mediaId} = acc   
acc
.send
.sendTxtMsg([toUser,fromUser,createTime,msgType,msgId,picUrl,mediaId].join('\n')) 
})

语音消息的接收.voice

wechatApp.voice(async acc=>{ 
const {toUser,fromUser,createTime,msgType,msgId,format,mediaId} = acc   
acc
.send
.sendTxtMsg([toUser,fromUser,createTime,msgType,msgId,format,mediaId].join('\n')) 
})

视频消息接收.video

wechatApp.video(async acc=>{ 
const {toUser,fromUser,createTime,msgType,msgId,thumbMediaId,mediaId} = acc   
acc
.send
.sendTxtMsg([toUser,fromUser,createTime,msgType,msgId,thumbMediaId,mediaId].join('\n')) 
})

Tip:不能在一种消息类型的处理器中获取其他消息类型的数据字段，否则会出现 null或 undefined

5. 接收事件推送

接收事件推送的数据字段可以参考普通事件数据字段

用户关注公众号.subscribe

wechatApp.subscribe(async acc=>{ 
const {toUser,fromUser,createTime,msgType,msgId} = acc   
acc
.send
.sendTxtMsg([toUser,fromUser,createTime,msgType,msgId].join('\n')) 
})

用户取关公众号.unsubscribe

wechatApp.unsubscribe(async acc=>{ 
const {toUser,fromUser,createTime,msgType,msgId} = acc   
acc
.send
.sendTxtMsg([toUser,fromUser,createTime,msgType,msgId].join('\n')) 
})

自定义菜单事件推送.menu

wechatApp.menu(async acc=>{ 
const {toUser,fromUser,createTime,msgType,msgId,event,eventKey} = acc   
acc
.send
.sendTxtMsg([toUser,fromUser,createTime,msgType,msgId,event,eventKey].join('\n')) 
})

6. 发送消息 & 客服接口

自动回复消息和客服消息都封装在 Send 模块中，开发者可以通过处理器函数中的 acc参数获取 const send = acc.send

自动回复

自动回复文本 send.sendTxtMsg(content) 参数说明：

|参数名|类型|说明| |-|-|-| |content|string|自定回复的文本|

自动回复图片 send.sendImageMsg(mediaId)

参数说明：

|参数名|类型|说明| |-|-|-| |mediaId|string|通过素材接口上传到微信服务器中的临时或永久文件的媒体id|

自定回复视频 send.sendVideoMsg(mediaId,title,desc)

参数说明：

|参数名|类型|可选|说明| |-|-|-|-| |mediaId|string|否|通过素材接口上传到微信服务器中的临时或永久文件的媒体id| |title|string|是|显示的标题| |desc|string|是|描述信息|

客服消息推送

推送文本消息 send.pushTxtCustomerMsg(toUser,content)

参数说明：

|参数名|类型|可选|说明| |-|-|-|-| |toUser|string|否|要推送用户的openid| |content|string|否|推送的文本消息|

推送图片消息 send.pushImageCustomerMsg(toUser,mediaId)

参数说明：

|参数名|类型|可选|说明| |-|-|-|-| |toUser|string|否|要推送用户的openid| |mediaId|string|否|通过素材接口上传文件的媒体id|

推送视频消息

send.pushVideoCustomerMsg(toUser,mediaId,thumbMediaId,title,desc)

参数说明：

|参数名|类型|可选|说明|默认值| |-|-|-|-| -| |toUser|string|否|要推送用户的openid| | |mediaId|string|否|通过素材接口上传文件的媒体id| | |thumbMediaId|string|是|素材接口上传文件的媒体id;用来展示视频封面|meidaId| |title|string|是|标题信息|"title"| |desc|string|是|描述信息|"desc"|

推送小程序卡片

send.pushMiniProgramCardMsg(toUser,miniConfig,params)

参数说明：

|参数名|类型|可选|说明|默认值| |-|-|-|-| -| |toUser|string|否|要推送用户的openid| | |miniConfig|object:{ title: string; appId: string; pagePath: string; thumbMediaId: string }|是|小程序配置信息|通过构造函数传入的 miniConfig| |params|object:{[key:string]:any}|是|设置打开小程序的路径后的参数||

模板消息推送

推送文本消息 send.pushTemplateMsg(toUser,templateId, data?, url?, miniprogram?,topcolor?)

参数说明：

|参数名|类型|可选|说明| |-|-|-|-| |toUser|string|否|要推送用户的openid| |templateId|string|否|模板消息id|
|data|Object|是|模板数据对象例:{User:{value,color}}|
|url|string|是|模板跳转链接|
|miniprogram|Object|是|模板小程序跳转配置例: {appid,pagepath}|
|topcolor|string|是|模板消息顶部颜色|

7. 用户接口

用户接口封装在Consumer 模块中，开发者可以通过处理器函数中的 acc参数获取 const consumer = acc.consumer

获取用户信息

consumer.getUserDetail(openid) 参数说明：

|参数名|类型|可选|说明| |-|-|-|-| |openid|string|否|可以通过acc.fromUser获取用户的openid|

8. 素材管理

素材管理接口封装在Material 模块中，开发者可以通过处理器函数中的 acc参数获取 const material = acc.material

媒体素材接口参考 : 素材接口

上传临时文件

material.addTmpMaterial(localPath, type)

参数说明:

|参数名|类型|可选|说明| |-|-|-|-| |localPath|string|否|本地文件路径|
|type|string|否|素材类型：image,video,voice...|

返回值: Promise<object>

上传永久文件

material.addLongTimeMaterial(localPath,type,desc)

参数说明:

|参数名|类型|可选|说明| |-|-|-|-| |localPath|string|否|本地文件路径|
|type|string|否|素材类型：image,video; tip:目前只支持两种|
|desc|object:{title:string,desc:string}|是|描述信息|

返回值: Promise<object>

删除永久文件

material.removeLongTimeMaterial(mediaId)

参数说明:

|参数名|类型|可选|说明| |-|-|-|-| |mediaId|string|否|媒体id|

返回值: Promise<object>

9. 自定义菜单

wechatApp.createMenu(menuData) 参数说明:

|参数名|类型|可选|说明| |-|-|-|-| |menuData|object:{[key:string]:any}|否|菜单json对象|

创建示例:


//菜单在一次微信服务器对接验证中生效
wechatApp.createMenu({
"button":[
{	
"type":"click",
"name":"今日歌曲",
"key":"V1001_TODAY_MUSIC"
},
{
"name":"菜单",
"sub_button":[
{	
"type":"view",
"name":"搜索",
"url":"http://www.soso.com/"
},
{
"type":"click",
"name":"赞一下我们",
"key":"V1001_GOOD"
}]
}]
})

10. 网页授权获取用户基本信息

wechatApp.oauth(handler) 参数说明:

|参数名|类型|可选|说明| |-|-|-|-| |handler|Function|否|认证过后接受数据的处理回调函数，当认证完成时会将认证的信息，和koa的Ctx为参数，调用handler|

示例代码:

wechatApp.oauth(async function handler(data,ctx) {  
const openid = data.openid 
ctx.response.redirect('http://www.baidu.com?openid='+openid)    
	//可以做其他的一系列需要权限的操作
})

配置

下面是创建实例可传入的完整配置；

微信接口(apiUrl)的配置无需开发者传递，都是在程序中配置写好的。

目前实现的接口数量有限，我非常欢迎有想加入到这个项目中的伙伴和我一起丰富项目的功能！

const koaWechatPublicConfig = { 
appId:"APPID",
appSecret:"APPSECRET",
token:"TOKEN",
encodingAESKey:"ENCODINGAESKEY",
apiDomain :"https://api.weixin.qq.com/", //默认
apiUrl: {}, //可以在github仓库中查看已经实现的接口 ,默认不要传入! 
miniConfig:{ //相关联的小程序配置，如果你的公众号有弹出小程序的场景那么你可以在这里配置
title:"TITLE",
appId:"APPID",
pagePath:"PAGEPATH",
thumbMediaId:"THUMBMEDIAID" 
}
}

类型

普通消息接受数据字段类型定义

export type ApplicationCommonContext = {
context:WechatApplication,
send:Send,
material:Material,
consumer:Consumer,
toUser:string,
fromUser:string,
msgType:MsgType,
createTime:number,
msgId:string,
content?:string,
picUrl?:string,
mediaId?:string, 
format?:any, 
thumbMediaId?:string
locX?:number,
locY?:number,
scale?:number,
label?:string,
title?:string,
desc?:string,
url?:string    
}

普通事件接受数据字段类型定义

export type ApplicationEventContext = {
context:WechatApplication, 
send:Send,
material:Material,
consumer:Consumer,
toUser:string,
fromUser:string,
createTime:number,
msgType:MsgType,
scene: SceneType,
event:string,
eventKey?:string,
ticket?:string,
menuId?:string
}

消息类型定义

export const enum MsgType{ 
TEXT, // 0
IMAGE, // 1
VOICE, // 2
VIDEO, // 3
EVENT,  // 4 
}

事件类型定义

export const enum EventType {
SUBSCRIBE, //0 
UNSUBSCRIBE, // 1
SCAN , // 2 
MENU // 3 
}

支持

欢迎 issues
作者联系邮箱: [email protected]
可以给一波 Star !!! 有问题我们一起讨论，一起来完善这个框架
未来: 如果koa版本的库足够成熟，考虑再去适配其他web框架下的库，比如express!

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

一款基于Koa的微信公众号开发框架

koa-wechat

介绍

安装

使用

功能

1. 微信公众号验证

全URL路径验证

结合koa-router 接入验证

2. 微信公众号信息加密

3. 获取access_token

4. 接收普通消息

文本消息的接收.text

图片消息的接收.image

语音消息的接收.voice

视频消息接收.video

5. 接收事件推送

用户关注公众号.subscribe

用户取关公众号.unsubscribe

自定义菜单事件推送.menu

6. 发送消息 & 客服接口

自动回复

客服消息推送

模板消息推送

7. 用户接口

获取用户信息

8. 素材管理

上传临时文件

上传永久文件

删除永久文件

9. 自定义菜单

10. 网页授权获取用户基本信息

配置

类型

支持