wechat spring boot starter

微信相關組件，還在不斷完善中感謝JetBrains 的對這個項目的認可項目地址：https://github.com/lcy19930619/wechat-spring-boot-starter
wiki網址: https://github.com/lcy19930619/wechat-spring-boot-starter/wiki

為什麼會有這個組件的出現？

微信文檔寫的一些東西，感覺比較亂，而且很多東西需要找來找去，百度、csdn等等代碼復用性也不高，所以寫了這個組件，希望通用性好一些

適用版本

• jdk 21
• spring boot 3.2.0+ 以上

基本功能

接收微信用戶與公眾號互動的訊息

• 文字訊息
• 圖片訊息
• 音訊訊息
• 視訊訊息
• 小視訊訊息
• 地理位置資訊
• 連結訊息

接收微信用戶與公眾號觸發的事件訊息

• 用戶關注
• 用戶取消追蹤
• 用戶未關注時
• 用戶已關注時的掃描帶參數二維碼
• 上報地理位置
• 模板送達結果
• 點擊選單拉取訊息時的事件推播
• 點擊選單跳轉連結時的事件推送
• 選單掃碼推事件的事件推送
• 掃碼推事件且彈出「訊息接收中」提示框的事件推播
• 彈出系統拍照發圖的事件推播
• 彈出拍照或相簿發圖的事件推播
• 彈出微信相簿發圖器的事件推播
• 彈出地理位置選擇器的事件推播
• 點擊選單跳轉小程式的事件推送

用戶與微信公眾號資訊加密傳輸

透過設定檔開啟,開啟後，會對資訊進行加密與解密，需要在微信後台---基本配置---伺服器配置，設定訊息加解密方式為：安全模式

使用方法

新增maven 版本管理依賴

 <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>net.jlxxw</groupId>
                <artifactId>wechat-spring-boot-starter</artifactId>
                 <version>${最新版本请查看仓库}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

選擇新增需要的元件

微信事件、訊息存取模組

以netty 方式，接取微信公眾號

< dependency >
    < groupId >net.jlxxw</ groupId >
    < artifactId >wechat-event-netty-spring-boot-starter</ artifactId >
</ dependency >

以http 方式，接取微信公眾號

< dependency >
    < groupId >net.jlxxw</ groupId >
    < artifactId >wechat-event-web-spring-boot-starter</ artifactId >
</ dependency >

使用範例一：新增自訂訊息處理器

步驟：

• 繼承AbstractWeChatMessageListener (抽象訊息處理監聽器)
• 實現對應方法
• 交給Spring 管理bean，加入@Component註解

範例程式碼如下:

 import net . jlxxw . wechat . event . component . listener . AbstractWeChatMessageListener ;
import net . jlxxw . wechat . dto . message . AbstractWeChatMessage ;
import net . jlxxw . wechat . enums . WeChatMessageTypeEnum ;
import net . jlxxw . wechat . response . WeChatMessageResponse ;
import org . springframework . stereotype . Component ;

/**
 * 用户发送消息监听器
 * @author chunyang.leng
 * @date 2021-12-18 6:19 下午
 */
@ Component
public class TextMessageListener extends AbstractWeChatMessageListener {
    /**
     * 支持的消息类型
     *
     * @return
     */
    @ Override
    public WeChatMessageTypeEnum supportMessageType () {

//      文本信息 WeChatMessageTypeEnum.TEXT
//      图片信息 WeChatMessageTypeEnum.IMAGE
//      语音信息 WeChatMessageTypeEnum.VOICE
//      视频信息 WeChatMessageTypeEnum.VIDEO
//      小视频信息 WeChatMessageTypeEnum.SHORT_VIDEO
//      地理位置信息 WeChatMessageTypeEnum.LOCATION
//      链接信息 WeChatMessageTypeEnum.LINK
//      更多类型，参考枚举 WeChatMessageTypeEnum
        return WeChatMessageTypeEnum . TEXT ;
    }
    /**
     * 处理微信消息 ,return null时，会转换为 "" 返回到微信服务器
     */
    @ Override
    public WeChatMessageResponse handler ( AbstractWeChatMessage abstractWeChatMessage ) {
        // 类型转化参考 supportMessageType() 方法中枚举定义
        TextMessage textMessage = ( TextMessage ) abstractWeChatMessage ;
        // 用户发送的内容
        String content = textMessage . getContent ();
        // 用户openId
        String fromUserName = textMessage . getFromUserName ();

      // 返回图文信息，具体内容补充方法参数即可
      // WeChatMessageResponse.buildArticle();
      // 返回图片信息，具体内容补充方法参数即可
      // WeChatMessageResponse.buildImage();
      // 返回音乐信息，具体内容补充方法参数即可
      // WeChatMessageResponse.buildMusic();
      // 返回文本信息，具体内容补充方法参数即可
      // WeChatMessageResponse.buildText();
      // 返回视频信息，具体内容补充方法参数即可
      // WeChatMessageResponse.buildVideo();
      // 返回音频信息，具体内容补充方法参数即可
      // WeChatMessageResponse.buildVoice();
        return WeChatMessageResponse . buildText ( "回复用户一个文本信息" );
    }
}

