Java调用微信手机号接口时提示“invalid code”错误原因？

Question

Java调用微信手机号接口（`https://api.weixin.qq.com/wxa/business/getuserphonenumber`）返回 `{"errcode":40029,"errmsg":"invalid code"}`，核心原因在于：**前端传入的 `code` 无效或已失效**。该 `code` 并非登录接口（`jscode2session`）返回的 `code`，而是需通过微信原生组件 `<button>` 触发后，在 `bindgetphonenumber` 回调中获取的**临时加密凭证（即 `event.detail.code`）**。常见错误包括：① 前端未正确监听回调或误将 `login` code 当作手机号 code 使用；② `code` 被重复使用（微信限制单次有效且5分钟过期）；③ 后端未及时解密（需用 `access_token` + `code` 调用微信接口，不可自行解析）；④ 小程序未开通“获取手机号”类目或未在后台配置合法域名。务必确认前后端 `code` 传递链路完整、时效合规、来源唯一。</button>

Answer 1

```html

一、现象层：错误响应的表征与初步定位

当Java后端调用微信手机号解密接口 https://api.weixin.qq.com/wxa/business/getuserphonenumber 时，返回 {"errcode":40029,"errmsg":"invalid code"}，这是典型的凭证校验失败信号。该错误码在微信官方文档中明确定义为“code 无效”，但需注意：此处的 code 并非 jscode2session 登录流程中的登录临时凭证（即 js_code），而是由微信原生组件 <button open-type="getPhoneNumber" bindgetphonenumber="onGetPhoneNumber"> 触发后，在 bindgetphonenumber 回调中通过 event.detail.code 获取的一次性加密临时凭证。

二、链路层：前后端协同的完整数据流剖析

以下为合法调用链路的时序逻辑（使用 Mermaid 流程图表示）：

sequenceDiagram
    participant U as 用户
    participant W as 微信客户端（小程序）
    participant F as 前端 JS
    participant B as Java 后端
    participant WX as 微信开放平台 API

    U->>W: 点击「获取手机号」按钮
    W->>F: 触发 bindgetphonenumber 回调
    F->>F: 提取 event.detail.code（唯一、单次、5min 有效期）
    F->>B: POST /api/v1/phonenumber { "code": "xxx", "encryptedData": "yyy", "iv": "zzz" }
    B->>WX: 调用 getuserphonenumber 接口（需 access_token + code + encryptedData + iv）
    WX-->>B: 返回解密后的 {"phoneNumber":"138****1234", "purePhoneNumber":"13812341234", ...}

三、根因层：四大高频失效场景深度归因

• ① 混淆两类 code：将 wx.login() 获取的 js_code 直接用于手机号解密——二者作用域、生命周期、签名机制完全隔离；
• ② 重复/超时使用：同一 code 被多次提交或距生成已超 5 分钟（微信服务端强制拒绝，且不提供过期时间字段）；
• ③ 解密逻辑误判：试图用 AES-128-CBC 自行解密 encryptedData（错误！必须交由微信服务端完成，后端仅传递原始参数）；
• ④ 权限与配置缺失：小程序未在「开发管理 → 接口权限」中开通「获取手机号」类目，或未在「服务器域名」中配置 HTTPS 合法请求域名（含回调域名）。

四、验证层：可落地的诊断清单（Checklist）

检查项	验证方式	预期结果
前端是否监听 bindgetphonenumber	检查 WXML 中 button 是否含 open-type="getPhoneNumber" 及对应 JS 方法	存在且能 console.log(event.detail.code)
code 是否被缓存或复用	后端日志记录每次请求的 code，并比对相邻请求	无重复值，且生成时间戳 ≤ 当前时间 - 300s
access_token 是否有效且为本小程序	调用 https://api.weixin.qq.com/cgi-bin/token 并校验 appid/appsecret	errcode=0，且 token 未过期（2h）

五、实施层：Java 后端关键代码示例（Spring Boot）

// 1. 接收前端传参（务必校验非空 & 长度合理性）
@PostMapping("/phonenumber")
public ResponseEntity<Object> decryptPhone(@RequestBody PhoneDecryptReq req) {
    if (StringUtils.isBlank(req.getCode()) || 
        req.getCode().length() < 20) {
        throw new IllegalArgumentException("Invalid code format");
    }
    // 2. 获取 access_token（建议加本地缓存+自动刷新）
    String accessToken = wechatTokenService.getAccessToken();
    // 3. 构建微信请求体（不可修改字段名，严格大小写）
    Map<String, Object> payload = Map.of(
        "code", req.getCode(),
        "encryptedData", req.getEncryptedData(),
        "iv", req.getIv()
    );
    // 4. 调用微信官方接口（使用 RestTemplate 或 OkHttp）
    String url = "https://api.weixin.qq.com/wxa/business/getuserphonenumber?access_token=" + accessToken;
    String response = restTemplate.postForObject(url, payload, String.class);
    // 5. 解析响应并处理 errcode=0 场景
    return ResponseEntity.ok(response);
}

六、治理层：长效防控机制建议

面向5年以上经验工程师，建议构建三层防护：

1. 前端拦截：封装 getPhoneNumber 调用为 Promise 工厂，自动绑定 timestamp + code 唯一标识，禁止二次触发；
2. 网关层审计：在 API 网关（如 Spring Cloud Gateway）注入 code 使用频次熔断器（如每分钟≤3次/IP）；
3. 后端可观测性：将 code 的生成时间、使用时间、耗时、IP、User-Agent 写入 ELK，建立「code 生命周期看板」。

七、延伸思考：为什么微信坚持服务端解密？

这不仅是安全设计，更是架构权责分离的范式体现：① 避免私钥泄露风险（小程序端无法安全存储解密密钥）；② 统一风控策略（微信可实时拦截异常设备/地域/行为）；③ 支持号码脱敏分级（如运营商归属地、实名状态等扩展字段未来演进）。因此，任何试图绕过微信服务端的「客户端解密方案」均违反平台协议且不可上线。

```