// 前端：小程序端
wx.login({
  success: (res) => {
    if (res.code) {
      wx.request({
        url: '/api/auth/login',
        method: 'POST',
        data: { code: res.code },
        success: (resp) => {
          // 拿到后端返回的业务 token，存起来后续请求带上
          getApp().globalData.token = resp.data.data;
        }
      });
    }
  }
});

// 后端：封装微信接口调用
@Component
public class WechatApi {

    private final String APP_ID = "wx1234567890abcdef";    // 小程序 appid
    private final String APP_SECRET = "abc123def456";      // 小程序 appsecret，只在后端

    /**
     * 用临时 code 换取 openid 和 session_key。
     * 调用成功时返回 openid 与 session_key；
     * code 无效或过期时 errcode 非 0。
     */
    public Code2SessionResp code2Session(String code) {
        String url = "https://api.weixin.qq.com/sns/jscode2session"
                + "?appid=" + APP_ID
                + "&secret=" + APP_SECRET
                + "&js_code=" + code
                + "&grant_type=authorization_code";

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder(URI.create(url)).GET().build();
        String json;
        try {
            json = client.send(request, HttpResponse.BodyHandlers.ofString()).body();
        } catch (Exception e) {
            throw new BizException("调用微信登录接口失败");
        }

        JSONObject obj = JSON.parseObject(json);
        if (obj.getInteger("errcode") != null && obj.getInteger("errcode") != 0) {
            // 常见 errcode 40029：code 无效；45011：频率限制
            throw new BizException("微信登录失败: " + obj.getString("errmsg"));
        }
        return new Code2SessionResp(obj.getString("openid"), obj.getString("session_key"));
    }
}

@RestController
@RequestMapping("/api/auth")
@RequiredArgsConstructor
public class AuthController {

    private final WechatApi wechatApi;
    private final UserService userService;
    private final TokenService tokenService;

    @PostMapping("/login")
    public Result<String> login(@RequestBody LoginRequest req) {
        // 1. code 换 openid
        Code2SessionResp resp = wechatApi.code2Session(req.getCode());
        // 2. 查库或建号（以 openid 为业务主键）
        User user = userService.findOrCreateByOpenid(resp.getOpenid());
        // 3. 签发业务 token
        return Result.ok(tokenService.generate(user));
    }
}

// 解密微信加密数据：AES-128-CBC
public class WxBizDataCrypt {

    public static String decrypt(String sessionKey, String encryptedData, String iv) throws Exception {
        byte[] keyBytes = Base64.getDecoder().decode(sessionKey);
        byte[] ivBytes = Base64.getDecoder().decode(iv);
        byte[] cipherBytes = Base64.getDecoder().decode(encryptedData);

        Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
        SecretKeySpec keySpec = new SecretKeySpec(keyBytes, "AES");
        cipher.init(Cipher.DECRYPT_MODE, keySpec, new IvParameterSpec(ivBytes));
        String plain = new String(cipher.doFinal(cipherBytes), StandardCharsets.UTF_8);

        // 微信要求末尾带 appid 作完整性校验
        JSONObject obj = JSON.parseObject(plain);
        if (!APP_ID.equals(obj.getString("watermark").getString("appid"))) {
            throw new BizException("数据校验失败");
        }
        return obj.getString("phoneNumber");   // 例如 "13800138000"
    }
}

// 前端：参数由后端返回，原样传给 wx.requestPayment
wx.requestPayment({
  timeStamp: '1743000000',      // 秒级时间戳，字符串
  nonceStr: 'abc123def456',     // 随机字符串
  package: 'prepay_id=wx20260731143000123456789012345678',
  signType: 'RSA',              // APIv3 固定 RSA
  paySign: 'xxx...',            // 二次签名，防篡改的关键
  success: () => { console.log('支付成功'); },
  fail: (err) => { console.log('支付失败', err); }
});

