java对接微信公众号API，实现扫码关注公众号，触发多条消息回复

一、准备工作

1. 依赖库

这里使用的是binarywang的Wxjava 库，源码地址：https://github.com/binarywang/WxJava。截止发稿前最新版本是4.6.7.B，我采用的是4.5.0版本。

<dependency><groupId>com.github.binarywang</groupId><artifactId>weixin-java-mp</artifactId><version>4.5.0</version>
</dependency>

除了这个还使用到了fastjson2、lombok的库，可自行添加

2. 公众号的相关配置

2.1 注册并认证微信公众号平台：https://mp.weixin.qq.com/
2.2 开启相关接口的权限
2.3 获取AppId和AppSecret，以及配置IP白名单、服务器的回调地址

3. 微信相关的API文档

以下API用的比较多，可以收藏一下。

2.1 获取 Access token
https://developers.weixin.qq.com/doc/offiaccount/Basic_Information/Get_access_token.html
2.2 获取 Stable Access token
https://developers.weixin.qq.com/doc/offiaccount/Basic_Information/getStableAccessToken.html
2.3 生成带参数的二维码
https://developers.weixin.qq.com/doc/offiaccount/Account_Management/Generating_a_Parametric_QR_Code.html
2.4 接收事件推送
https://developers.weixin.qq.com/doc/offiaccount/Message_Management/Receiving_event_pushes.html
2.5 客服接口-发消息
https://developers.weixin.qq.com/doc/offiaccount/Message_Management/Service_Center_messages.html#7
2.6 新增永久素材
https://developers.weixin.qq.com/doc/offiaccount/Asset_Management/Adding_Permanent_Assets.html

二、编码过程

1. 生成带参数的二维码

// 创建二维码ticket
public static String WX_QRCODE_TICKET_URL = "https://api.weixin.qq.com/cgi-bin/qrcode/create?access_token=%s";
// 通过ticket换取二维码
public static String WX_SHOW_QRCODE_URL = "https://mp.weixin.qq.com/cgi-bin/showqrcode?ticket=%s";/**
* 生成带参数的二维码
* @param type 二维码类型，1-永久二维码、其他值-临时二维码
* @param scene 自定义参数，API支持字符串和整形，这里使用的是字符串
*/
public String generateQrCode(String type, String scene) throws Exception {if (StringUtils.isBlank(scene)) {throw new Exception("参数不正确");}// API地址String url = String.format(WX_QRCODE_TICKET_URL, getStableAccessToken());JSONObject object = new JSONObject();if ("1".equals(type)) {//永久二维码object.put("action_name", "QR_LIMIT_STR_SCENE"); // 字符串，整形使用 QR_LIMIT_SCENEJSONObject json = JSONObject.of("scene", JSONObject.of("scene_str", scene));// 字符串，整形使用 scene_idobject.put("action_info", json);} else {object.put("expire_seconds", 60 * 60 * 24); // 24小时object.put("action_name", "QR_STR_SCENE"); // 字符串，整形使用 QR_SCENEJSONObject json = JSONObject.of("scene", JSONObject.of("scene_str", scene)); // 字符串，整形使用 scene_idobject.put("action_info", json);        }log.info("object = {}", object);HttpHeaders headers = new HttpHeaders();headers.setContentType(MediaType.APPLICATION_JSON);HttpEntity<String> httpEntity = new HttpEntity<>(object.toString(), headers);ResponseEntity<String> responseEntity = restTemplate.postForEntity(url, httpEntity, String.class);if (!responseEntity.getStatusCode().is2xxSuccessful()) {throw new Exception("创建二维码ticket失败");}JSONObject responseBody = JSON.parseObject(responseEntity.getBody());log.info("responseBody = {}", responseBody);if (responseBody == null || responseBody.getInteger("errcode") != null) {throw new Exception(responseBody.getString("errmsg"));}String ticket = responseBody.getString("ticket");return String.format(WX_SHOW_QRCODE_URL, ticket);
}

