微信API工具包 [ Aha-Weixin ]

支持两种方式调用微信提供的API功能，自动维护微信的API调用凭证，开发者无需关心这部分的规则，拆包即用，支持两种方式同时使用。

• 使用微信公众号平台，比较适合开发者自己持有或所在公司自有的公众号开发。推荐在只需要控制1个或少数几个公众号的时候使用这种方式
• 使用微信开放平台（第三方平台），比较适合做为通用的基于微信的功能支撑服务的供应商平台时使用。建议在需要开发一个平台，将功能提供给大量（并非自己持有或公司自有）的公众号时，一定要通过这种方式

  <dependency>
    <groupId>io.github.rcarlosdasilva</groupId>
    <artifactId>weixin</artifactId>
    <version>0.5-SNAPSHOT</version>
  </dependency>

支持Spring Boot，并提供了starter：

  <dependency>
    <groupId>io.github.rcarlosdasilva</groupId>
    <artifactId>weixin-spring-boot-starter</artifactId>
    <version>0.2-SNAPSHOT</version>
  </dependency>

1 依赖

常用工具类：Guava
Json解析：Gson
XML解析：XStream
Http：okhttp
缓存：jredis
日志：slf4j

2 配置

2.1 配置项（具体可查看Setting类中的注释）

• throwException：boolean（默认true）：当微信API调用失败时，是否作为异常抛出。为false会将调用失败的code与message输出为日志
• useRedisCache：boolean（默认false）：是否使用redis作为缓存，存储微信API调用凭据等信息。默认是用普通Map类存储（不推荐）
• useSpringRedis：boolean（默认false）：是否使用spring中配置的redis作为缓存（只当useRedisCache为true时生效），需要在Spring Boot环境下，并添加spring-boot-starter-data-redis（暂时只支持这样）。为false并useRedisCache为true时，必须配置redisSetting
• autoLoadAuthorizedWeixinData：boolean（默认true）：使用开放平台时，公众号管理员授权成功后，是否自动获取公众号信息，设置为false则需要开发者根据授权码自己获取公众号信息（适用于希望使用微信GET跳转网页地址中的授权码获取公众号信息的场景）
• redisSetting：RedisSetting（默认null）：redis的配置信息，具体配置信息解释，参考JRedis的JedisPool类
• listeners：List：添加监听器（实例对象），具体解释会在后面说明

2.2 通用方式

weixin工具包有默认的配置，如需改变，需要实例一个Setting对象，配置内容可参照 2.1

  Setting setting = new Setting();
  // setting.setUseRedisCache(true);
  // setting.setUseSpringRedis(true);
  WeixinRegistry.withSetting(setting);

  //如果使用第三方平台
  WeixinRegistry.openPlatform(appId, appSecret, aesToken, aesKey);

2.3 或使用Spring Boot Starter

如果使用Starter，则可借用Spring Boot的自动配置，以YAML做配置为例：

weixin:
  throw-exception: true
  cache-type: reids
  use-spring-redis-config: true
  # 如果使用第三方平台
  open-platform:
    app-id: 三方平台appid
    app-secret: 三方平台secret
    aes-token: 加密aes token
    aes-key: 加密aes key

3 加载公众号信息

3.1 公众号信息内容

使用weixin工具包之前，需要将公众号的相关信息加载一下，工具包才能自动维护API调用凭证等数据。Account类用来存储这些信息，主要包含：