使用範例二：新增自訂事件處理器

步驟：

• 繼承AbstractWeChatEventListener (抽象事件處理監聽器)
• 實現對應方法
• 交給Spring 管理bean，加入@Component註解範例程式碼如下:

 import net . jlxxw . wechat . dto . message . event . SubscribeEventMessage ;
import net . jlxxw . wechat . event . component . listener . AbstractWeChatEventListener ;
import net . jlxxw . wechat . dto . message . AbstractWeChatMessage ;
import net . jlxxw . wechat . enums . WeChatEventTypeEnum ;
import net . jlxxw . wechat . response . WeChatMessageResponse ;
import org . junit . Assert ;
import org . springframework . stereotype . Component ;

/**
 * 用户关注事件监听器
 * @author chunyang.leng
 * @date 2021-12-19 7:08 下午
 */
@ Component
public class SubscribeEventMessageListener extends AbstractWeChatEventListener {
    /**
     * 支持的事件类型
     */
    @ Override
    public WeChatEventTypeEnum supportEventType () {

//      文本信息 WeChatMessageTypeEnum.TEXT
//      图片信息 WeChatMessageTypeEnum.IMAGE
//      语音信息 WeChatMessageTypeEnum.VOICE
//      视频信息 WeChatMessageTypeEnum.VIDEO
//      小视频信息 WeChatMessageTypeEnum.SHORT_VIDEO
//      地理位置信息 WeChatMessageTypeEnum.LOCATION
//      链接信息 WeChatMessageTypeEnum.LINK
//      更多类型，参考枚举 WeChatMessageTypeEnum

      return WeChatEventTypeEnum . SUBSCRIBE ;
    }

    /**
     * 处理微信消息 ,return null时，会转换为 "" 返回到微信服务器
     */
    @ Override
    public WeChatMessageResponse handler ( AbstractWeChatMessage abstractWeChatMessage ) {
        Assert . assertNotNull ( "接收到的数据不应为空" , abstractWeChatMessage );
        // 类型转化参考 supportMessageType() 方法中枚举定义
        SubscribeEventMessage subscribeEventMessage = ( SubscribeEventMessage ) abstractWeChatMessage ;
        // 用户关注 event key
        String eventKey = subscribeEventMessage . getEventKey ();
        // 用户openId
        String fromUserName = subscribeEventMessage . getFromUserName ();


      // 返回图文信息，具体内容补充方法参数即可
      // WeChatMessageResponse.buildArticle();
      // 返回图片信息，具体内容补充方法参数即可
      // WeChatMessageResponse.buildImage();
      // 返回音乐信息，具体内容补充方法参数即可
      // WeChatMessageResponse.buildMusic();
      // 返回文本信息，具体内容补充方法参数即可
      // WeChatMessageResponse.buildText();
      // 返回视频信息，具体内容补充方法参数即可
      // WeChatMessageResponse.buildVideo();
      // 返回音频信息，具体内容补充方法参数即可
      // WeChatMessageResponse.buildVoice();
        return WeChatMessageResponse . buildText ( supportEventType (). getDescription () + " done" );
    }
}

微信公眾號各種函數入口（需引入token管理實作）

適用場景:

• 需要呼叫微信各種接口
• 微信文件看不懂

maven 座標

< dependency >
    < groupId >net.jlxxw</ groupId >
    < artifactId >wechat-function-spring-boot-starter</ artifactId >
</ dependency >

範例: 取得使用者基本信息

 import net . jlxxw . wechat . enums . LanguageEnum ;
import net . jlxxw . wechat . function . WeChatFunctionAutoConfiguration ;
import net . jlxxw . wechat . response . user . SubscriptionResponse ;
import org . springframework . beans . factory . annotation . Autowired ;
import org . springframework . beans . factory . annotation . Value ;
import org . springframework . boot . test . context . SpringBootTest ;
import org . springframework . test . context . ActiveProfiles ;
import org . springframework . test . context . TestPropertySource ;
import org . springframework . util . CollectionUtils ;
import org . springframework . stereotype . Component ;

@ Component
public class UserManagerTest  {

    @ Autowired
    public UserManager userManager ;

    public void getUserInfoTest ( String openId ) {
        
        SubscriptionResponse userInfo = userManager . getUserInfo ( openId , LanguageEnum . ZH_CN );
        Assert . assertTrue ( "查询到的用户信息不应为空" , Objects . nonNull ( userInfo ));
    }
}

token 管理模組，預設mysql 實現

適用場景：

• 需要持久化token、js api ticket
• 需要呼叫微信接口
• 具有mysql 環境
• 無自訂實作持久層
• 自動化管理token（不具備自動更新token 能力）

maven 座標

