SpringBoot快速接入微信公众号后端服务开发的实战指南

# application.yml
server:
  port: 8088
spring:
  application:
    name: wx-service
  datasource:
    url: jdbc:mysql://localhost:3306/wx_service?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai&useSSL=false
    username: root
    password: your_password
    driver-class-name: com.mysql.cj.jdbc.Driver
# MyBatis-Plus 配置
mybatis-plus:
  mapper-locations: classpath*:mapper/**/*.xml
  type-aliases-package: com.example.wxservice.entity
  configuration:
    map-underscore-to-camel-case: true
# 微信公众号配置
wx:
  # 公众号配置（从微信公众平台 -> 开发 -> 基本配置获取）
  app-id: wx175ab95db5361a27
  app-secret: 85fba4e2d45a1987c1ab9e7e5d19aa03
  token: 9DNI6IEfqN1lEVs5SvGLr5l5wCCtU
  debug: true
  # 小程序配置（用于生成 URL Link 跳转小程序）
  mini-app-id: wx8bba9e3c31c52c86
  mini-app-secret: 0519397d042233f5b061d90ab0098503
  mini-app-path: pages/index/index

@RestController
@RequestMapping("/wx")
public class WechatController {

    private final WechatService wechatService;

    /**
     * 服务器地址验证（GET）
     * 微信配置服务器URL时，会携带 signature、timestamp、nonce、echostr 参数访问此接口
     */
    @GetMapping("/callback")
    public String verifyServer(
            @RequestParam("signature") String signature,
            @RequestParam("timestamp") String timestamp,
            @RequestParam("nonce") String nonce,
            @RequestParam("echostr") String echostr) {
        
        String result = wechatService.verifyServer(signature, timestamp, nonce, echostr);
        return result != null ? result : "验证失败";
    }
}

/**
 * 微信签名验证算法（SHA1）
 * 
 * 验证步骤：
 * 1. 将 token、timestamp、nonce 三个参数按字典序排序
 * 2. 将排序后的字符串拼接成一个字符串
 * 3. 对拼接后的字符串进行 SHA1 加密
 * 4. 比对加密结果与微信传来的 signature 是否一致
 */
public static boolean checkSignature(String token, String signature, 
                                     String timestamp, String nonce) {
    // 1. 字典序排序
    String[] arr = new String[]{token, timestamp, nonce};
    Arrays.sort(arr);
    
    // 2. 拼接字符串
    StringBuilder content = new StringBuilder();
    for (String s : arr) {
        content.append(s);
    }
    
    // 3. SHA1 加密
    String sha1 = sha1(content.toString());
    
    // 4. 比对签名
    return signature.equals(sha1);
}

/**
 * 接收微信消息推送（POST）
 * 
 * 注意：此接口的 Content-Type 是 application/xml，不是 application/json
 */
@PostMapping(value = "/callback", produces = "application/xml; charset=UTF-8")
public String receiveMessage(HttpServletRequest request) {
    try {
        // 读取请求体中的 XML 数据
        StringBuilder sb = new StringBuilder();
        BufferedReader reader = request.getReader();
        String line;
        while ((line = reader.readLine()) != null) {
            sb.append(line);
        }
        String xmlData = sb.toString();
        
        // 交给 Service 层处理
        return wechatService.handleMessage(xmlData);
    } catch (Exception e) {
        log.error("接收微信消息时发生错误", e);
        return "success"; // 即使异常也要返回 success，否则微信会重试
    }
}

<xml>
    <ToUserName><![CDATA[gh_xxx]]></ToUserName>
    <FromUserName><![CDATA[openid_xxx]]></FromUserName>
    <CreateTime>123456789</CreateTime>
    <MsgType><![CDATA[text]]></MsgType>
    <Content><![CDATA[你好]]></Content>
</xml>

/**
 * 解析 XML 消息中的节点值
 * 
 * 支持两种格式：
 * 1. CDATA 格式：<TagName><![CDATA[value]]></TagName>
 * 2. 普通格式：<TagName>value</TagName>
 */