• key：在weixin工具包中的key，在调用API的时候，需要使用key找到对应的公众号信息。建议使用appid作为key，如果为空，默认使用appid
• appId：公众号的appid，必填
• appSecret：（只有使用公众号平台管理时）公众号的appsecret，必填
• refreshToken：授权给第三方平台的公众号authorizer_refresh_token，使用第三方平台管理公众号时必填，否则不需要设置
• mpId：公众号的原始ID，必填（第三方平台授权时，会获取到）
• nickname：无所谓
• accountType：公众号类型，暂时无所谓
• certified：（只有使用公众号平台管理时）是否认证，暂时无所谓
• aesToken：（只有使用公众号平台管理时）加密token，加密方式为密文或兼容时，必填
• aesKey：（只有使用公众号平台管理时）加密key，加密方式为密文或兼容时，必填
• encryptionType：（只有使用公众号平台管理时）加密方式
• withOpenPlatform：如果为公众号管理员授权给第三方平台的形式管理公众号，则为true（默认）。如果是使用公众号平台管理，则应该设置为false
• retryTimes：假如调用微信API时发生任何错误，自动重试的次数（默认为2）
• extension：为开发者预留的扩展信息（Object类型），开发者可根据自己的需要，利用这个字段存放业务相关的信息（例如公众号在数据库中的id之类）

使用Account.create(appId, appSecret)创建一个使用公众号平台管理的公众号信息（withOpenPlatform会自动设置为false）。使用Account.create(appId)创建一个使用第三方平台管理的公众号信息

3.2 通用方式

  Account accountWithNormalWeixin = Account.create(appId, appSecret);
  // 配置其他内容 accountWithNormalWeixin.setMpId(mpid) 等
  Account accountAuthorizedForOpenPlatform = Account.create(appId);

  // weixin工具包可以自动识别，每个公众号应该通过哪种公众号管理方式来获取API调用凭证等数据
  WeixinRegistry.register(accountWithNormalWeixin);
  WeixinRegistry.register(accountAuthorizedForOpenPlatform);
  // 有几个公众号就调用几遍WeixinRegistry.register方法

  // 假如只需要控制一个公众号，则
  // Account singleAccount = Account.create(appId, appSecret);
  // WeixinRegistry.registerUnique(singleAccount);

3.3 或使用Spring Boot Starter

实现Starter中的AccountLoader接口，并保证在Spring中注册Bean，在load方法中返回公众号信息，而不用关心如何加载，例如：

@Component
public class WeixinAccountLoader implements AccountLoader {

  @Override
  public List load() {
    List accounts = new ArrayList();

    // 创建公众号信息集合

    return accounts;
  }

}

weixin starter会尝试注入AccountLoader并自动注册load方法返回的公众号

4 监听器

weixin工具包会自动维护管理所有与微信API调用凭证相关的数据，不需要开发者介入就可以简单实现微信开发。但有时开发者会有储存微信API调用凭据（access_token）等数据的需要，这里提供了几个监听器接口，开发者可自行实现这些接口，每次凭据有更新后，监听器都会获取到最新的数据，进行相应的业务处理。

4.1 提供的接口

• AccessTokenUpdatedListener：公众号平台下有用，当weixin工具包使用appid和appsecret自动更新公众号的access_token时调用
• JsTicketUpdatedListener：公众号平台下有用，当weixin工具包使用access_token自动更新公众号的jsapi_ticket时调用
• OpenPlatformAccessTokenUpdatedListener：开放平台下有用，当weixin工具包使用verify_ticket和三方平台的component_appid, coomponent_appsecret自动更新三方平台的component_access_token时调用
• OpenPlatformLisensorAccessTokenUpdatedListener：开放平台下有用，当weixin工具包使用authorizer_refresh_token自动更新（刷新）授权方公众号的调用凭据（authorizer_access_token）时调用

4.2 通用注册监听器

  // Setting配置参考2.2
  Setting setting = new Setting();
  // 实例化监听器的实现类
  OpenPlatformAccessTokenUpdatedListener listener = new ListenerImpl();
  setting.addListener(listener);

4.3 或使用Spring Boot Starter

只要保证将监听器的实现类在Spring中注册Bean，weixin starter会自动注入监听器

5 API调用

当前weixin工具包实现了自定义菜单、素材管理、消息管理、用户管理、客服消息等功能API