// 发送订阅消息
public void sendSubscribeMsg(String openid, Map<String, Object> data) {
    String url = "https://api.weixin.qq.com/cgi-bin/message/subscribe/send"
            + "?access_token=" + getAccessToken();

    JSONObject body = new JSONObject();
    body.put("touser", openid);
    body.put("template_id", "tpl_456");
    body.put("page", "pages/order/detail");
    body.put("data", new JSONObject()
            .put("thing1", new JSONObject().put("value", "您的订单已发货"))
            .put("time2", new JSONObject().put("value", "2026-07-31 14:30")));

    httpPost(url, body.toString());
}

public String getAccessToken() {
    // Redis 缓存，key = wx:access_token，过期时间略小于 7200 秒
    String cached = redis.get("wx:access_token");
    if (cached != null) {
        return cached;
    }
    String url = "https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential"
            + "&appid=" + APP_ID + "&secret=" + APP_SECRET;
    String token = JSON.parseObject(httpGet(url)).getString("access_token");
    redis.setex("wx:access_token", 7000, token);
    return token;
}

wx.chooseAddress({
  success: (res) => {
    console.log(res.userName, res.telNumber, res.provinceName);
  }
});

<dependencies>
    <!-- Web：写接口必需 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!-- MyBatis Plus：操作数据库 -->
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>mybatis-plus-boot-starter</artifactId>
        <version>3.5.7</version>
    </dependency>
    <!-- MySQL 驱动 -->
    <dependency>
        <groupId>com.mysql</groupId>
        <artifactId>mysql-connector-j</artifactId>
        <scope>runtime</scope>
    </dependency>
    <!-- Redis：令牌、access_token 缓存 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-redis</artifactId>
    </dependency>
    <!-- JSON：解析微信请求/响应 -->
    <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>fastjson2</artifactId>
        <version>2.0.51</version>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

POST
/v3/pay/transactions/jsapi
1743000000
nonce_str
{ "appid": "wx1234567890", "mchid": "1900000109", ... }

Authorization: WECHATPAY2-SHA256-RSA2048 mchid="1900000109",nonce_str="abc123def456",timestamp="1743000000",signature="xxx"

// 签名工具：统一下单签名、二次签名、回调验签共用
@Component
public class WxPaySign {

    /** 商户私钥：PEM 内容从商户平台下载，妥善保管，严禁提交到 git */
    private final PrivateKey merchantPrivateKey;

    /** 平台证书：用于验签微信的回调，微信会定期更换，需留意更新 */
    private final PublicKey platformPublicKey;

    public WxPaySign() throws Exception {
        this.merchantPrivateKey = loadPrivateKey("apiclient_key.pem");
        this.platformPublicKey = loadPublicKey("wechatpay_public_key.pem");
    }

    /** 读取 PEM 文件里的 RSA 私钥 */
    private PrivateKey loadPrivateKey(String pemPath) throws Exception {
        String content = readAll(pemPath)
                .replace("-----BEGIN PRIVATE KEY-----", "")
                .replace("-----END PRIVATE KEY-----", "")
                .replaceAll("\\s", "");
        byte[] der = Base64.getDecoder().decode(content);
        PKCS8EncodedKeySpec spec = new PKCS8EncodedKeySpec(der);
        return KeyFactory.getInstance("RSA").generatePrivate(spec);
    }

    /** 读取 PEM 文件里的平台公钥 */
    private PublicKey loadPublicKey(String pemPath) throws Exception {
        String content = readAll(pemPath)
                .replace("-----BEGIN PUBLIC KEY-----", "")
                .replace("-----END PUBLIC KEY-----", "")
                .replaceAll("\\s", "");
        byte[] der = Base64.getDecoder().decode(content);
        X509EncodedKeySpec spec = new X509EncodedKeySpec(der);
        return KeyFactory.getInstance("RSA").generatePublic(spec);
    }

    /** 构造 APIv3 请求签名串：method + 路径 + 时间戳 + 随机串 + 请求体 */
    public String buildSignMessage(String method, String urlPath, String timestamp,
                                   String nonceStr, String body) {
        return method + "\n" + urlPath + "\n" + timestamp + "\n" + nonceStr + "\n" + body + "\n";
    }

    /** 用商户私钥做 SHA256withRSA 签名，输出 Base64 */
    public String sign(String message) throws Exception {
        Signature signature = Signature.getInstance("SHA256withRSA");
        signature.initSign(merchantPrivateKey);
        signature.update(message.getBytes(StandardCharsets.UTF_8));
        return Base64.getEncoder().encodeToString(signature.sign());
    }