public static String getXmlValue(String xml, String nodeName) {
    if (xml == null || xml.isEmpty()) {
        return null;
    }
    
    // 优先尝试 CDATA 格式
    String cdataStart = "<" + nodeName + "><![CDATA[";
    String cdataEnd = "]]></" + nodeName + ">";
    int startIndex = xml.indexOf(cdataStart);
    int endIndex = xml.indexOf(cdataEnd);
    if (startIndex != -1 && endIndex != -1) {
        return xml.substring(startIndex + cdataStart.length(), endIndex);
    }

    // 再尝试普通标签格式
    String startTag = "<" + nodeName + ">";
    String endTag = "</" + nodeName + ">";
    startIndex = xml.indexOf(startTag);
    endIndex = xml.indexOf(endTag);
    if (startIndex != -1 && endIndex != -1) {
        return xml.substring(startIndex + startTag.length(), endIndex);
    }

    return null;
}

@Override
public String handleMessage(String xmlData) {
    String msgType = WechatUtil.getXmlValue(xmlData, "MsgType");
    String fromUser = WechatUtil.getXmlValue(xmlData, "FromUserName");
    String toUser = WechatUtil.getXmlValue(xmlData, "ToUserName");

    // 处理事件（关注、取消关注、扫码等）
    if ("event".equals(msgType)) {
        return handleEvent(xmlData, fromUser, toUser);
    }

    // 处理文本、语音、文档消息
    if ("text".equals(msgType) || "voice".equals(msgType) || "file".equals(msgType)) {
        return handleTextMessage(xmlData, fromUser, toUser);
    }

    // 其他类型消息，回复默认信息
    return "success";
}

private String handleTextMessage(String xmlData, String fromUser, String toUser) {
    // ...
    WxUser user = wxUserMapper.selectByOpenId(fromUser);
    int interactionCount = user.getInteractionCount() != null ? user.getInteractionCount() : 0;

    if (interactionCount == 0) {
        // 第一次：引导使用服务（带小程序链接）
        String reply = buildDefaultNewsReply(fromUser, toUser);
        user.setInteractionCount(1);
        wxUserMapper.updateById(user);
        return reply;
    } else if (interactionCount == 1) {
        // 第二次：引导描述需求
        String reply = buildSecondReply(fromUser, toUser);
        user.setInteractionCount(2);
        wxUserMapper.updateById(user);
        return reply;
    } else {
        // 第N次：安抚用户
        user.setInteractionCount(interactionCount + 1);
        wxUserMapper.updateById(user);
        return WechatUtil.buildTextMessage(fromUser, toUser, 
            "感谢您的反馈，稍后会有服务人员与您联系，请您关注公众号信息。");
    }
}

public String generateUrlLink(String path) {
    String accessToken = getAccessToken();  // 带本地缓存
    
    // 分离 path 和 query
    String pagePath = path;
    String query = "";
    int queryIndex = path.indexOf("?");
    if (queryIndex != -1) {
        pagePath = path.substring(0, queryIndex);
        query = path.substring(queryIndex + 1);
    }
    
    // 调用微信接口
    Map<String, Object> body = new HashMap<>();
    body.put("path", pagePath);
    body.put("query", query);
    body.put("is_expire", false);
    // ...
}

CREATE TABLE wx_user (
    id                  BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '主键ID',
    open_id             VARCHAR(64) NOT NULL COMMENT '微信用户的OpenID（唯一标识）',
    nick_name           VARCHAR(128) DEFAULT NULL COMMENT '用户昵称',
    sex                 INT DEFAULT 0 COMMENT '性别 0:未知 1:男 2:女',
    city                VARCHAR(64) DEFAULT NULL COMMENT '用户所在城市',
    province            VARCHAR(64) DEFAULT NULL COMMENT '用户所在省份',
    country             VARCHAR(64) DEFAULT NULL COMMENT '用户所在国家',
    head_img_url        VARCHAR(512) DEFAULT NULL COMMENT '用户头像URL',
    subscribe_status    INT DEFAULT 1 COMMENT '关注状态 0:取消关注 1:已关注',
    subscribe_time      DATETIME DEFAULT NULL COMMENT '关注时间',
    unsubscribe_time    DATETIME DEFAULT NULL COMMENT '取消关注时间',
    interaction_count   INT DEFAULT 0 COMMENT '用户交互次数（用于自动回复规则）',
    create_time         DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    update_time         DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    UNIQUE KEY uk_open_id (open_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='微信公众号用户表';

ALTER TABLE wx_user ADD COLUMN interaction_count INT DEFAULT 0 
COMMENT '用户交互次数（用于自动回复规则）';

{"errcode": 412, "errmsg": "..."}