csxj2026/junhong_cmp_fiber

Fork 0

Files

huang bf591095a2 微信相关能力

2026-01-30 17:25:30 +08:00

14 KiB

Raw Blame History

微信集成功能验证指南

本文档提供微信公众号 OAuth 认证和微信支付功能的完整验证流程。

前置准备

1. 微信配置准备

确保已获取以下信息：

公众号配置：

AppID
AppSecret
OAuth 回调域名已配置（在公众号后台）

支付配置：

商户号
APIv3 密钥（32位）
商户证书文件（apiclient_cert.pem）
商户私钥文件（apiclient_key.pem）
证书序列号
支付回调 URL 已配置（在商户平台）

2. 环境准备

# 创建证书目录
mkdir -p /app/certs

# 复制证书文件
cp apiclient_cert.pem /app/certs/
cp apiclient_key.pem /app/certs/

# 设置文件权限
chmod 600 /app/certs/*

# 加载环境变量
source .env.local

3. 启动服务

# 编译并启动
go run cmd/api/main.go

# 或使用 Docker
docker-compose up -d api

配置验证

自动验证脚本

运行配置验证脚本：

# 加载环境变量
source .env.local

# 运行验证脚本
bash scripts/verify-wechat.sh

预期输出（所有检查通过）：

========================================
  微信配置验证脚本
========================================

1. 检查微信公众号配置
----------------------------------------
✓ JUNHONG_WECHAT_OFFICIAL_ACCOUNT_APP_ID
✓ JUNHONG_WECHAT_OFFICIAL_ACCOUNT_APP_SECRET
✓ JUNHONG_WECHAT_OFFICIAL_ACCOUNT_TOKEN
✓ JUNHONG_WECHAT_OFFICIAL_ACCOUNT_AES_KEY
✓ JUNHONG_WECHAT_OFFICIAL_ACCOUNT_OAUTH_REDIRECT_URL

2. 检查微信支付配置
----------------------------------------
✓ JUNHONG_WECHAT_PAYMENT_APP_ID
✓ JUNHONG_WECHAT_PAYMENT_MCH_ID
✓ JUNHONG_WECHAT_PAYMENT_API_V3_KEY
✓ JUNHONG_WECHAT_PAYMENT_CERT_PATH
✓ JUNHONG_WECHAT_PAYMENT_KEY_PATH
✓ JUNHONG_WECHAT_PAYMENT_SERIAL_NO
✓ JUNHONG_WECHAT_PAYMENT_NOTIFY_URL

3. 检查证书文件
----------------------------------------
✓ 文件存在: /app/certs/apiclient_cert.pem
✓ 文件存在: /app/certs/apiclient_key.pem

4. 验证配置格式
----------------------------------------
✓ 支付回调 URL 使用 HTTPS

5. 检查证书有效性（可选）
----------------------------------------
✓ 证书有效期至: Jan 30 12:00:00 2026 GMT
  ✓ 证书序列号匹配

========================================
  验证结果
========================================
错误: 0
警告: 0

✅ 配置验证通过，所有配置正确

查看服务启动日志

# 查看实时日志
tail -f logs/app.log

# 或使用 Docker
docker logs -f junhong-api

预期日志（成功初始化）：

{
  "level": "info",
  "ts": "2025-01-30T12:00:00.000+0800",
  "msg": "微信公众号服务初始化成功"
}
{
  "level": "info",
  "ts": "2025-01-30T12:00:00.001+0800",
  "msg": "微信支付服务初始化成功"
}
{
  "level": "info",
  "ts": "2025-01-30T12:00:00.002+0800",
  "msg": "服务启动成功",
  "address": ":3000"
}

错误日志（配置问题）：

{
  "level": "fatal",
  "ts": "2025-01-30T12:00:00.000+0800",
  "msg": "微信配置不完整或无效",
  "error": "证书文件不存在: /app/certs/apiclient_cert.pem"
}

功能测试

1. 微信 OAuth 登录

前端测试步骤

步骤 1：构造授权 URL

const appId = 'wxabcdef1234567890';
const redirectUri = encodeURIComponent('https://your-domain.com/wechat-callback');
const state = Math.random().toString(36).substring(7);

const authUrl = `https://open.weixin.qq.com/connect/oauth2/authorize?appid=${appId}&redirect_uri=${redirectUri}&response_type=code&scope=snsapi_userinfo&state=${state}#wechat_redirect`;

// 跳转到微信授权页面
window.location.href = authUrl;

步骤 2：处理回调

在回调页面（https://your-domain.com/wechat-callback）：

// 获取 URL 参数中的 code
const urlParams = new URLSearchParams(window.location.search);
const code = urlParams.get('code');
const state = urlParams.get('state');

if (!code) {
  alert('授权失败：未获取到授权码');
  return;
}

// 调用后端 OAuth 登录接口
fetch('https://api.your-domain.com/api/c/v1/wechat/auth', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ code })
})
.then(res => res.json())
.then(data => {
  if (data.code === 0) {
    console.log('登录成功', data.data);
    localStorage.setItem('token', data.data.token);
    // 跳转到主页
    window.location.href = '/';
  } else {
    alert(`登录失败: ${data.msg}`);
  }
})
.catch(err => {
  console.error('请求失败', err);
  alert('登录失败，请重试');
});

后端日志验证

# 查看 OAuth 请求日志
tail -f logs/app.log | grep -i oauth

成功日志：

{
  "level": "debug",
  "ts": "2025-01-30T12:00:00.000+0800",
  "msg": "微信 OAuth 授权成功",
  "open_id": "o6_bmjrPTlm6_2sgVt7hMZOPfL2M",
  "union_id": "oGfRjwX..."
}
{
  "level": "info",
  "ts": "2025-01-30T12:00:00.001+0800",
  "msg": "个人客户创建成功",
  "customer_id": 123
}

失败日志：

{
  "level": "error",
  "ts": "2025-01-30T12:00:00.000+0800",
  "msg": "微信 OAuth 授权失败",
  "code": "071abc123...",
  "error": "invalid code"
}

使用 curl 测试

# 替换为真实的授权码（5分钟有效）
CODE="071abc123456789def"

curl -X POST http://localhost:3000/api/c/v1/wechat/auth \
  -H "Content-Type: application/json" \
  -d "{\"code\":\"$CODE\"}"

成功响应：

{
  "code": 0,
  "msg": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "customer_id": 123,
    "phone": "",
    "nickname": "微信用户",
    "is_new_user": true
  },
  "timestamp": "2025-01-30T12:00:00+08:00"
}

2. 微信账号绑定

前提条件

已有个人客户账号
已获取 JWT Token

测试步骤

# 替换为真实的 Token 和授权码
TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
CODE="071abc123456789def"

curl -X POST http://localhost:3000/api/c/v1/bind-wechat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"code\":\"$CODE\"}"

成功响应：

{
  "code": 0,
  "msg": "绑定成功",
  "timestamp": "2025-01-30T12:00:00+08:00"
}

失败响应（微信号已被绑定）：

{
  "code": 1020,
  "msg": "该微信号已被其他账号绑定",
  "timestamp": "2025-01-30T12:00:00+08:00"
}

3. 微信 JSAPI 支付

前提条件

已创建订单（状态为"待支付"）
在微信内网页中调用
已获取用户 OpenID

测试步骤

步骤 1：创建支付订单

# 替换为真实的 Token、订单ID 和 OpenID
H5_TOKEN="your_h5_token_here"
ORDER_ID=1
OPEN_ID="o6_bmjrPTlm6_2sgVt7hMZOPfL2M"

curl -X POST "http://localhost:3000/api/h5/orders/$ORDER_ID/wechat-pay/jsapi" \
  -H "Authorization: Bearer $H5_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"open_id\":\"$OPEN_ID\"}"

成功响应：

{
  "code": 0,
  "msg": "支付订单创建成功",
  "data": {
    "prepay_id": "wx30123456789012345678901234567890",
    "pay_config": {
      "appId": "wxabcdef1234567890",
      "timeStamp": "1706606400",
      "nonceStr": "5K8264ILTKCH16CQ2502SI8ZNMTM67VS",
      "package": "prepay_id=wx30123456789012345678901234567890",
      "signType": "RSA",
      "paySign": "oR9d8PuhnIc+YZ8cBHFCwfgpaK9gd..."
    }
  },
  "timestamp": "2025-01-30T12:00:00+08:00"
}

步骤 2：前端唤起支付

// 获取支付配置后，调用微信 JSAPI
wx.chooseWXPay({
  ...payConfig,
  success: function(res) {
    console.log('支付成功', res);
    alert('支付成功');
    // 跳转到订单详情页
    window.location.href = `/orders/${orderId}`;
  },
  fail: function(res) {
    console.error('支付失败', res);
    alert('支付失败：' + res.err_msg);
  }
});

后端日志验证

# 查看支付请求日志
tail -f logs/app.log | grep -i jsapi

成功日志：

{
  "level": "info",
  "ts": "2025-01-30T12:00:00.000+0800",
  "msg": "创建 JSAPI 支付订单成功",
  "order_no": "ORDER_20250130_001",
  "prepay_id": "wx30123456789012345678901234567890"
}

4. 微信 H5 支付

前提条件

已创建订单（状态为"待支付"）
在浏览器中调用（微信外）

测试步骤

步骤 1：创建 H5 支付订单

# 替换为真实的 Token 和订单ID
H5_TOKEN="your_h5_token_here"
ORDER_ID=1

curl -X POST "http://localhost:3000/api/h5/orders/$ORDER_ID/wechat-pay/h5" \
  -H "Authorization: Bearer $H5_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scene_info": {
      "payer_client_ip": "123.12.12.123",
      "h5_type": "Wap"
    }
  }'

成功响应：

{
  "code": 0,
  "msg": "H5 支付订单创建成功",
  "data": {
    "h5_url": "https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx30123456789012345678901234567890&package=3583359058"
  },
  "timestamp": "2025-01-30T12:00:00+08:00"
}

步骤 2：前端跳转支付

// 跳转到微信 H5 支付页面
const returnUrl = encodeURIComponent(`https://your-domain.com/orders/${orderId}`);
window.location.href = `${h5Url}&redirect_url=${returnUrl}`;

后端日志验证

# 查看 H5 支付日志
tail -f logs/app.log | grep -i "h5"

成功日志：

{
  "level": "info",
  "ts": "2025-01-30T12:00:00.000+0800",
  "msg": "创建 H5 支付订单成功",
  "order_no": "ORDER_20250130_001",
  "h5_url": "https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?..."
}

5. 支付回调验证

验证方法1：查看日志

支付成功后，微信会自动调用回调接口。查看日志验证：

# 查看支付回调日志
tail -f logs/app.log | grep -i "支付通知"

成功日志：

{
  "level": "info",
  "ts": "2025-01-30T12:00:00.000+0800",
  "msg": "支付通知处理成功",
  "out_trade_no": "ORDER_20250130_001",
  "transaction_id": "4200001234202501301234567890"
}

验证方法2：查询订单状态

# 查询订单状态（使用数据库或 API）
curl -X GET "http://localhost:3000/api/h5/orders/$ORDER_ID" \
  -H "Authorization: Bearer $H5_TOKEN"

预期响应（订单已支付）：

{
  "code": 0,
  "data": {
    "id": 1,
    "order_no": "ORDER_20250130_001",
    "status": "paid",
    "total_amount": 100,
    "paid_amount": 100,
    "paid_at": "2025-01-30T12:00:00+08:00",
    "payment_method": "wechat"
  }
}

验证方法3：使用 Postman 模拟回调

注意：真实环境中由微信服务器调用，本地测试需要跳过签名验证。

# 模拟支付回调（仅测试环境）
curl -X POST http://localhost:3000/api/callback/wechat-pay \
  -H "Content-Type: application/json" \
  -d '{
    "id": "test_id",
    "create_time": "2025-01-30T12:00:00+08:00",
    "resource_type": "encrypt-resource",
    "event_type": "TRANSACTION.SUCCESS",
    "summary": "支付成功",
    "resource": {
      "ciphertext": "...",
      "nonce": "...",
      "associated_data": "..."
    }
  }'

常见问题排查

1. 配置验证失败

问题：脚本报错 "缺失必填配置"

解决方法：

# 检查环境变量是否加载
env | grep JUNHONG_WECHAT

# 重新加载环境变量
source .env.local

# 重新运行验证脚本
bash scripts/verify-wechat.sh

2. 服务启动失败

问题：日志显示 "微信配置不完整或无效"

解决方法：

查看详细错误日志
检查证书文件路径是否正确
验证证书文件权限（600 或 644）
确认 APIv3 密钥长度为 32 位

3. OAuth 授权失败

问题：返回错误码 1044

可能原因：

授权码已过期（5分钟有效期）
授权码已被使用过
AppID 或 AppSecret 配置错误
回调域名未在公众号后台配置

解决方法：

重新发起授权流程获取新 code
检查公众号配置
查看详细日志：tail -f logs/app.log | grep -i oauth

4. 支付订单创建失败

问题：返回错误码 1046

可能原因：

商户号配置错误
证书文件无效或过期
APIv3 密钥错误
订单金额为0或负数

解决方法：

验证商户号和密钥
检查证书有效期：openssl x509 -in /app/certs/apiclient_cert.pem -noout -dates
确认证书序列号匹配
查看详细日志：tail -f logs/app.log | grep -i payment

5. 支付回调签名验证失败

问题：日志显示 "支付回调签名验证失败"

可能原因：

证书配置错误
证书序列号不匹配
证书已过期

解决方法：

重新下载最新的商户证书
更新证书序列号配置
确保证书文件路径正确
验证证书：bash scripts/verify-wechat.sh

6. 启用调试日志

如需查看详细的 HTTP 请求日志：

# 设置环境变量
export JUNHONG_WECHAT_PAYMENT_HTTP_DEBUG=true

# 重启服务
go run cmd/api/main.go

# 查看调试日志
tail -f logs/app.log | grep -i wechat

验证清单

完成以下清单后，微信集成功能验证完成：

配置验证脚本通过（0 错误）
服务启动成功，微信服务初始化日志正常
微信 OAuth 登录成功，返回 Token
微信账号绑定成功
JSAPI 支付订单创建成功，返回支付配置
H5 支付订单创建成功，返回支付 URL
支付回调处理成功，订单状态更新为"已支付"
日志中无错误或警告信息

14 KiB Raw Blame History Unescape Escape

微信集成功能验证指南

目录

前置准备

1. 微信配置准备

2. 环境准备

3. 启动服务

配置验证

自动验证脚本

查看服务启动日志

功能测试

1. 微信 OAuth 登录

前端测试步骤

后端日志验证

使用 curl 测试

2. 微信账号绑定

前提条件

测试步骤

3. 微信 JSAPI 支付

前提条件

测试步骤

后端日志验证

4. 微信 H5 支付

前提条件

测试步骤

后端日志验证

5. 支付回调验证

验证方法1：查看日志

验证方法2：查询订单状态

验证方法3：使用 Postman 模拟回调

常见问题排查

1. 配置验证失败

2. 服务启动失败

3. OAuth 授权失败

4. 支付订单创建失败

5. 支付回调签名验证失败

6. 启用调试日志

验证清单

相关文档

14 KiB

Raw Blame History