    /** 组装 Authorization Header */
    public String buildAuthorization(String method, String urlPath, String body) throws Exception {
        String timestamp = String.valueOf(System.currentTimeMillis() / 1000);
        String nonceStr = UUID.randomUUID().toString().replace("-", "");
        String message = buildSignMessage(method, urlPath, timestamp, nonceStr, body);
        String signature = sign(message);
        return "WECHATPAY2-SHA256-RSA2048 mchid=\"" + mchid
                + "\",nonce_str=\"" + nonceStr
                + "\",timestamp=\"" + timestamp
                + "\",signature=\"" + signature + "\"";
    }
}

{
  "appid": "wx1234567890",
  "mchid": "1900000109",
  "description": "测试商品",
  "out_trade_no": "ORDER_20260731_143000_12345",
  "notify_url": "https://abc.ngrok.io/api/pay/callback",
  "amount": {
    "total": 9999,
    "currency": "CNY"
  },
  "payer": {
    "openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o"
  }
}

// 统一下单
public String createOrder(Order order, String openid) throws Exception {
    String urlPath = "/v3/pay/transactions/jsapi";
    String body = buildJsapiBody(order, openid);   // 组上表 JSON

    // 1. 构造签名 Header
    String authorization = wxPaySign.buildAuthorization("POST", urlPath, body);

    // 2. 发送请求
    HttpClient client = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.mch.weixin.qq.com" + urlPath))
            .header("Authorization", authorization)
            .header("Content-Type", "application/json")
            .header("Accept", "application/json")
            .header("Wechatpay-Serial", platformCertSerialNo)  // 平台证书序列号
            .POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8))
            .build();
    HttpResponse<String> resp = client.send(request, HttpResponse.BodyHandlers.ofString());

    // 3. 非 2xx 说明下单失败，解析错误码
    if (resp.statusCode() != 200) {
        JSONObject err = JSON.parseObject(resp.body());
        // 常见：ORDER_PAID（订单已支付）、PARAM_ERROR、NO_AUTH（无权限）
        throw new BizException("下单失败: " + err.getString("message"));
    }

    // 4. 响应里只有两个关键字段：prepay_id 和 trade_type
    JSONObject respJson = JSON.parseObject(resp.body());
    return respJson.getString("prepay_id");   // 例如 wx20260731143000123456789012345678
}

appId=wx1234567890
timeStamp=1743000000
nonceStr=abc123def456
package=prepay_id=wx20260731143000123456789012345678

// 二次签名：返回给 wx.requestPayment 的五个参数
public Map<String, String> buildPaySign(String appId, String prepayId) throws Exception {
    String timestamp = String.valueOf(System.currentTimeMillis() / 1000);
    String nonceStr = UUID.randomUUID().toString().replace("-", "").substring(0, 16);
    String packageStr = "prepay_id=" + prepayId;

    // 注意：与下单签名串不同，这里每行是 key=value
    String message = "appId=" + appId + "\n"
            + "timeStamp=" + timestamp + "\n"
            + "nonceStr=" + nonceStr + "\n"
            + "package=" + packageStr + "\n";

    String paySign = wxPaySign.sign(message);

    Map<String, String> params = new LinkedHashMap<>();
    params.put("timeStamp", timestamp);
    params.put("nonceStr", nonceStr);
    params.put("package", packageStr);
    params.put("signType", "RSA");
    params.put("paySign", paySign);
    return params;
}

{
  "timeStamp": "1743000000",
  "nonceStr": "abc123def456",
  "package": "prepay_id=wx20260731143000123456789012345678",
  "signType": "RSA",
  "paySign": "MIIBlQ...Base64 签名结果..."
}

{
  "id": "EVT_123456",
  "create_time": "2026-07-31T14:30:00+08:00",
  "resource_type": "encrypt-resource",
  "event_type": "TRANSACTION.SUCCESS",
  "summary": "支付成功",
  "resource": {
    "original_type": "transaction",
    "algorithm": "AEAD_AES_256_GCM",
    "ciphertext": "加密的支付结果数据...",
    "associated_data": "transaction",
    "nonce": "abc123"
  }
}

