Spring Boot项目中短信通知替换为微信公众号模板消息推送的使用方案-深圳市維司達科技有限公司

文章目录

- 1、准备工作
- - 1.1、公众号类型
  - 1.2、获取关键凭证
  - 1.3、配置IP白名单
  - 1.3、申请模板消息
- 2、Spring Boot 后端技术实现
- - 2.1、添加Maven依赖
  - 2.2、配置文件 (application.yml)
  - 2.3、核心服务类开发
- 3、与系统业务模块整合
- - 3.1、定义消息 DTO
  - 3.2、业务逻辑替换策略
- 4、关键注意事项与优化
- - 4.1、降级与兜底机制
  - 4.2、模板ID管理
  - 4.3、用户取消关注处理
  - 4.3、跳转链接 (URL)
- 5、总结

在Spring Boot项目中使用微信公众号模板消息有很多优点：微信消息的到达率高于手机通信短信，且成本更低（模板消息通常免费）。

本文详细介绍涉及微信公众号配置、后端接口开发和业务逻辑整合的微信公众号模板消息完整技术方案。

前提条件：

用户必须关注公众号。
必须有appid、secret、openid、消息模板Id。
根据appid和secret、获取token。
通过openid和token和模板Id进行消息推送。

1、准备工作

1.1、公众号类型

必须是已认证的服务号。订阅号没有模板消息接口权限，未认证的服务号无法调用接口。

1.2、获取关键凭证

登录公众号后台，进入“开发” -> “基本配置”。
记下 AppID 和 AppSecret，这是后端调用接口的“身份证”。

1.3、配置IP白名单

在“开发” -> “开发设置”中，将你的Spring Boot项目服务器公网IP添加到IP白名单中，否则服务器无法获取access_token。

1.3、申请模板消息

进入“功能” -> “模板消息”（或在接口列表中搜索模板）。
从模板库中搜索与系统业务相关的模板。

关键点：记下每个模板的模板ID（如 TEMPLATE_ID_1, TEMPLATE_ID_2）。
注意字段：记录下模板中的关键词（如 keyword1, keyword2 或 first, remark），后端发送数据时必须与这些字段名完全一致。

2、Spring Boot 后端技术实现

将微信公众号消息推送功能集成到现有的系统中。

2.1、添加Maven依赖

在 pom.xml 中引入HTTP客户端和JSON处理库（如果项目中还没有的话）：

<dependencies><!-- Spring Web --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><!-- HTTP Client --><dependency><groupId>org.apache.httpcomponents</groupId><artifactId>httpclient</artifactId><version>4.5.13</version></dependency><!-- JSON处理 (Fastjson或Jackson) --><dependency><groupId>com.alibaba</groupId><artifactId>fastjson</artifactId><version>1.2.83</version></dependency></dependencies>

2.2、配置文件 (application.yml)

将公众号的配置信息外置，方便维护：

wechat:app-id:your_app_id_hereapp-secret:your_app_secret_here# 定义不同业务场景的模板IDtemplates:apply:TEMPLATE_ID_FOR_APPLY# 申请模板IDdispatch:TEMPLATE_ID_FOR_DISPATCH# 通知模板IDfinish:TEMPLATE_ID_FOR_FINISH# 订单完成模板ID

2.3、核心服务类开发

AccessToken 管理（核心）
微信接口调用需要 access_token，它有效期为2小时，必须全局缓存，不能每次发消息都去请求，否则会触发频率限制。
实现：创建一个 AccessTokenService，使用单例模式或 @Component 管理。在获取 token 时，判断是否过期（当前时间 > 过期时间-5分钟），如果过期则调用微信接口刷新。
模板消息推送服务
创建 WeChatTemplateService。
构建请求体：根据微信官方文档格式，构建 JSON 数据包，包含 touser (用户OpenID),template_id, url (点击消息跳转的页面，可选), data (消息内容)。
发送请求：使用 HttpClient 调用 https://api.weixin.qq.com/cgi-bin/message/template/send 接口。
错误处理：捕获微信返回的 errcode，如 40001 (凭证错误)、40037 (模板ID无效) 等，并记录日志。
获取用户 OpenID (身份绑定)
短信是通过手机号发送的，微信是通过 OpenID 发送的。需要建立用户账号与OpenID的映射关系。
方案：在现有系统的前端（H5或小程序），用户登录或绑定页面时，通过微信授权（snsapi_base 或 snsapi_userinfo）获取用户的 OpenID。
存储：将 OpenID 存入用户表（User表）或专门的微信绑定表中。
查询：当业务模块（如申请订单）触发时，根据消费哲用户的用户ID查询出对应的 OpenID。

3、与系统业务模块整合

这是将“技术”落地到“业务”的关键步骤。替换现有的阿里短信调用逻辑。

3.1、定义消息 DTO

创建一个通用的消息数据传输对象，或者针对不同场景创建 Map：

// 例如：订单申请通知数据Map<String,Object>applyData=newHashMap<>();applyData.put("first","您的申请已提交成功！");applyData.put("keyword1","商务接待");applyData.put("keyword2","2023-10-27 09:00");applyData.put("remark","请耐心等待。");

3.2、业务逻辑替换策略

找到原来调用阿里短信的 Service 层代码（通常在 SmsService.send() 附近），进行替换或并行调用。

场景一：订单申请 (Apply)
原逻辑：smsService.send(phone, “申请已提交…”)
新逻辑：根据申请人ID查询数据库，获取 openId。
组装“订单申请”模板数据。
调用 weChatTemplateService.send(openId, templateId_apply, data)。
建议：初期可以短信和微信同时发，观察微信的到达率，稳定后再下线短信，避免影响用户体验。
场景二：派单 (Dispatch)
触发点：当调度员在系统中点击“派单”按钮，分配了任务后。
逻辑：获取接收人的 OpenID，组装“订单通知”模板（包含订单号、客服姓名、电话、预计到达时间）。
场景三：订单完成 (Finish)
触发点：派单员在移动端点击“结束行程”或系统自动判定行程结束后。
逻辑：通知申请人行程已结束，包含实际费用、行驶里程等信息。

4、关键注意事项与优化

4.1、降级与兜底机制

网络问题：如果微信服务器超时或不可用，系统不能报错卡住。建议引入 RabbitMQ/Kafka 或 Spring Task，将消息推送到队列异步处理，失败的消息进入死信队列，由定时任务重试。

4.2、模板ID管理

不要把模板ID写死在代码里。建议在系统后台管理界面增加一个“消息模板配置”菜单，将 yml 中的配置映射到数据库，方便运营人员随时更换模板而无需重启服务。

4.3、用户取消关注处理

如果用户取消关注公众号，发送消息会失败。在捕获到“用户不存在”或“关注状态异常”的错误码时，更新数据库中该用户的微信绑定状态为“无效”，后续不再推送。

4.3、跳转链接 (URL)

模板消息支持点击跳转。url 参数可以设置为系统的H5页面地址，例如直接跳转到“我的订单详情页”，提升用户体验。

5、总结

实施步骤清单：

步骤	动作	责任人
1	申请/确认服务号，获取 AppID/Secret，申请模板ID	运维/项目经理
2	在Spring Boot中添加配置和依赖，编写 AccessToken 和 SendMessage 工具类	后端开发
3	前端实现微信授权，获取 OpenID 并绑定到用户表	前端/全栈开发
4	修改 ApplyService, DispatchService 等业务代码，调用新工具类	后端开发
5	测试全流程（申请->派单->完成），确认消息能收到且内容正确	测试/QA