< dependency >
    < groupId >net.jlxxw</ groupId >
    < artifactId >wechat-repository-mysql-spring-boot-starter</ artifactId >
</ dependency >

擴充點

• WeChatTokenRepositorytoken 持久層入口
• WeChatJsApiTicketRepository ticket 持久層入口
• IpSegmentRepository 可信任ip 管理入口，用於判斷請求資料是否來自微信
• WeChatAiBotTokenRepository 微信的開源ai機器人（為啥不使用gpt？你能保證請求在5s內完全返回麼？公眾號也不支援SSE協議）

程式碼範例:自訂持久層token 管理

步驟:

• 實現介面
• 交給Spring 管理

 import net . jlxxw . wechat . repository . token . WeChatTokenRepository ;
import org . springframework . stereotype . Component ;

/**
 * @author chunyang.leng
 * @date 2024-01-12 17:45
 */
@ Component
public class MyTokenRepositoryImpl implements WeChatTokenRepository {

    /**
     * 保存token
     *
     * @param token
     */
    @ Override
    public void save ( String token ) {
        
    }

    /**
     * 获取保存在本地的token
     *
     * @return 保存在本地的token
     */
    @ Override
    public String get () {
        return null ;
    }
}

簡單的安全防護模組

適用場景

• 希望對接收的資料進行鑑權，該資料來自微信伺服器

特別注意

• 如果沒有引入定時器模組，則需要自行實作定時器，更新微信伺服器ip位址資訊

< dependency >
    < groupId >net.jlxxw</ groupId >
    < artifactId >wechat-security-spring-boot-starter</ artifactId >
</ dependency >

簡單的定時器模組

適用場景

• 單體應用
• 不想自己管理token 和ticket

< dependency >
    < groupId >net.jlxxw</ groupId >
    < artifactId >wechat-simple-schedule-spring-boot-starter</ artifactId >
</ dependency >

如果僅需要部分底層模組，也可以按需引入

微信介面出入參數物件集合

< dependency >
  < groupId >net.jlxxw</ groupId >
  < artifactId >wechat-common</ artifactId >
</ dependency >

微信事件回呼處理

< dependency >
  < groupId >net.jlxxw</ groupId >
  < artifactId >wechat-event</ artifactId >
</ dependency >

微信介面方法模組

< dependency >
  < groupId >net.jlxxw</ groupId >
  < artifactId >wechat-event</ artifactId >
</ dependency >

事件模式執行原理

• 透過spring Boot的spi機制（即：掃描/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports）檔案註冊spring bean 載入全部元件
• 接收微信事件回調，並透過EventBus進行相關處理

注意事項

• 一個message只能使用一個listener
• 一個event只能使用一個listener
• 如果內建的處理器無法滿足業務需求，或微信擴充了新的訊息和事件，可以註冊以下兩個bean進行處理
  • UnKnowWeChatEventListener
  • UnKnowWeChatMessageListener

事件執行流程

netty模式

1、wechat-event-netty-spring-boot-starter 隨著系統啟動進行初始化，啟動WeChatEventNettyServer.javanetty server
2.微信請求到達時，WeChatChannelMessageHandler.java 開始工作3、如果新增安全支援模組wechat-security-spring-boot-starter，則透過SecurityHandler.java對進行請求ip檢查4、請求轉發到EventBus.java 5、解析微信請求數據，根據event 以及MsgType 查找註冊到ioc容器中到監聽器（即自己寫的業務監聽器）
6.呼叫監聽器的handler 方法，執行相關業務
7.向微信伺服器返回數據

web模式

1、wechat-event-web-spring-boot-starter 隨著系統啟動進行初始化,註冊WeChatMessageController 作為程式入口2、微信資料請求發送到WeChatMessageController，並進行白名單認證。 3.請求轉送到EventBus
4.解析微信請求數據，根據event 以及MsgType 查找註冊到ioc容器中到監聽器（即自己寫的業務監聽器）
5.呼叫監聽器的handler 方法，執行相關業務
6.向微信伺服器返回數據

完整設定檔

 wechat :
  # 需要替换为真实数据
  app-id : wx97562dcec7e78aca
  # 需要替换为真实数据
  secret : 995bc3e1c1e0d30884f3d2e1f033eced
  verify-token : mytoken123456
  # 需要替换为真实数据
  encoding-aes-key : 9hFP1tCoPIRB8rFk4ukaYn6bw1Gbxs53yIGVplNsxxx
  event :
    server :
      # 引入 event-netty 使用，与 event-web 互斥
      netty :
        codec : cipher_text
        port : 9999
        log :
          enable : true
          level : debug
        verify-token-url : /verify
        core-controller-url : /we
      # 引入 event-web 使用，与 event-netty 互斥
      web :
        core-controller-url : /we
        codec : cipher_text
  # 引入 wechat-repository-mysql-spring-boot-starter 使用
  repository :
    mysql :
      enable-auto-create-js-api-table : true
      enable-auto-create-token-table : true