{
  "out_trade_no": "ORDER_20260731_123456",
  "transaction_id": "4200001234567890123456789012",
  "trade_type": "JSAPI",
  "trade_state": "SUCCESS",
  "amount": { "total": 9999, "currency": "CNY" },
  "success_time": "2026-07-31T14:30:00+08:00",
  "payer": { "openid": "oUpF8u..." }
}

// 回调处理器：验签 -> 解密 -> 幂等更新
@RestController
@RequestMapping("/api/pay")
@RequiredArgsConstructor
public class PayCallbackController {

    private final WxPaySign wxPaySign;
    private final OrderService orderService;

    @PostMapping("/callback")
    public String callback(@RequestBody String rawBody,
                           @RequestHeader("Wechatpay-Serial") String serial,
                           @RequestHeader("Wechatpay-Signature") String signature,
                           @RequestHeader("Wechatpay-Timestamp") String timestamp,
                           @RequestHeader("Wechatpay-Nonce") String nonce) {

        // 1. 验签：用微信平台公钥校验签名，防伪造
        //    消息串格式：timestamp\nnonce\nrawBody\n
        String message = timestamp + "\n" + nonce + "\n" + rawBody + "\n";
        boolean valid = wxPaySign.verifyPlatform(message, signature);
        if (!valid) {
            log.warn("回调验签失败");
            return failure();  // 返回失败，微信会重试
        }

        // 2. 解密：拿到明文支付结果
        JSONObject resource = JSON.parseObject(rawBody)
                .getJSONObject("resource");
        String ciphertext = resource.getString("ciphertext");
        String associatedData = resource.getString("associated_data");
        String nonceStr = resource.getString("nonce");
        String plain = decryptAesGcm(apiV3Key, ciphertext, associatedData, nonceStr);

        JSONObject data = JSON.parseObject(plain);
        String outTradeNo = data.getString("out_trade_no");
        String transactionId = data.getString("transaction_id");
        String tradeState = data.getString("trade_state");
        Integer totalFee = data.getJSONObject("amount").getInteger("total");

        // 3. 只处理成功态；其他状态直接应答成功（没必要重试）
        if (!"SUCCESS".equals(tradeState)) {
            return success();
        }

        // 4. 幂等更新（核心，见第 4 步）：乐观锁 + 唯一索引
        boolean first = orderService.handlePaid(outTradeNo, transactionId, totalFee);
        if (first) {
            // 5. 业务处理：扣库存、加积分、发订阅消息
            orderService.postPaidBusiness(outTradeNo);
        }
        return success();
    }

    /** 应答成功：HTTP 200 + 特定 body，微信收到后停止重试 */
    private String success() {
        return "{\"code\":\"SUCCESS\",\"message\":\"成功\"}";
    }

    /** 应答失败：返回非 2xx，微信按频率递增重试（最多 15 次） */
    private String failure() {
        throw new BizException("处理失败");
    }
}

// AES-256-GCM 解密：APIv3 回调数据专用
private String decryptAesGcm(String apiV3Key, String ciphertext,
                             String associatedData, String nonce) throws Exception {
    byte[] key = apiV3Key.getBytes(StandardCharsets.UTF_8);  // 32 位密钥
    byte[] cipherBytes = Base64.getDecoder().decode(ciphertext);

    Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
    SecretKeySpec keySpec = new SecretKeySpec(key, "AES");
    GCMParameterSpec spec = new GCMParameterSpec(128,
            nonce.getBytes(StandardCharsets.UTF_8));
    cipher.init(Cipher.DECRYPT_MODE, keySpec, spec);
    if (associatedData != null && !associatedData.isEmpty()) {
        cipher.updateAAD(associatedData.getBytes(StandardCharsets.UTF_8));
    }
    return new String(cipher.doFinal(cipherBytes), StandardCharsets.UTF_8);
}

// 分布式锁：Redis SETNX + 过期时间
String lockKey = "pay:lock:" + outTradeNo;
Boolean locked = stringRedisTemplate.opsForValue()
        .setIfAbsent(lockKey, "1", Duration.ofSeconds(30));
