wechat spring boot starter

WeChat related components are still being improved. Thanks to JetBrains for recognizing this project. Project address: https://github.com/lcy19930619/wechat-spring-boot-starter
Wiki address: https://github.com/lcy19930619/wechat-spring-boot-starter/wiki

Why does this component appear?

Some of the things written in WeChat documents feel a bit messy, and a lot of things need to be found and searched. The code reusability of Baidu, csdn, etc. is not high, so I wrote this component in the hope of better versatility.

Applicable version

• jdk 21
• spring boot 3.2.0+ or ​​above

Basic functions

Receive information about interactions between WeChat users and official accounts

• text message
• Picture information
• audio information
• Video information
• Small video information
• Geolocation information
• Link information

Receive event information triggered by WeChat users and official accounts

• User attention
• User unfollows
• When the user is not following
• Scan the QR code with parameters when the user has followed
• Report geographic location
• Template delivery results
• Event push when clicking the menu to pull the message
• Event push when clicking menu jump link
• Event push of menu scan code push event
• Scan the QR code to push events and pop up the "message receiving" prompt box.
• Pop-up system event push for taking pictures and posting pictures
• Pop-up event push for taking pictures or posting pictures in albums
• Pop-up event push of WeChat photo album sender
• Event push for pop-up location selector
• Click the menu to jump to the event push of the applet

Encrypted transmission of information between users and WeChat public accounts

Turn it on through the configuration file. After turning it on, the information will be encrypted and decrypted. You need to set the message encryption and decryption method in the WeChat background---Basic Configuration---Server Configuration as: Safe Mode

How to use

Add maven version management dependency

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

Select to add the required components

WeChat event and message access module

Use netty to access WeChat public account

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

Access the WeChat official account via http

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

Usage example 1: Add a custom message processor

step:

• Inherit AbstractWeChatMessageListener (abstract message processing listener)
• Implement the corresponding method
• Leave it to Spring to manage the bean and add @Component annotation

The sample code is as follows:

 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 ( "回复用户一个文本信息" );
    }
}

Usage example 2: Add a custom event handler

step:

• Inherit AbstractWeChatEventListener (abstract event processing listener)
• Implement the corresponding method
• Leave it to Spring to manage the bean and add @Component annotation. The sample code is as follows:

 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" );
    }
}

Various function entrances for WeChat public accounts (token management implementation needs to be introduced)

Applicable scenarios:

• Need to call various WeChat interfaces
• I can’t understand WeChat documents

maven coordinates

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

Example: Get basic user information

 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 management module, default mysql implementation

Applicable scenarios:

• Requires persistent token and js api ticket
• Need to call WeChat interface
• Have mysql environment
• No custom implementation of persistence layer
• Automatically manage tokens (does not have the ability to automatically update tokens)

maven coordinates

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

extension point

• WeChatTokenRepositorytoken persistence layer entry
• WeChatJsApiTicketRepository ticket persistence layer entry
• IpSegmentRepository Trusted IP management entrance, used to determine whether the request data comes from WeChat
• WeChatAiBotTokenRepository WeChat’s open source ai robot (why not use gpt? Can you guarantee that the request will be completely returned within 5s? The official account does not support the SSE protocol)

Code example: Custom persistence layer token management

step:

• implement interface
• Leave it to Spring management

 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 ;
    }
}

Simple security module

Applicable scenarios

• I hope to authenticate the received data, which comes from the WeChat server.

special attention

• If the timer module is not introduced, you need to implement the timer yourself and update the WeChat server IP address information.

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

Simple timer module

Applicable scenarios

• Single application
• Don’t want to manage tokens and tickets by yourself

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

If you only need some of the underlying modules, you can also introduce them on demand.

WeChat interface access parameter object collection

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

WeChat event callback processing

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

WeChat interface method module

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

Event pattern execution principle

• Register spring beans through spring Boot's spi mechanism (ie: scan /resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports) file to load all components
• Receive WeChat event callbacks and perform related processing through EventBus

Things to note

• A message can only use one listener
• An event can only use one listener
• If the built-in processor cannot meet business needs, or WeChat expands new messages and events, you can register the following two beans for processing
  • UnKnowWeChatEventListener
  • UnKnowWeChatMessageListener

Event execution process

netty mode

1. wechat-event-netty-spring-boot-starter initializes as the system starts and starts the WeChatEventNettyServer.javanetty server
2. When the WeChat request arrives, WeChatChannelMessageHandler.java starts working 3. If the security support module wechat-security-spring-boot-starter is added, the request ip is checked through SecurityHandler.java 4. The request is forwarded to EventBus.java 5. Parsing WeChat requests data, searches and registers it in the ioc container according to the event and MsgType to the listener (that is, the business listener written by yourself)
6. Call the handler method of the listener to perform related services
7. Return data to WeChat server

web mode

1. wechat-event-web-spring-boot-starter is initialized as the system starts, and registers WeChatMessageController as the program entrance. 2. WeChat data requests are sent to WeChatMessageController, and whitelist authentication is performed. 3. Forward the request to EventBus
4. Parse the WeChat request data, find the listener registered in the ioc container according to the event and MsgType (that is, the business listener written by yourself)
5. Call the handler method of the listener to perform related services
6. Return data to WeChat server

Complete configuration file

 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