微信生态覆盖超13亿月活用户,已成为企业数字化转型的核心入口。作为开发者,掌握微信接口开发Java技术体系,意味着掌握高价值技术能力与商业机会。
本页面系统梳理微信开放平台三大核心场景——公众号(服务号/订阅号)、小程序、企业微信——的接口开发要点,结合Java生态(Spring Boot为主)提供可落地的技术方案。所有内容基于微信官方最新文档(2025年Q1版本),兼顾生产环境稳定性、安全性与可维护性。
微信接口按功能划分为12大模块,Java开发者需重点关注:
| 模块 | 核心能力 | 典型场景 |
|---|---|---|
| OAuth2.0授权 | 用户身份认证、获取OpenID/UnionID | 网页登录、免密授权、用户画像 |
| 消息管理 | 接收/回复文本/图片/图文/菜单事件 | 客服消息、模板消息、被动回复 |
| 自定义菜单 | 创建/查询/删除菜单,支持点击/扫码/跳转 | 业务引导、功能入口、H5页面跳转 |
| 素材管理 | 临时/永久素材上传、下载、管理 | 图文消息封面、客服头像、永久图文 |
| 用户管理 | 用户信息获取、标签管理、黑名单操作 | 分组运营、精准推送、用户召回 |
| 微信支付 | 公众号支付、Native支付、H5支付 | 商品下单、会员续费、打赏收款 |
| JSSDK配置 | 调用相机、地理位置、分享等原生能力 | 扫码点餐、地图导航、朋友圈分享 |
| 模板消息 | 订阅消息推送(2023年起全面替代模板消息) | 订单通知、服务提醒、活动提醒 |
| 网页授权 | 获取用户基础信息(snsapi_base/snsapi_userinfo) | 一键登录、用户信息补全 |
| 小程序云开发 | 云数据库、云函数、云存储集成 | 快速搭建后端服务、降低运维成本 |
| 企业微信API | 通讯录管理、会话存档、客户联系 | 内部系统集成、销售管理、客服系统 |
| 企业微信微应用 | 消息推送、菜单配置、OAuth2.0集成 | OA审批、考勤打卡、移动门户 |
com.xservx.wx
├── config/
│ ├── WxMpConfig.java # 微信配置类
│ └── WxPayConfig.java # 支付配置类
├── controller/
│ ├── WxMpController.java # 公众号消息入口
│ ├── WxPayController.java # 支付回调处理
│ └── WxJsController.java # JSSDK签名接口
├── service/
│ ├── impl/
│ │ ├── WxMpServiceImpl.java # 消息处理逻辑
│ │ ├── WxPayServiceImpl.java# 支付业务逻辑
│ │ └── WxUserService.java # 用户管理服务
│ └── WxMpService.java
├── util/
│ ├── WxSignUtil.java # JSSDK签名工具
│ ├── WxHttpUtil.java # HTTP请求封装
│ └── WxPayUtil.java # 支付工具类
└── WxMpApplication.java
<dependencies>
<!-- 微信公众号SDK(推荐使用weixin-java-mp)-->
<dependency>
<groupId>com.github.binarywang</groupId>
<artifactId>weixin-java-mp</artifactId>
<version>4.6.0</version>
</dependency>
<!-- 微信支付SDK-->
<dependency>
<groupId>com.github.binarywang</groupId>
<artifactId>weixin-java-pay</artifactId>
<version>4.6.0</version>
</dependency>
<!-- 企业微信SDK-->
<dependency>
<groupId>com.github.binarywang</groupId>
<artifactId>weixin-java-cp</artifactId>
<version>4.6.0</version>
</dependency>
<!-- Spring Boot Web-->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
</dependencies>
wx:
mp:
appId: wx1234567890abcdef
secret: 1234567890abcdef1234567890abcdef
token: xservx_wx_token
aesKey: your_aes_key_32_chars
storage:
type: redis
pay:
mchId: 1900000109
mchKey: 12345678901234567890123456789012
notifyUrl: https://www.xservx.com/pay/notify
掌握以上基础后,即可进入各功能模块的深度开发实践。以下按用户高频需求展开详解。
微信OAuth2.0是网页授权与用户身份识别的基石,支持两种作用域:
用户点击链接进入业务页面,例如:https://www.xservx.com/user/profile?redirect=order
Java后端构造微信授权地址:https://open.weixin.qq.com/connect/oauth2/authorize?appid=APPID&redirect_uri=REDIRECT_URI&response_type=code&scope=SCOPE&state=STATE#wechat_redirect
微信弹出授权页(snsapi_userinfo需用户点击“允许”)
授权后跳转:REDIRECT_URI?code=CODE&state=STATE
用code换取access_token(含OpenID):https://api.weixin.qq.com/sns/oauth2/access_token?appid=APPID&secret=SECRET&code=CODE&grant_type=authorization_code
若scope为snsapi_userinfo,可调用:https://api.weixin.qq.com/sns/userinfo?access_token=ACCESS_TOKEN&openid=OPENID&lang=zh_CN
@GetMapping("/wx/oauth/url")
public ResponseEntity<String> getOAuthUrl(@RequestParam String redirectUrl) {
String encodedRedirect = URLEncoder.encode(redirectUrl, StandardCharsets.UTF_8);
String url = String.format(
"https://open.weixin.qq.com/connect/oauth2/authorize?appid=%s&redirect_uri=%s&response_type=code&scope=snsapi_userinfo&state=XSERVX#wechat_redirect",
wxMpConfig.getAppId(), encodedRedirect
);
return ResponseEntity.ok(url);
}
@GetMapping("/wx/oauth/callback")
public String oauthCallback(@RequestParam String code, @RequestParam(required = false) String state) {
try {
WxMpOAuth2AccessToken token = wxMpService.oauth2getAccessToken(code);
String openId = token.getOpenId();
// 若需用户信息
if (token.getScope().equals("snsapi_userinfo")) {
WxMpUser user = wxMpService.oauth2getUserInfo(token, null);
// 保存用户信息:user.getNickname(), user.getHeadImgUrl()等
}
// 业务逻辑:生成本地token、重定向等
return "redirect:/user/profile?openId=" + openId;
} catch (WxErrorException e) {
log.error("OAuth2授权失败", e);
return "redirect:/error?msg=授权失败";
}
}
UnionID仅在满足以下任一条件时返回:
① 小程序调用 wx.getUserInfo() 获取 encryptedData 和 iv
② 后端用 session_key 解密:
```java
WxMaJscode2SessionResult result = wxMaService.jsCode2SessionInfo(code);
String sessionKey = result.getSessionKey();
String decryptData = WxMaCryptUtil.decrypt(sessionKey, encryptedData, iv);
// decryptData 包含 unionId 字段
```
③ 同一用户在公众号端调用OAuth2时,若满足条件,access_token接口返回数据中含unionid字段
微信消息分为两类:
文本/图片/语音/事件等消息推送至公众号服务器(POST请求)
校验微信签名(signature)、时间戳(timestamp)、随机数(nonce)
XML转对象(推荐使用WxMpXmlMessage)
根据消息类型(text/image/event)执行不同逻辑
构造XML响应(文本/图文/音乐等)
| 消息类型 | 请求XML字段 | 响应XML字段 | 适用场景 |
|---|---|---|---|
| 文本消息 | Content, MsgId | Content | 关键词回复、智能客服 |
| 图片消息 | PicUrl, MediaId, MsgId | MediaId | 图片识别、素材回复 |
| 语音消息 | MediaId, Format, Recognition, MsgId | MediaId | 语音识别、语音回复 |
| 视频消息 | MediaId, ThumbMediaId, MsgId | MediaId, ThumbMediaId | 视频点播、教学视频 |
| 链接消息 | Title, Description, Url, MsgId | Title/Description/Url | 网页链接推送 |
| 位置消息 | Location_X, Location_Y, Scale, Label, MsgId | Location_X, Location_Y, Scale, Label | 附近门店、地理围栏 |
| 事件消息 | Event, EventKey, Ticket | 根据事件类型响应 | 菜单点击、扫码、关注/取关 |
@PostMapping("/wx/mp/callback")
public String handleWxMessage(@RequestBody String requestBody,
@RequestParam("signature") String signature,
@RequestParam("timestamp") String timestamp,
@RequestParam("nonce") String nonce,
@RequestParam("encrypt_type") String encryptType,
@RequestParam("msg_signature") String msgSignature) {
try {
// 验证签名
if (!wxMpService.checkSignature(timestamp, nonce, signature)) {
return "签名验证失败";
}
// 解析消息
WxMpXmlMessage inMessage = WxMpXmlMessage.fromXml(requestBody);
// 处理文本消息
if ("text".equals(inMessage.getMsgType())) {
String content = inMessage.getContent().trim();
WxMpXmlOutMessage outMessage = null;
if ("天气".equals(content)) {
// 查询天气API并构造图文消息
outMessage = WxMpXmlOutMessage.TEXT()
.toUser(inMessage.getFromUser())
.fromUser(inMessage.getToUser())
.content("当前气温25℃,晴朗,适合出行")
.build();
} else if ("菜单".equals(content)) {
outMessage = WxMpXmlOutMessage.TEXT()
.toUser(inMessage.getFromUser())
.fromUser(inMessage.getToUser())
.content("请回复:1-订单查询 2-客服联系 3-最新活动")
.build();
}
return outMessage.toXml();
}
// 默认回复
return WxMpXmlOutMessage.TEXT()
.toUser(inMessage.getFromUser())
.fromUser(inMessage.getToUser())
.content("感谢关注!回复【帮助】查看功能列表")
.build()
.toXml();
} catch (Exception e) {
log.error("消息处理异常", e);
return "error";
}
}
需用户48小时内与公众号互动过(发送消息/点击菜单/扫码/支付),才可推送客服消息。
发送文本客服消息:
WxMpKefuMessage message = new WxMpKefuMessage();
message.setToUser(openId);
message.setMsgType(WxConsts.KefuMsgType.TEXT);
message.setContent("您的订单已发货,快递单号:YT123456789CN");
wxMpService.getKefuService().sendKefuMessage(message);
用户需手动订阅,每条消息可发送一次,无频率限制,但需在模板库选择。
Java发送代码:
WxMpSubscribeMessage subscribeMessage = new WxMpSubscribeMessage();
subscribeMessage.setToUser(openId);
subscribeMessage.setTemplateId("template_id_from_mp");
Map data = new HashMap<>();
data.put("thing1", new WxMpSubscribeMessage.Data("订单状态更新"));
data.put("date2", new WxMpSubscribeMessage.Data(LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm"))));
subscribeMessage.setData(data);
wxMpService.getSubscribeService().sendSubscribeMessage(subscribeMessage);
素材分为两类:
上传图片素材(用于客服消息):
File file = new File("/path/to/image.jpg");
WxMpMediaUploadResult result = wxMpService.getMediaService()
.uploadMedia("image", "jpg", new FileInputStream(file));
String mediaId = result.getMediaId(); // 有效期3天
① 先上传封面图片,获取media_id
② 构造图文消息:
WxMpNewsMessage.Article article = new WxMpNewsMessage.Article();
article.setTitle("Java微信开发实战");
article.setThumbMediaId("thumb_media_id_from_upload");
article.setAuthor("xservx团队");
article.setDigest("系统讲解公众号开发核心技术");
article.setShowCoverPic(true);
article.setContent("正文内容...");
article.setContentSourceUrl("https://www.xservx.com/detail");
List articles = Arrays.asList(article);
WxMpMaterialUploadResult result = wxMpService.getMaterialService()
.materialNewsUpload(articles, true); // true表示永久图文
用户数据是公众号核心资产,需建立完整的用户标签体系。
// 创建标签
WxMpUserTag tag = new WxMpUserTag();
tag.setName("VIP客户");
WxMpUserTag created = wxMpService.getUserTagService().userTagCreate(tag);
Long tagId = created.getId();
// 批量打标签
List openIds = Arrays.asList("OPENID1", "OPENID2");
wxMpService.getUserTagService().userTagging(tagId, openIds);
// 查询用户标签
List userTagList = wxMpService.getUserTagService().userTagList(openId);
// 返回用户所属标签ID列表
通过OAuth2获取用户信息后,应同步至本地数据库:
@Data
@Entity
@Table(name = "wx_user")
public class WxUser {
@Id
private String openId;
private String unionId;
private String nickname;
private String headImgUrl;
private Integer sex; // 1男 2女 0未知
private String province;
private String city;
private String country;
private Set tagIds = new HashSet<>(); // 所属标签ID集合
private LocalDateTime subscribeTime;
private Boolean subscribe; // 是否关注
}
微信支付支持4种模式,Java开发者需重点掌握:
后端调用统一下单API:https://api.mch.weixin.qq.com/pay/unifiedorder
返回预支付交易会话标识
前端调用 wx.chooseWXPay({})
微信异步推送支付结果至notify_url
@PostMapping("/pay/jsapi")
public ResponseEntity<Map<String, Object>> createJsApiOrder(@RequestBody OrderRequest req) {
WxPayUnifiedOrderV3Request orderRequest = new WxPayUnifiedOrderV3Request();
orderRequest.setAppid(wxPayConfig.getAppId());
orderRequest.setMchid(wxPayConfig.getMchId());
orderRequest.setDescription("订单-" + req.getOrderNo());
orderRequest.setOutTradeNo(req.getOrderNo());
WxPayUnifiedOrderV3Request.Amount amount = new WxPayUnifiedOrderV3Request.Amount();
amount.setTotal(req.getAmount()); // 单位:分
orderRequest.setAmount(amount);
WxPayUnifiedOrderV3Request.Payer payer = new WxPayUnifiedOrderV3Request.Payer();
payer.setOpenid(req.getOpenId());
orderRequest.setPayer(payer);
orderRequest.setNotifyUrl(wxPayConfig.getNotifyUrl());
try {
WxPayUnifiedOrderV3Result result = wxPayService.unifiedOrder(orderRequest);
String prepayId = result.getPrepayId();
// 构造JSAPI调起支付参数
Map<String, String> payParams = new HashMap<>();
payParams.put("appId", wxPayConfig.getAppId());
payParams.put("timeStamp", String.valueOf(System.currentTimeMillis() / 1000));
payParams.put("nonceStr", UUID.randomUUID().toString().replace("-", ""));
payParams.put("package", "prepay_id=" + prepayId);
payParams.put("signType", "RSA");
payParams.put("paySign", rsaSign(payParams));
return ResponseEntity.ok(payParams);
} catch (Exception e) {
log.error("统一下单失败", e);
return ResponseEntity.status(500).build();
}
}
function pay(orderNo) {
$.post('/pay/jsapi', { orderNo: orderNo, amount: 100, openId: openid }, function(res) {
wx.chooseWXPay({
timestamp: res.timeStamp,
nonceStr: res.nonceStr,
package: res.package,
signType: res.signType,
paySign: res.paySign,
success: function (res) {
alert('支付成功');
location.href = '/order/success?orderNo=' + orderNo;
},
fail: function (res) {
alert('支付失败: ' + res.errMsg);
}
});
});
}
JSSDK是微信开放的前端JS接口库,支持调用相机、地理位置、分享等30+原生能力。
公众号后台 → 设置 → 公众号设置 → 功能设置 → JS接口安全域名
后端调用:https://api.weixin.qq.com/cgi-bin/ticket/getticket?access_token=ACCESS_TOKEN&type=jsapi
用jsapi_ticket + noncestr + timestamp + url 生成signature
wx.config({ ... })
public static Map<String, String> sign(String jsapiTicket, String url) {
Map<String, String> ret = new HashMap<>();
String nonceStr = UUID.randomUUID().toString();
long timestamp = System.currentTimeMillis() / 1000;
String raw = "jsapi_ticket=" + jsapiTicket +
"&noncestr=" + nonceStr +
"×tamp=" + timestamp +
"&url=" + url;
try {
MessageDigest crypt = MessageDigest.getInstance("SHA-1");
crypt.update(raw.getBytes(StandardCharsets.UTF_8));
String signature = bytesToHex(crypt.digest());
ret.put("url", url);
ret.put("jsapiTicket", jsapiTicket);
ret.put("nonceStr", nonceStr);
ret.put("timestamp", String.valueOf(timestamp));
ret.put("signature", signature);
return ret;
} catch (Exception e) {
throw new RuntimeException(e);
}
}
| 接口 | 功能 | 使用场景 |
|---|---|---|
| wx.scanQRCode | 扫码(支持微信二维码/条形码) | 扫码点餐、商品溯源 |
| wx.getLocation | 获取定位(经纬度) | 附近门店、LBS推送 |
| wx.openLocation | 打开地图查看位置 | 导航至门店 |
| wx.chooseImage | 选择图片(相册/拍照) | 上传头像、图片识别 |
| wx.uploadImage | 上传图片至微信服务器 | 图片素材上传 |
| wx.onMenuShareTimeline | 自定义朋友圈分享内容 | 活动裂变、品牌传播 |
| wx.onMenuShareAppMessage | 自定义好友分享内容 | 商品分享、活动推广 |
小程序虽为前端主导,但后端开发需掌握以下核心:
@PostMapping("/mini/login")
public ResponseEntity<Map<String, Object>> miniLogin(@RequestBody Map<String, String> req) {
String code = req.get("code");
String encryptedData = req.get("encryptedData");
String iv = req.get("iv");
try {
// 1. 换取session_key
WxMaJscode2SessionResult session = wxMaService.jsCode2SessionInfo(code);
String sessionKey = session.getSessionKey();
// 2. 解密用户信息
String userInfoJson = WxMaCryptUtil.decrypt(sessionKey, encryptedData, iv);
WxMaUserInfo userInfo = JSON.parseObject(userInfoJson, WxMaUserInfo.class);
// 3. 生成本地token
String token = UUID.randomUUID().toString();
redisTemplate.opsForValue().set("mini:user:" + token, userInfo.getOpenId(), 2, TimeUnit.HOURS);
Map<String, Object> result = new HashMap<>();
result.put("token", token);
result.put("openId", userInfo.getOpenId());
return ResponseEntity.ok(result);
} catch (Exception e) {
log.error("小程序登录失败", e);
return ResponseEntity.status(500).build();
}
}
若使用云开发,Java可仅负责复杂业务逻辑,基础CRUD由云函数处理:
企业微信是微信生态的B端入口,支持与公众号/小程序互通。
https://qyapi.weixin.qq.com在公众号菜单中跳转企业微信应用:
{
"type": "view",
"name": "员工登录",
"url": "https://work.weixin.qq.com/wwopen/sso/qrConnect?appid= wwce09876543210abc&agentid=1000002&redirect_uri=YOUR_REDIRECT_URL&state=STATE"
}
📌 最新动态:2025年起微信将加强数据安全监管,所有收集用户信息的接口需提供单独授权弹窗。