成功后返回如https://mp.weixin.qq.com/cgi-bin/showqrcode?ticket=gQEa8DwAAAAxxxZm0wS05EMVoAAgRWby1nAwSAUQEA的字符串，通过浏览器访问就可以得到二维码了。

2. 获取 Stable Access token

获取tonken需要用到appId和appSecret

public static String WX_STABLE_TOKEN_BASE_URL = "https://api.weixin.qq.com/cgi-bin/stable_token";
// 微信公众号 stable accessToken, 2小时过期
public static final String MP_STABLE_ACCESS_TOKEN ="mp_stable_access_token";
// 公众号配置
@Value("${weixin.mp.appId}")
private String mpAppId;
@Value("${weixin.mp.secret}")
private String mpSecret;/**
* 获取 Stable Access token
* 避免频繁调用API，浪费调用次数，token需要做一下缓存，这里是存到redis，2小时过期
*/
private String getStableAccessToken() throws Exception {String accessToken = redisService.getCacheObject(MP_STABLE_ACCESS_TOKEN);if (accessToken == null) {JSONObject object = new JSONObject();object.put("grant_type", "client_credential"); // 固定object.put("appid", mpAppId);object.put("secret", mpSecret);String payload = object.toString();HttpHeaders headers = new HttpHeaders();headers.setContentType(MediaType.APPLICATION_JSON);HttpEntity<String> httpEntity = new HttpEntity<>(payload, headers);ResponseEntity<String> responseEntity = restTemplate.postForEntity(WX_STABLE_TOKEN_BASE_URL, httpEntity, String.class);JSONObject responseBody = JSON.parseObject(responseEntity.getBody());if (responseBody == null || responseBody.getInteger("errcode") != null) {throw new Exception("getStableAccessToken fail：" + responseBody.toJSONString());}accessToken = responseBody.getString("access_token");if (null == accessToken) {throw new Exception("getStableAccessToken fail：accessToken is null");}redisService.setCacheObject(MP_STABLE_ACCESS_TOKEN, accessToken, 7200L, TimeUnit.SECONDS);}return accessToken;
}

3. 微信公众号路由配置相关

import lombok.AllArgsConstructor;
import me.chanjar.weixin.mp.api.WxMpMessageRouter;
import me.chanjar.weixin.mp.api.WxMpService;
import me.chanjar.weixin.mp.api.impl.WxMpServiceImpl;
import me.chanjar.weixin.mp.config.impl.WxMpDefaultConfigImpl;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;import java.util.List;
import java.util.stream.Collectors;import static me.chanjar.weixin.common.api.WxConsts.EventType;
import static me.chanjar.weixin.common.api.WxConsts.XmlMsgType;
import static me.chanjar.weixin.common.api.WxConsts.XmlMsgType.EVENT;
import static me.chanjar.weixin.mp.constant.WxMpEventConstants.CustomerService.*;
import static me.chanjar.weixin.mp.constant.WxMpEventConstants.POI_CHECK_NOTIFY;/*** 微信公众号路由配置*/
@AllArgsConstructor
@Configuration
@EnableConfigurationProperties(WxMpProperties.class)
public class WxMpConfig {private final MsgHandler msgHandler;private final SubscribeHandler subscribeHandler;private final ScanHandler scanHandler;private final WxMpProperties properties;@Beanpublic WxMpService wxMpService() {final List<WxMpProperties.MpConfig> configs = this.properties.getConfigs();if (configs == null) {throw new RuntimeException("微信公众号配置错误！");}WxMpService service = new WxMpServiceImpl();service.setMultiConfigStorages(configs.stream().map(a -> {WxMpDefaultConfigImpl configStorage = new WxMpDefaultConfigImpl();configStorage.setAppId(a.getAppId());configStorage.setSecret(a.getSecret());configStorage.setToken(a.getToken());configStorage.setAesKey(a.getAesKey());return configStorage;}).collect(Collectors.toMap(WxMpDefaultConfigImpl::getAppId, a -> a, (o, n) -> o)));return service;}@Beanpublic WxMpMessageRouter messageRouter(WxMpService wxMpService) {final WxMpMessageRouter newRouter = new WxMpMessageRouter(wxMpService);// 记录所有事件的日志 （异步执行）newRouter.rule().handler(this.logHandler).next();//其他事件，此处省略... ...// 关注事件newRouter.rule().async(false).msgType(EVENT).event(EventType.SUBSCRIBE).handler(this.subscribeHandler).end();// 扫码事件newRouter.rule().async(false).msgType(EVENT).event(EventType.SCAN).handler(this.scanHandler).end();// 默认newRouter.rule().async(false).handler(this.msgHandler).end();return newRouter;}
}

微信公众号配置 WxMpProperties

@Data
@ConfigurationProperties(prefix = "weixin.mp")
public class WxMpProperties {//多个公众号配置信息private List<MpConfig> configs;@Datapublic static class MpConfig {//设置微信公众号的appidprivate String appId;//设置微信公众号的app secretprivate String secret;//设置微信公众号的tokenprivate String token;//设置微信公众号的EncodingAESKeyprivate String aesKey;}
}

4. 公众号事件处理

4.1 事件类型定义

public enum TriggerWay {TALK,SUBSCRIBE,BUTTON,
}

4.2 默认事件处理

@Component
public class MsgHandler extends AbstractHandler {@Resourceprivate WechatMessageMapper wechatMessageMapper;@Overridepublic WxMpXmlOutMessage handle(WxMpXmlMessage wxMessage,Map<String, Object> context, WxMpService weixinService,WxSessionManager sessionManager) {String msgType = wxMessage.getMsgType();String msg = wxMessage.getContent();              //从数据库查询对应的关键字配置WechatMessageConfig config = wechatMessageMapper.selectByParam(TriggerWay.TALK.name(), msg);if (config != null) {return build(config, wxMessage);}return null;}private WxMpXmlOutMessage build(WechatMessageConfig config, WxMpXmlMessage wxMessage) {switch (config.getType()) {case "NEWS":return buildNews(config, wxMessage);case "TEXT":return buildText(config, wxMessage);case "IMAGE":return buildImage(config, wxMessage);default:break;}return null;}/*** 发送图文消息** @param config* @param wxMessage* @return*/public static WxMpXmlOutMessage buildNews(WechatMessageConfig config, WxMpXmlMessage wxMessage) {WxMpXmlOutNewsMessage.Item item = new WxMpXmlOutNewsMessage.Item();item.setTitle(config.getMessage());item.setUrl(config.getUrl());item.setPicUrl(config.getPicUrl());return WxMpXmlOutMessage.NEWS().addArticle(item).fromUser(wxMessage.getToUser()).toUser(wxMessage.getFromUser()).build();}/*** 发送图片** @param config* @param wxMessage* @return*/public WxMpXmlOutMessage buildImage(WechatMessageConfig config, WxMpXmlMessage wxMessage) {//调用上传图片素材接口，此方法省略WxMediaUploadResult res = upload(config.getPicUrl());return res == null ? res : WxMpXmlOutMessage.IMAGE().mediaId(res.getMediaId()).fromUser(wxMessage.getToUser()).toUser(wxMessage.getFromUser()).build();}/*** 发送文本消息** @param config* @param wxMessage* @return*/public static WxMpXmlOutMessage buildText(WechatMessageConfig config, WxMpXmlMessage wxMessage) {return buildText(config.getMessage(), wxMessage);}/*** 发送文本消息** @param msg* @param wxMessage* @return*/public static WxMpXmlOutMessage buildText(String msg, WxMpXmlMessage wxMessage) {return WxMpXmlOutMessage.TEXT().content(msg).fromUser(wxMessage.getToUser()).toUser(wxMessage.getFromUser()).build();}
}

4.3 扫码事件处理

@Component
public class ScanHandler extends AbstractHandler {@Resourceprivate WechatMessageMapper wechatMessageMapper;// 生成二维码时给的参数private final String SCENE_STR = "xxxx";@Overridepublic WxMpXmlOutMessage handle(WxMpXmlMessage message,Map<String, Object> context, WxMpService weixinService,WxSessionManager sessionManager) throws WxErrorException {// 扫码事件处理String eventKey = message.getEventKey();logger.info("扫码用户 FromUser：{}，eventKey:{}", message.getFromUser(), eventKey);if (SCENE_STR.equals(eventKey)) {//从数据库查询对应的关键字配置WechatMessageConfig config = wechatMessageMapper.selectByParam(TriggerWay.TALK.name(), SCENE_STR);if (config != null) {//触发推送模板消息return MsgHandler.buildText(config, message);}}return null;}
}

4.4 公众号关注事件处理

扫码关注与搜索公众号关注的需求有点不同，扫码关注除了需要返回默认信息外，还需要根据二维码中的关键字返回特定内容，所以需要触发多条消息。微信的API是不支持这个操作的，只能换一种思路，可以借助客服消息发送接口。
代码如下：

@Component
public class SubscribeHandler extends AbstractHandler {@Resourceprivate WechatMessageMapper wechatMessageMapper;@Resourceprivate ScanAsynHandler scanAsynHandler;@Overridepublic WxMpXmlOutMessage handle(WxMpXmlMessage wxMessage,Map<String, Object> context, WxMpService weixinService,WxSessionManager sessionManager) throws WxErrorException {try {String fromUser = wxMessage.getFromUser();// 获取微信用户基本信息，lang: zh_CN 简体(默认)WxMpUser userWxInfo = weixinService.getUserService().userInfo(fromUser, null);if (userWxInfo != null && userWxInfo.getSubscribe()) {String unionId = userWxInfo.getUnionId();String openId = userWxInfo.getOpenId();String sceneStr = userWxInfo.getQrSceneStr();this.logger.info("新关注用户 FromUser：{}，UnionId:{}，OpenId:{}，sceneStr：{} ", fromUser, unionId, openId, sceneStr);//TODO 保存到数据库... ...//如果是扫码跳转的，关注后会自动携带sceneStr参数if (SCENE_STR.equals(sceneStr)) {//此时需要触发异步推送第二条模板消息scanAsynHandler.handleSpecial(wxMessage);}//触发新用户订阅时推送的默认模板消息WechatMessageConfig config = wechatMessageMapper.selectByParam(TriggerWay.SUBSCRIBE.name(), "SUBSCRIBE");if (config != null) {return MsgHandler.buildText(config, wxMessage);}}} catch (WxErrorException e) {int errorCode = e.getError().getErrorCode();this.logger.error("用户关注公众号失败：状态码 {}，失败原因：{}", errorCode, e.getError().getErrorMsg());}return null;}
}

ScanAsynHandler部分

//客服发送消息接口
public final static String WX_CUSTOM_BASE_URL = "https://api.weixin.qq.com/cgi-bin/message/custom/send?access_token=%s";// @Async的用法自行研究
// 触发异步推送第二条模板消息
@Async("taskExecutor")
protected Boolean handleSpecial(WxMpXmlMessage wxMessage) {   WechatMessageConfig config = wechatMessageMapper.selectByParam(TriggerWay.TALK.name(), SCENE_STR);if (config != null) {//调用客服消息发送接口String customerUrl = String.format(WX_CUSTOM_BASE_URL, getStableAccessToken());//还支持其他形式的消息内容，可查阅文档JSONObject object = JSONObject.of("touser", wxMessage.getFromUser(), "msgtype", "text", "text", JSONObject.of("content", config.getMessage()));log.info("发送模板消息：{}", object);HttpHeaders headers = new HttpHeaders();headers.setContentType(MediaType.APPLICATION_JSON);HttpEntity<String> httpEntity = new HttpEntity<>(object.toString(), headers);ResponseEntity<JSONObject> responseEntity = restTemplate.postForEntity(customerUrl, httpEntity, JSONObject.class);JSONObject body = responseEntity.getBody();log.info("模板消息发送结果：{}", body);return body.containsKey("errcode") && body.getInteger("errcode") == 0;}return false;
}