# weixin-java-tools

**Repository Path**: java2demo/weixin-java-tools

## Basic Information

- **Project Name**: weixin-java-tools
- **Description**: weixin-java-tools

微信java开发工具集，本项目主要分为两大块：微信消息路由器、微信Java API

特性列表：

    不基于Servlet、和其他MVC框架，仅作为工具使用，提供更多的灵活性
    详尽的单元测试代码，可以拿来当example用
    详尽的javadoc
    access token过期自动刷新的功能
    微信服务端繁忙自动重试的功能
    提供微信错误信息的异常处理机制

- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2015-08-29
- **Last Updated**: 2020-12-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

weixin-java-tools

[![Build Status](https://travis-ci.org/chanjarster/weixin-java-tools.svg?branch=develop)](https://travis-ci.org/chanjarster/weixin-java-tools)
![Maven Central](https://img.shields.io/maven-central/v/me.chanjar/weixin-java-parent.svg)

===========


weixin-java-tools
微信java开发工具集，本项目主要分为两大块：微信消息路由器、微信Java API


特性列表：


不基于Servlet、和其他MVC框架，仅作为工具使用，提供更多的灵活性详尽的单元测试代码，可以拿来当example用详尽的javadocaccess token过期自动刷新的功能微信服务端繁忙自动重试的功能提供微信错误信息的异常处理机制
微信消息路由器
你可以使用WxMessageRouter来对微信推送过来的消息、事件进行路由，交给的WxMessageHandler处理。


使用方法：

WxMessageRouter router = new WxMessageRouter();
router
  .rule()
      .msgType("MSG_TYPE")
      .event("EVENT")
      .eventKey("EVENT_KEY")
      .content("CONTENT")
      .interceptor(interceptor).handler(handler)
  .end()
  .rule()
      .msgType("MSG_TYPE")
      .handler(handler)
  .end()
;

// 将WxXmlMessage交给消息路由器
WxXmlMessage message = WxXmlMessage.fromXml(xml);
router.route(message);


开发人员需实现自己的WxMessageHandler和WxMessageInterceptor配置路由规则时要按照从细到粗的原则，否则可能消息可能会被提前处理默认情况下消息只会被处理一次，除非使用 Rule.next()规则的结束必须用Rule.end()或者Rule.next()，否则不会生效具体使用可以看源代码中的WxMessageRouterTest单元测试，或者查看Javadoc
同步回复
WxMessageRouter默认使用异步的方式处理消息，如果要使用同步的方式处理消息，那么可以这样：

router
  .rule()
    .async(false)
    .handler(handler)
  .end()
;

WxXmlMessage message = WxXmlMessage.fromXml(xml);
// 获得同步的返回结果
WxXmlMessage res = router.route(message);
String xml = res.toXml();
// ... 将xml写入HttpServletResponse

微信Java API
使用WxService可以调用微信API。目前已实现除“微信小店”以外的所有功能。

构造WxService
WxService依赖于WxConfigStorage，WxConfigStorage是微信客户端配置所存储的地方，本工具提供了默认基于内存的实现：WxInMemoryConfigStorage。您可能在实际使用时需要提供自己的实现，比如在集群环境下存储到数据库中。

WxConfigStorage config = new WxInMemoryConfigStorage();
config.setAppId(...);
config.setSecret(...);
config.setToken(...);
WxServiceImpl wxService = new WxServiceImpl();
wxService.setWxConfigStorage(config);

验证消息if(!wxService.checkSignature(timestamp, nonce, signature)) {
   // 验证失败
}

刷新access_tokenwxService.accessTokenRefresh();


刷新后的accessToken存在WxConfigStorage中。

多媒体文件上传多媒体文件InputStream inputStream = ...;
File file = ...;
WxMediaUploadResult res = wxService.mediaUpload(mediaType, fileType, inputStream);
// 或者
res = wxService.mediaUpload(mediaType, file);
res.getType();
res.getCreated_at();
res.getMedia_id();
res.getThumb_media_id();

下载多媒体文件// 获得一个在系统临时目录的文件
File file = wxService.mediaDownload(media_id);

分组管理创建分组WxGroup res = wxService.groupCreate("测试分组1");

获得分组列表List<WxGroup> groupList = wxService.groupGet();

更新分组名WxGroup g = new WxGroup();
g.setId(...);
g.setName(...);
wxService.groupUpdate(group);

用户管理更新用户备注名wxService.userUpdateRemark(openid, "测试备注名");

获得用户信息String lang = "zh_CN"; //语言
WxUser user = wxService.userInfo(openid, lang);

获得用户列表WxUserList wxUserList = wxService.userList(next_openid);

查询用户所在分组long groupid = wxService.userGetGroup(openid);

将用户移到分组wxService.userUpdateGroup(openid, to_groupid);

发送客服消息WxCustomMessage message = new WxCustomMessage();
// 设置消息的内容等信息
wxService.customMessageSend(message);

群发消息
下面用用户列表群发（WxMassOpenIdsMessage）做例子，如果要使用分组群发，则使用WxMassGroupMessage即可。

文本消息WxMassOpenIdsMessage massMessage = new WxMassOpenIdsMessage();
massMessage.setMsgtype(WxConsts.MASS_MSG_TEXT);
massMessage.setContent("消息内容");
massMessage.getTouser().add(openid);

WxMassSendResult massResult = wxService.massOpenIdsMessageSend(massMessage);

视频消息WxMediaUploadResult uploadMediaRes = wxService.mediaUpload(WxConsts.MEDIA_VIDEO, WxConsts.FILE_MP4, inputStream);

// 把视频变成可被群发的媒体
WxMassVideo video = new WxMassVideo();
video.setTitle("测试标题");
video.setDescription("测试描述");
video.setMedia_id(uploadMediaRes.getMedia_id());
WxMassUploadResult uploadResult = wxService.massVideoUpload(video);

WxMassOpenIdsMessage massMessage = new WxMassOpenIdsMessage();
massMessage.setMsgtype(WxConsts.MASS_MSG_VIDEO);
massMessage.setMedia_id(uploadResult.getMedia_id());
massMessage.getTouser().add(openid);

WxMassSendResult massResult = wxService.massOpenIdsMessageSend(massMessage);

图片消息WxMediaUploadResult uploadMediaRes = wxService.mediaUpload(WxConsts.MEDIA_IMAGE, WxConsts.FILE_JPG, inputStream);

WxMassOpenIdsMessage massMessage = new WxMassOpenIdsMessage();
massMessage.setMsgtype(WxConsts.MASS_MSG_IMAGE);
massMessage.setMedia_id(uploadMediaRes.getMedia_id());
massMessage.getTouser().add(openid);

WxMassSendResult massResult = wxService.massOpenIdsMessageSend(massMessage);

语音消息WxMediaUploadResult uploadMediaRes = wxService.mediaUpload(WxConsts.MEDIA_VOICE, WxConsts.FILE_MP3, inputStream);

WxMassOpenIdsMessage massMessage = new WxMassOpenIdsMessage();
massMessage.setMsgtype(WxConsts.MASS_MSG_VOICE);
massMessage.setMedia_id(uploadMediaRes.getMedia_id());
massMessage.getTouser().add(openid);

WxMassSendResult massResult = wxService.massOpenIdsMessageSend(massMessage);

图文消息// 先上传图文消息里需要的图片
WxMediaUploadResult uploadMediaRes = wxService.mediaUpload(WxConsts.MEDIA_IMAGE, WxConsts.FILE_JPG, inputStream);

WxMassNews news = new WxMassNews();
WxMassNewsArticle article1 = new WxMassNewsArticle();
article1.setTitle("标题1");
article1.setContent("内容1");
article1.setThumb_media_id(uploadMediaRes.getMedia_id());
news.addArticle(article1);

WxMassNewsArticle article2 = new WxMassNewsArticle();
article2.setTitle("标题2");
article2.setContent("内容2");
article2.setThumb_media_id(uploadMediaRes.getMedia_id());
article2.setShow_cover_pic(true);
article2.setAuthor("作者2");
article2.setContent_source_url("www.baidu.com");
article2.setDigest("摘要2");
news.addArticle(article2);

WxMassUploadResult massUploadResult = wxService.massNewsUpload(news);

WxMassOpenIdsMessage massMessage = new WxMassOpenIdsMessage();
massMessage.setMsgtype(WxConsts.MASS_MSG_NEWS);
massMessage.setMedia_id(uploadResult.getMedia_id());
massMessage.getTouser().add(openid);

WxMassSendResult massResult = wxService.massOpenIdsMessageSend(massMessage);

自定义菜单创建自定义菜单WxMenu wxMenu = new WxMenu();
// 设置菜单
wxService.menuCreate(wxMenu);

删除自定义菜单wxService.menuDelete();

获得自定义菜单WxMenu wxMenu = wxService.menuGet()

二维码获得二维码ticket// 临时ticket
WxQrCodeTicket ticket = wxService.qrCodeCreateTmpTicket(scene, expire_seconds);
// 永久ticket
WxQrCodeTicket ticket = wxService.qrCodeCreateLastTicket(scene);

换取二维码图片WxQrCodeTicket ticket = ...;
// 获得一个在系统临时目录下的文件，是jpg格式的
File file = wxService.qrCodePicture(ticket);

短链接String shortUrl = wxService.shortUrl("www.baidu.com");

如何执行单元测试
将 src/test/resources/test-config.sample.xml 改成 test-config.xml 设置appId, secret, accessToken(可选), openId

mvn clean test



微信公众号、企业号Java SDK。

详细文档请看 [wiki](https://github.com/chanjarster/weixin-java-tools/wiki)。

## Quick Start

如果要开发公众号（订阅号、服务号）应用，在你的maven项目中添加：

```xml
<dependency>
  <groupId>me.chanjar</groupId>
  <artifactId>weixin-java-mp</artifactId>
  <version>1.1.5</version>
</dependency>
```

如果要开发企业号应用，在你的maven项目中添加：

```xml
<dependency>
  <groupId>me.chanjar</groupId>
  <artifactId>weixin-java-cp</artifactId>
  <version>1.1.5</version>
</dependency>
```

## SNAPSHOT版

本项目的BUG修复和新特性一般会先发布在*-SNAPSHOT版里供大家预览，如果要使用*-SNAPSHOT版，则需要在你的pom.xml中添加这段：

```xml
<repositories>
  <repository>
      <snapshots />
      <id>sonatype snapshots</id>
      <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
  </repository>
</repositories>
```

## 升级指南

* [1.0.3升级指南](https://github.com/chanjarster/weixin-java-tools/wiki/1_0_3升级指南)
* [1.1.0升级指南](https://github.com/chanjarster/weixin-java-tools/wiki/1_1_0升级指南)
* [1.1.1升级指南](https://github.com/chanjarster/weixin-java-tools/wiki/1_1_1升级指南)