dev --- 3.8.0.A版本, openProject引用 ; formao-live --- 3.7.0.B 版本, formallProject引用
Nie możesz wybrać więcej, niż 25 tematów Tematy muszą się zaczynać od litery lub cyfry, mogą zawierać myślniki ('-') i mogą mieć do 35 znaków.

README.md 8.1 KiB

10 lat temu
10 lat temu
10 lat temu
10 lat temu
10 lat temu
10 lat temu
10 lat temu
10 lat temu
10 lat temu
10 lat temu
10 lat temu
10 lat temu
10 lat temu
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315
  1. weixin-java-tools
  2. ===========
  3. 微信java开发工具集,本项目主要分为两大块:微信消息路由器、微信Java API
  4. 特性列表:
  5. 1. 不基于Servlet、和其他MVC框架,仅作为工具使用,提供更多的灵活性
  6. 2. 详尽的单元测试代码,可以拿来当example用
  7. 3. 详尽的javadoc
  8. 4. access token过期自动刷新的功能
  9. 5. 微信服务端繁忙自动重试的功能
  10. 6. 提供微信错误信息的异常处理机制
  11. ## 微信消息路由器
  12. 你可以使用``WxMessageRouter``来对微信推送过来的消息、事件进行路由,交给的``WxMessageHandler``处理。
  13. 使用方法:
  14. ```java
  15. WxMessageRouter router = new WxMessageRouter();
  16. router
  17. .rule()
  18. .msgType("MSG_TYPE")
  19. .event("EVENT")
  20. .eventKey("EVENT_KEY")
  21. .content("CONTENT")
  22. .interceptor(interceptor).handler(handler)
  23. .end()
  24. .rule()
  25. .msgType("MSG_TYPE")
  26. .handler(handler)
  27. .end()
  28. ;
  29. // 将WxXmlMessage交给消息路由器
  30. WxXmlMessage message = WxXmlMessage.fromXml(xml);
  31. router.route(message);
  32. ```
  33. 1. 开发人员需实现自己的``WxMessageHandler``和``WxMessageInterceptor``
  34. 1. 配置路由规则时要按照从细到粗的原则,否则可能消息可能会被提前处理
  35. 2. 默认情况下消息只会被处理一次,除非使用 ``Rule.next()``
  36. 3. 规则的结束必须用``Rule.end()``或者``Rule.next()``,否则不会生效
  37. 4. 具体使用可以看源代码中的``WxMessageRouterTest``单元测试,或者查看Javadoc
  38. ### 同步回复
  39. ``WxMessageRouter``默认使用异步的方式处理消息,如果要使用同步的方式处理消息,那么可以这样:
  40. ```java
  41. router
  42. .rule()
  43. .async(false)
  44. .handler(handler)
  45. .end()
  46. ;
  47. WxXmlMessage message = WxXmlMessage.fromXml(xml);
  48. // 获得同步的返回结果
  49. WxXmlMessage res = router.route(message);
  50. String xml = res.toXml();
  51. // ... 将xml写入HttpServletResponse
  52. ```
  53. ## 微信Java API
  54. 使用``WxService``可以调用微信API。目前已实现除“微信小店”以外的所有功能。
  55. ### 构造WxService
  56. ``WxService``依赖于``WxConfigStorage``,``WxConfigStorage``是微信客户端配置所存储的地方,本工具提供了默认基于内存的实现:``WxInMemoryConfigStorage``。您可能在实际使用时需要提供自己的实现,比如在集群环境下存储到数据库中。
  57. ```java
  58. WxConfigStorage config = new WxInMemoryConfigStorage();
  59. config.setAppId(...);
  60. config.setSecret(...);
  61. config.setToken(...);
  62. WxServiceImpl wxService = new WxServiceImpl();
  63. wxService.setWxConfigStorage(config);
  64. ```
  65. ### 验证消息
  66. ```java
  67. if(!wxService.checkSignature(timestamp, nonce, signature)) {
  68. // 验证失败
  69. }
  70. ```
  71. ### 刷新access_token
  72. ```java
  73. wxService.accessTokenRefresh();
  74. ```
  75. 刷新后的accessToken存在WxConfigStorage中。
  76. ### 多媒体文件
  77. #### 上传多媒体文件
  78. ```java
  79. InputStream inputStream = ...;
  80. File file = ...;
  81. WxMediaUploadResult res = wxService.mediaUpload(mediaType, fileType, inputStream);
  82. // 或者
  83. res = wxService.mediaUpload(mediaType, file);
  84. res.getType();
  85. res.getCreated_at();
  86. res.getMedia_id();
  87. res.getThumb_media_id();
  88. ```
  89. #### 下载多媒体文件
  90. ```java
  91. // 获得一个在系统临时目录的文件
  92. File file = wxService.mediaDownload(media_id);
  93. ```
  94. ### 分组管理
  95. #### 创建分组
  96. ```java
  97. WxGroup res = wxService.groupCreate("测试分组1");
  98. ```
  99. #### 获得分组列表
  100. ```java
  101. List<WxGroup> groupList = wxService.groupGet();
  102. ```
  103. #### 更新分组名
  104. ```java
  105. WxGroup g = new WxGroup();
  106. g.setId(...);
  107. g.setName(...);
  108. wxService.groupUpdate(group);
  109. ```
  110. ### 用户管理
  111. #### 更新用户备注名
  112. ```java
  113. wxService.userUpdateRemark(openid, "测试备注名");
  114. ```
  115. #### 获得用户信息
  116. ```java
  117. String lang = "zh_CN"; //语言
  118. WxUser user = wxService.userInfo(openid, lang);
  119. ```
  120. #### 获得用户列表
  121. ```java
  122. WxUserList wxUserList = wxService.userList(next_openid);
  123. ```
  124. #### 查询用户所在分组
  125. ```java
  126. long groupid = wxService.userGetGroup(openid);
  127. ```
  128. #### 将用户移到分组
  129. ```java
  130. wxService.userUpdateGroup(openid, to_groupid);
  131. ```
  132. ### 发送客服消息
  133. ```java
  134. WxCustomMessage message = new WxCustomMessage();
  135. // 设置消息的内容等信息
  136. wxService.customMessageSend(message);
  137. ```
  138. ### 群发消息
  139. 下面用用户列表群发(``WxMassOpenIdsMessage``)做例子,如果要使用分组群发,则使用``WxMassGroupMessage``即可。
  140. #### 文本消息
  141. ```java
  142. WxMassOpenIdsMessage massMessage = new WxMassOpenIdsMessage();
  143. massMessage.setMsgtype(WxConsts.MASS_MSG_TEXT);
  144. massMessage.setContent("消息内容");
  145. massMessage.getTouser().add(openid);
  146. WxMassSendResult massResult = wxService.massOpenIdsMessageSend(massMessage);
  147. ```
  148. #### 视频消息
  149. ```java
  150. WxMediaUploadResult uploadMediaRes = wxService.mediaUpload(WxConsts.MEDIA_VIDEO, WxConsts.FILE_MP4, inputStream);
  151. // 把视频变成可被群发的媒体
  152. WxMassVideo video = new WxMassVideo();
  153. video.setTitle("测试标题");
  154. video.setDescription("测试描述");
  155. video.setMedia_id(uploadMediaRes.getMedia_id());
  156. WxMassUploadResult uploadResult = wxService.massVideoUpload(video);
  157. WxMassOpenIdsMessage massMessage = new WxMassOpenIdsMessage();
  158. massMessage.setMsgtype(WxConsts.MASS_MSG_VIDEO);
  159. massMessage.setMedia_id(uploadResult.getMedia_id());
  160. massMessage.getTouser().add(openid);
  161. WxMassSendResult massResult = wxService.massOpenIdsMessageSend(massMessage);
  162. ```
  163. #### 图片消息
  164. ```java
  165. WxMediaUploadResult uploadMediaRes = wxService.mediaUpload(WxConsts.MEDIA_IMAGE, WxConsts.FILE_JPG, inputStream);
  166. WxMassOpenIdsMessage massMessage = new WxMassOpenIdsMessage();
  167. massMessage.setMsgtype(WxConsts.MASS_MSG_IMAGE);
  168. massMessage.setMedia_id(uploadMediaRes.getMedia_id());
  169. massMessage.getTouser().add(openid);
  170. WxMassSendResult massResult = wxService.massOpenIdsMessageSend(massMessage);
  171. ```
  172. #### 语音消息
  173. ```java
  174. WxMediaUploadResult uploadMediaRes = wxService.mediaUpload(WxConsts.MEDIA_VOICE, WxConsts.FILE_MP3, inputStream);
  175. WxMassOpenIdsMessage massMessage = new WxMassOpenIdsMessage();
  176. massMessage.setMsgtype(WxConsts.MASS_MSG_VOICE);
  177. massMessage.setMedia_id(uploadMediaRes.getMedia_id());
  178. massMessage.getTouser().add(openid);
  179. WxMassSendResult massResult = wxService.massOpenIdsMessageSend(massMessage);
  180. ```
  181. #### 图文消息
  182. ```java
  183. // 先上传图文消息里需要的图片
  184. WxMediaUploadResult uploadMediaRes = wxService.mediaUpload(WxConsts.MEDIA_IMAGE, WxConsts.FILE_JPG, inputStream);
  185. WxMassNews news = new WxMassNews();
  186. WxMassNewsArticle article1 = new WxMassNewsArticle();
  187. article1.setTitle("标题1");
  188. article1.setContent("内容1");
  189. article1.setThumb_media_id(uploadMediaRes.getMedia_id());
  190. news.addArticle(article1);
  191. WxMassNewsArticle article2 = new WxMassNewsArticle();
  192. article2.setTitle("标题2");
  193. article2.setContent("内容2");
  194. article2.setThumb_media_id(uploadMediaRes.getMedia_id());
  195. article2.setShow_cover_pic(true);
  196. article2.setAuthor("作者2");
  197. article2.setContent_source_url("www.baidu.com");
  198. article2.setDigest("摘要2");
  199. news.addArticle(article2);
  200. WxMassUploadResult massUploadResult = wxService.massNewsUpload(news);
  201. WxMassOpenIdsMessage massMessage = new WxMassOpenIdsMessage();
  202. massMessage.setMsgtype(WxConsts.MASS_MSG_NEWS);
  203. massMessage.setMedia_id(uploadResult.getMedia_id());
  204. massMessage.getTouser().add(openid);
  205. WxMassSendResult massResult = wxService.massOpenIdsMessageSend(massMessage);
  206. ```
  207. ### 自定义菜单
  208. #### 创建自定义菜单
  209. ```java
  210. WxMenu wxMenu = new WxMenu();
  211. // 设置菜单
  212. wxService.menuCreate(wxMenu);
  213. ```
  214. #### 删除自定义菜单
  215. ```java
  216. wxService.menuDelete();
  217. ```
  218. #### 获得自定义菜单
  219. ```java
  220. WxMenu wxMenu = wxService.menuGet()
  221. ```
  222. ### 二维码
  223. #### 获得二维码ticket
  224. ```java
  225. // 临时ticket
  226. WxQrCodeTicket ticket = wxService.qrCodeCreateTmpTicket(scene, expire_seconds);
  227. // 永久ticket
  228. WxQrCodeTicket ticket = wxService.qrCodeCreateLastTicket(scene);
  229. ```
  230. #### 换取二维码图片
  231. ```java
  232. WxQrCodeTicket ticket = ...;
  233. // 获得一个在系统临时目录下的文件,是jpg格式的
  234. File file = wxService.qrCodePicture(ticket);
  235. ```
  236. ### 短链接
  237. ```java
  238. String shortUrl = wxService.shortUrl("www.baidu.com");
  239. ```
  240. ## 如何执行单元测试
  241. 将 ``src/test/resources/test-config.sample.xml`` 改成 ``test-config.xml`` 设置appId, secret, accessToken(可选), openId
  242. ```bash
  243. mvn clean test
  244. ```