if (Boolean.TRUE.equals(locked)) {
    try {
        doPay();
    } finally {
        stringRedisTemplate.delete(lockKey);   // 记得释放
    }
} else {
    throw new BizException("订单正在处理中，请勿重复提交");
}

CREATE UNIQUE INDEX uk_pay_record_out_trade_no
    ON pay_record (out_trade_no);

try {
    payRecordMapper.insert(record);   // 主键冲突会抛 DuplicateKeyException
    doPay();
} catch (DuplicateKeyException e) {
    log.info("流水已存在，重复回调，忽略处理");
    return "已处理";
}

-- 乐观锁：只有状态还是 PENDING 时才能更新为 PAID
-- 影响行数 = 1 说明这次更新生效；= 0 说明订单已是其他状态，重复回调
UPDATE orders
SET status = 'PAID',
    pay_time = NOW(),
    transaction_id = '4200001234567890123456789012'
WHERE out_trade_no = 'ORDER_20260731_123456'
  AND status = 'PENDING';

// MyBatis：乐观锁更新，返回影响行数
int rows = orderMapper.updateStatusToPaid(outTradeNo, transactionId);
if (rows == 1) {
    // 第一次处理：更新成功，可以放心做后续业务
    doBusiness();
    log.info("订单 {} 首次处理为已支付", outTradeNo);
} else {
    // 重复回调：订单已是 PAID，直接应答成功，无副作用
    log.warn("订单 {} 已处理，重复回调，忽略", outTradeNo);
    return "SUCCESS";
}

<update id="updateStatusToPaid">
    UPDATE orders
    SET status = 'PAID',
        pay_time = NOW(),
        transaction_id = #{transactionId}
    WHERE out_trade_no = #{outTradeNo}
      AND status = 'PENDING'
</update>

// 下单时：生成一次性令牌
String token = UUID.randomUUID().toString();
stringRedisTemplate.opsForValue()
        .set("pay:token:" + token, outTradeNo, Duration.ofMinutes(5));

// 支付时：删除令牌，删成功才放行
Long deleted = stringRedisTemplate.opsForValue()
        .getOperations().execute((RedisCallback<Long>) conn ->
                conn.del(("pay:token:" + token).getBytes()));
if (deleted != null && deleted == 1) {
    doPay();
} else {
    throw new BizException("请勿重复支付");
}

// 前端：按钮防抖
pay() {
  if (this.paying) return;      // 正在支付，直接忽略
  this.paying = true;
  wx.showLoading({ title: '支付中' });
  wx.requestPayment({
    ...this.payParams,
    complete: () => {
      this.paying = false;
      wx.hideLoading();
    }
  });
}

log.info("收到支付回调: outTradeNo={}, transactionId={}, totalFee={}",
        outTradeNo, transactionId, totalFee);

curl -X POST http://localhost:8080/api/pay/callback \
  -H "Content-Type: application/json" \
  -d '{"out_trade_no":"ORDER_20260731_123456","transaction_id":"4200001234567890123456789012","total_fee":9999}'

@Test
void testSignAndVerify() {
    // 用固定私钥签名，再验签，应通过
}

@Test
void testIdempotency() {
    // 同一订单处理两次，第二次应被乐观锁拦截
}

@Test
void testDuplicateCallback() {
    // 模拟回调连发两次，流水表只有一条记录
}

CREATE TABLE orders (
    id             BIGINT PRIMARY KEY AUTO_INCREMENT,
    out_trade_no   VARCHAR(64)  NOT NULL UNIQUE,
    status         VARCHAR(20)  NOT NULL,     -- PENDING / PAID / CLOSED
    amount         INT          NOT NULL,     -- 单位分
    openid         VARCHAR(64)  NOT NULL,
    created_at     DATETIME     NOT NULL
);

CREATE TABLE pay_records (
    id             BIGINT PRIMARY KEY AUTO_INCREMENT,
    out_trade_no   VARCHAR(64)  NOT NULL UNIQUE,
    transaction_id VARCHAR(64),
    total_fee      INT          NOT NULL,
    pay_time       DATETIME
);