微信接口开发Java|xservx.com

⚡微信接口开发Java全景概览

微信生态覆盖超13亿月活用户,已成为企业数字化转型的核心入口。作为开发者,掌握微信接口开发Java技术体系,意味着掌握高价值技术能力与商业机会。

本页面系统梳理微信开放平台三大核心场景——公众号(服务号/订阅号)、小程序、企业微信——的接口开发要点,结合Java生态(Spring Boot为主)提供可落地的技术方案。所有内容基于微信官方最新文档(2025年Q1版本),兼顾生产环境稳定性、安全性与可维护性。

〔1〕开发前准备

〔2〕核心接口分类

微信接口按功能划分为12大模块,Java开发者需重点关注:

模块 核心能力 典型场景
OAuth2.0授权 用户身份认证、获取OpenID/UnionID 网页登录、免密授权、用户画像
消息管理 接收/回复文本/图片/图文/菜单事件 客服消息、模板消息、被动回复
自定义菜单 创建/查询/删除菜单,支持点击/扫码/跳转 业务引导、功能入口、H5页面跳转
素材管理 临时/永久素材上传、下载、管理 图文消息封面、客服头像、永久图文
用户管理 用户信息获取、标签管理、黑名单操作 分组运营、精准推送、用户召回
微信支付 公众号支付、Native支付、H5支付 商品下单、会员续费、打赏收款
JSSDK配置 调用相机、地理位置、分享等原生能力 扫码点餐、地图导航、朋友圈分享
模板消息 订阅消息推送(2023年起全面替代模板消息) 订单通知、服务提醒、活动提醒
网页授权 获取用户基础信息(snsapi_base/snsapi_userinfo) 一键登录、用户信息补全
小程序云开发 云数据库、云函数、云存储集成 快速搭建后端服务、降低运维成本
企业微信API 通讯录管理、会话存档、客户联系 内部系统集成、销售管理、客服系统
企业微信微应用 消息推送、菜单配置、OAuth2.0集成 OA审批、考勤打卡、移动门户

〔3〕Java技术栈推荐

示例:Spring Boot项目基础结构

src/main/java/com/xservx/wx
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

关键依赖(Maven)

pom.xml
<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>

配置示例(application.yml)

application.yml
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授权:用户身份认证核心路径

微信OAuth2.0是网页授权与用户身份识别的基石,支持两种作用域:

〔1〕授权流程详解

① 用户访问网页

用户点击链接进入业务页面,例如:
https://www.xservx.com/user/profile?redirect=order

② 后端生成授权URL

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需用户点击“允许”)

④ 回调携带code

授权后跳转:
REDIRECT_URI?code=CODE&state=STATE

⑤ 后端换取access_token

用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

Java代码示例(Spring Boot)

WxJsController.java
@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=授权失败";
    }
}

⚠️注意事项

〔2〕UnionID获取条件

UnionID仅在满足以下任一条件时返回:

  1. 用户关注了公众号,且公众号与小程序同属一个主体
  2. 用户在小程序授权后,访问了绑定同一主体的企业微信应用
  3. 用户在企业微信应用中授权后,关注了同主体公众号

UnionID获取流程

点击展开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字段

⚡消息管理:被动回复与主动推送双通道

微信消息分为两类:

〔1〕被动回复流程

① 用户发送消息

文本/图片/语音/事件等消息推送至公众号服务器(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 根据事件类型响应 菜单点击、扫码、关注/取关

事件消息详解

点击展开事件类型说明
  • subscribe:关注公众号(含带参数二维码扫码关注)
  • unsubscribe:取消关注
  • SCAN:已关注用户扫码(携带scene_id)
  • CLICK:菜单按钮点击(type=click)
  • VIEW:菜单链接跳转(type=view)
  • LOCATION:上报地理位置(需开启自动推送)
  • MASSSENDJOBFINISH:群发消息完成

Java代码示例:处理文本消息

WxMpController.java
@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";
    }
}

〔2〕主动推送:客服消息与订阅消息

客服消息(72小时内有效)

需用户48小时内与公众号互动过(发送消息/点击菜单/扫码/支付),才可推送客服消息。

点击展开客服消息发送示例

发送文本客服消息:

WxMpKefuMessage message = new WxMpKefuMessage();
message.setToUser(openId);
message.setMsgType(WxConsts.KefuMsgType.TEXT);
message.setContent("您的订单已发货,快递单号:YT123456789CN");
wxMpService.getKefuService().sendKefuMessage(message);

订阅消息(2023年起强制使用)

用户需手动订阅,每条消息可发送一次,无频率限制,但需在模板库选择。

点击展开订阅消息流程
  1. 在公众号后台「订阅消息」中添加模板(如:订单状态通知、服务提醒)
  2. 前端调用 wx.requestSubscribeMessage() 弹出订阅框
  3. 用户点击“允许”后,后端用 template_id + touser + data 发送

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