• Weixin.with(key).certificate()：主要提供页面授权连接生成和JS SDK的签名生成
• Weixin.with(key).common()：提供短连接生成和二维码功能相关
• Weixin.with(key).helper()：提供接口调用次数清零和ip验证等
• Weixin.with(key).user()：提供微信粉丝用户相关功能，包括黑名单
• Weixin.with(key).userTag()：提供微信粉丝标签的增删改查
• Weixin.with(key).menu()：提供自定义菜单全部功能
• Weixin.with(key).media()：提供素材管理相关功能
• Weixin.with(key).comment()：提供图文消息留言管理功能
• Weixin.with(key).message()：提供消息发送相关功能（图文消息、模板消息、客服消息发送）
• Weixin.with(key).template()：提供模板消息相关功能（不包含模板消息发送）
• Weixin.with(key).custom()：提供客服消息全部功能（不包含客服消息发送）
• Weixin.with(key).statistics()：提供数据分析功能
• Weixin.withOpenPlatform().openAuth()：提供开放平台授权流程相关功能
• Weixin.withOpenPlatform().openCertificate()：提供开放平台中已授权的公众号认证相关功能

5.1 典型调用示例

待完善    具体功能与使用可参考io.github.rcarlosdasilva.weixin.api.internal包中API调用接口类中的注释

5.2 已实现API速查

示例： 第一行：Weixin.with(key).certificate().askAccessToken()

6 微信通知回调处理

微信的服务器会在粉丝用户给公众号发送文本、图片、语音等消息，或自定义菜单点击、扫码等事件产生时，对开发者服务器特定接口，发起通知请求，具体通知规则与内容参考微信文档。
另外，使用开放平台的第三方平台时，公众号对三方平台进行授权的过程，微信的服务器也会对开发者服务器特定接口进行通知请求。
接收并解析微信服务器发来的通知，需要开发实现NotificationHandler接口，或继承DefaultNotificationHandler（建议继承DefaultNotificationHandler）

NotificationHandler中定义了不同的方法，来响应微信文档中定义的不同通知内容。例如：

• doMessageForText方法中，处理粉丝用户对公众号发送了一条文本消息
• doMessageForImage方法中，处理粉丝用户对公众号发送了一张图片
• doEventOfMenuForClick方法中，处理粉丝用户点击了自定义菜单中类型为click的菜单按钮

6.1 指定通知处理类

实例化NotificationHandler的实现类，在系统启动时（保证在微信服务器发来通知前），执行：

  NotificationHandlerProxy.proxy(notificationHandler);

如果使用Spring Boot Starter，则只要保证将NotificationHandler的实现类在Spring中注册Bean即可，Starter会自动识别，例如：

@Component
public class BusinessNotificationHandler extends DefaultNotificationHandler {
  ...
}

6.2 如何响应

NotificationHandler接口中定义的每个方法中都有一个NotificationResponseBuilder（响应构造器）参数，开发者根据业务需求通过NotificationResponseBuilder构造响应内容。

构造器可响应给微信如下几种类型的内容：

• 不响应：使用responseNothing方法，会返回给微信success
• 文本：使用responseText方法
• 图片：使用responseImage方法，需要指定一个已添加到微信（有media_id）的图片
• 语音：使用responseVoice方法，类似图片
• 视频：使用responseVideo方法，类似图片
• 音乐：使用responseMusic方法
• 图文：使用responseNewsOneOf方法，如果希望响应多图文，就调用多遍该方法

在每个方法中都会有一个Notification类型参数，使用notification.getAccount()方法就可以获取到当前通知消息相关的公众号信息（在开放平台下，进行授权过程的相关方法中除外）。

6.3 接收通知

开发者在获取到微信传来的参数后，使用NotificationHandlerProxy.instance().process()方法获取返回微信的内容。在这个方法中，会自动解密，根据NotificationHandler实现类中对应的方法中构建的响应内容进行加密，生成加密后的XML格式响应结果。