⚡素材管理:图文/图片/语音的全生命周期

素材分为两类:

〔1〕上传临时素材

点击展开Java上传代码

上传图片素材(用于客服消息):

File file = new File("/path/to/image.jpg");
WxMpMediaUploadResult result = wxMpService.getMediaService()
    .uploadMedia("image", "jpg", new FileInputStream(file));
String mediaId = result.getMediaId(); // 有效期3天

〔2〕上传永久图文素材

点击展开永久图文上传示例

① 先上传封面图片,获取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表示永久图文

〔3〕素材管理最佳实践

⚠️ 注意:上传永久素材有配额限制(图文消息3000条,其他素材100万条/月),需合理规划。

⚡用户管理:分层运营与精准触达

用户数据是公众号核心资产,需建立完整的用户标签体系。

〔1〕用户标签管理

Java操作标签示例

WxUserService.java
// 创建标签
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列表

〔2〕用户信息同步

通过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; // 是否关注
}

〔3〕黑名单与取消关注处理

💡 数据价值:用户标签可用于:
• 精准推送:仅向“高活跃用户”发送活动通知
• A/B测试:不同标签组展示不同菜单
• 用户画像:结合CRM系统做分层运营

⚡微信支付:安全可靠的交易闭环

微信支付支持4种模式,Java开发者需重点掌握:

〔1〕公众号支付流程

① 下单请求

后端调用统一下单API:
https://api.mch.weixin.qq.com/pay/unifiedorder

② 返回prepay_id

返回预支付交易会话标识

③ JSAPI调起支付

前端调用 wx.chooseWXPay({})

④ 支付结果通知

微信异步推送支付结果至notify_url

Java统一下单代码

WxPayController.java
@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();
    }
}

前端调用示例(微信JSSDK)

pay.js
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);
            }
        });
    });
}

〔2〕支付安全要点

⚠️ 重要:微信支付需通过微信支付商户平台申请,企业资质审核严格。个人开发者无法申请。

⚡JSSDK:调用微信原生能力

JSSDK是微信开放的前端JS接口库,支持调用相机、地理位置、分享等30+原生能力。

〔1〕配置流程

① 绑定域名

公众号后台 → 设置 → 公众号设置 → 功能设置 → JS接口安全域名

② 获取jsapi_ticket

后端调用:
https://api.weixin.qq.com/cgi-bin/ticket/getticket?access_token=ACCESS_TOKEN&type=jsapi

③ 签名生成

用jsapi_ticket + noncestr + timestamp + url 生成signature

④ 前端注入配置

wx.config({ ... })

Java签名生成代码

WxSignUtil.java
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);
    }
}

常用JSSDK接口

接口 功能 使用场景
wx.scanQRCode 扫码(支持微信二维码/条形码) 扫码点餐、商品溯源
wx.getLocation 获取定位(经纬度) 附近门店、LBS推送
wx.openLocation 打开地图查看位置 导航至门店
wx.chooseImage 选择图片(相册/拍照) 上传头像、图片识别
wx.uploadImage 上传图片至微信服务器 图片素材上传
wx.onMenuShareTimeline 自定义朋友圈分享内容 活动裂变、品牌传播
wx.onMenuShareAppMessage 自定义好友分享内容 商品分享、活动推广

安全注意事项

⚡小程序:Java后端开发要点

小程序虽为前端主导,但后端开发需掌握以下核心:

〔1〕核心接口差异

小程序登录Java处理

MiniProgramLoginController.java
@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();
    }
}

〔2〕小程序云开发(可选)

若使用云开发,Java可仅负责复杂业务逻辑,基础CRUD由云函数处理:

💡 混合开发建议:高并发业务(如秒杀)用Java处理,基础数据管理用云开发,实现降本增效。

⚡企业微信:企业级协同办公

企业微信是微信生态的B端入口,支持与公众号/小程序互通。

〔1〕核心能力

企业微信Java SDK特性

点击展开企业微信开发要点
  • 企业ID(corpid)替代AppID
  • 应用Secret(agentSecret)替代AppSecret
  • 用户唯一标识为userid(非OpenID)
  • 支持OAuth2.0、JSSDK,但接口域名不同:
    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"
}
💡 商业价值:企业微信可打通C端用户与B端员工,实现:
• 客户 -> 员工 -> 企业 的数据闭环
• 转化率提升30%+(行业实测数据)

〔FAQ〕网友们还关心

开发常见问题
性能优化
安全合规

① 开发常见问题

② 性能优化建议

③ 安全与合规

📌 最新动态:2025年起微信将加强数据安全监管,所有收集用户信息的接口需提供单独授权弹窗。