使用Spring MVC的例子（开放平台）：

  @RequestMapping(value = "notification/open/{appId}", method = RequestMethod.POST)
  @ResponseBody
  public String notificationCallback(@PathVariable String appId,
      @RequestParam(value = "msg_signature", required = true) String signature,
      @RequestParam(value = "timestamp", required = true) long timestamp,
      @RequestParam(value = "nonce", required = true) String nonce, @RequestBody String content) {

    return NotificationHandlerProxy.instance().process(appId, content, signature, timestamp, nonce);
  }

使用Spring MVC的例子（公众号平台）：

  @RequestMapping(value = "notification", method = RequestMethod.POST)
  @ResponseBody
  public String notificationCallback(@RequestParam(value = "signature", required = true) String signature,
      @RequestParam(value = "timestamp", required = true) long timestamp,
      @RequestParam(value = "nonce", required = true) String nonce, @RequestBody String content) {

    return NotificationHandlerProxy.instance().process(content, signature, timestamp, nonce);
  }

注意：开放平台中，签名获取的参数名为msg_signature，公众号平台中是signature

7 （开放平台）第三方平台公众号授权过程

开发者需要暴露两个接口，授权事件接收URL和公众号消息与事件接收URL。这里解释授权事件接收URL中的代码。

使用Spring MVC的例子（与普通消息和事件消息类似）：

  @RequestMapping(value = "authorization", method = RequestMethod.POST)
  @ResponseBody
  public String authorizationCallback(@RequestParam(value = "msg_signature", required = true) String signature,
      @RequestParam(value = "timestamp", required = true) long timestamp,
      @RequestParam(value = "nonce", required = true) String nonce, @RequestBody String content) {

    return NotificationHandlerProxy.instance().process(content, signature, timestamp, nonce);
  }

授权过程中会调用NotificationHandler的doInfoOfComponentVerifyTicket、doInfoOfAuthorizeSucceeded、doInfoOfAuthorizeCanceled、doInfoOfAuthorizeUpdated四个方法

• doInfoOfComponentVerifyTicket：微信服务器每十分钟会通知一次开发者服务器，weixin工具包会自动缓存传过来的verify_ticket，开发者如无特别的需要，可不重写该方法
• doInfoOfAuthorizeSucceeded：公众号管理员授权成功后，微信服务器会通知开发者服务器，weixin工具包在这个时候，会自动使用授权码，将接口调用凭据（authorizer_access_token, authorizer_refresh_token）、授权信息以及授权方的帐号基本信息获取回来。在该方法中，开发者可直接将这部分信息进行相应的存储（authorizer_refresh_token必须要保存）。开发者在处理完必要的业务之后，需要参考3.1，返回公众号信息Bean（Account），weixin工具包会自动对该公众号进行加载
• doInfoOfAuthorizeCanceled：公众号管理员取消授权时，微信服务器会通知开发者服务器，开发者可在该方法中修改对应的业务信息
• doInfoOfAuthorizeUpdated：公众号管理员更新授权内容时，微信服务器会通知开发者服务器，传递的信息等与授权成功相同

7.1 授权地址

开发者不用关心三方平台的component_access_token，也无须关心预授权码如何获取，在引导公众号管理员授权时，使用Weixin.withOpenPlatform().openAuth() .openPlatformAuthorize("成功后跳转地址")方法获取授权地址。

7.2 授权成功（更新）后的处理

管理员授权成功后，微信会做两次请求：1. 页面的跳转（GET），并在页面地址后加上授权码。 2. 微信服务器会发起对开发者服务器的授权事件接收URL请求（POST），请求内容中会传递授权码过来

两次请求都有授权码，这里建议，在页面的跳转请求中，获取到授权码后不进行任何授权相关的操作，这部分工作应放在服务器端完成。如开发者需要在跳转页面中，显示本次授权的公众号相关信息，可利用授权码对开发者服务器做轮询调取