第三方服务集成手册

// ✅ 业务代码只依赖自己的接口，不直接依赖第三方 SDK// providers/sms/provider.jsclass SmsProvider {  async send(phone, templateId, params) { throw new Error('not implemented') }}// providers/sms/aliyun.jsclass AliyunSms extends SmsProvider {  async send(phone, templateId, params) {    const res = await this.client.sendSms({ PhoneNumbers: phone, TemplateCode: templateId, TemplateParam: JSON.stringify(params) })    if (res.Code !== 'OK') throw new SmsError(res.Code, res.Message)    return { requestId: res.RequestId }  }}// providers/sms/index.js —— 统一出口const provider = process.env.SMS_PROVIDER === 'aliyun' ? new AliyunSms() : new MockSms()module.exports = provider

async function callThirdParty({ url, method = 'POST', data, timeout = 5000 }) {  const start = Date.now()  try {    const res = await axios({ url, method, data, timeout })    logger.info({      event: 'thirdparty.call',      host: new URL(url).host,      duration: Date.now() - start,      success: true,    })    return res.data  } catch (err) {    logger.error({      event: 'thirdparty.call.failed',      host: new URL(url).host,      duration: Date.now() - start,      status: err.response?.status,      code: err.response?.data?.code,      message: err.response?.data?.message,    })    throw err  }}

function buildSign(params, secret) {  // 1. 剔除空值与签名字段本身  const entries = Object.entries(params)    .filter(([k, v]) => k !== 'sign' && v !== '' && v !== null && v !== undefined)  // 2. 按 key 的字典序升序排列（注意：大小写敏感）  entries.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))  // 3. 拼接为 k1=v1&k2=v2（不要 URL 编码，除非文档明确要求）  const raw = entries.map(([k, v]) => `${k}=${v}`).join('&')  // 4. 追加密钥并计算摘要  return crypto.createHmac('sha256', secret).update(raw + '&key=' + secret).digest('hex').toUpperCase()}

// 收到回调第一步：验签，通过才处理function verifyCallback(headers, rawBody, publicKey) {  const signature = headers['x-signature']  const timestamp = headers['x-timestamp']  // 防重放：时间戳超出窗口直接拒绝  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {    throw new Error('回调时间戳过期')  }  const expected = crypto    .createVerify('RSA-SHA256')    .update(`${timestamp}\n${rawBody}`)    .verify(publicKey, signature, 'base64')  if (!expected) throw new Error('签名验证失败')}

// Koa：先拿到原始 body 再解析app.use(async (ctx, next) => {  if (ctx.path.startsWith('/callback/')) {    ctx.state.rawBody = await getRawBody(ctx.req)    ctx.request.body = JSON.parse(ctx.state.rawBody)  }  await next()})

// 定时任务：补偿查询长时间未收到回调的订单cron.schedule('*/5 * * * *', async () => {  const stuck = await orderRepo.find({    status: 'pending',    createdAt: { $lt: new Date(Date.now() - 5 * 60 * 1000) },   // 5 分钟前创建    checkedCount: { $lt: 10 },                                  // 最多查 10 次  })  for (const order of stuck) {    const remote = await payProvider.query(order.orderNo)    if (remote.status === 'paid') {      await orderService.markPaid(order.orderNo, remote.transactionId, remote.amount)    }    await orderRepo.increment(order.id, 'checkedCount', 1)  }})

const PROVIDER_ERROR_MAP = {  'INSUFFICIENT_BALANCE': { code: 30001, message: '账户余额不足', retryable: false },  'CARD_EXPIRED':         { code: 30002, message: '银行卡已过期', retryable: false },  'SYSTEM_ERROR':         { code: 30003, message: '支付通道繁忙，请稍后重试', retryable: true },  'SIGN_ERROR':           { code: 30004, message: '签名校验失败', retryable: false, alert: true },}function mapError(providerCode) {  return PROVIDER_ERROR_MAP[providerCode] || {    code: 30099,    message: '服务暂时不可用',    retryable: false,    alert: true,                  // 未知错误要告警  }}

// 每日对账示例async function dailyReconcile(date) {  const remote = await payProvider.downloadBill(date)      // 对方账单  const local = await paymentRepo.findByDate(date)         // 本地流水  const remoteMap = new Map(remote.map((r) => [r.orderNo, r]))  const diffs = []  for (const l of local) {    const r = remoteMap.get(l.orderNo)    if (!r) diffs.push({ type: 'local_only', orderNo: l.orderNo, amount: l.amount })    else if (r.amount !== l.amount) diffs.push({ type: 'amount_mismatch', orderNo: l.orderNo, local: l.amount, remote: r.amount })    remoteMap.delete(l.orderNo)  }  for (const [orderNo, r] of remoteMap) {    diffs.push({ type: 'remote_only', orderNo, amount: r.amount })  }  if (diffs.length) {    logger.error({ event: 'reconcile.mismatch', date, count: diffs.length, diffs })    await alert.notify(`对账差异 ${diffs.length} 笔，日期 ${date}`)  }}

const REQUIRED_KEYS = ['PAY_APP_ID', 'PAY_PRIVATE_KEY', 'PAY_NOTIFY_URL']function validateConfig() {  const missing = REQUIRED_KEYS.filter((k) => !process.env[k])  if (missing.length) throw new Error(`缺少配置: ${missing.join(', ')}`)  if (process.env.NODE_ENV === 'production') {    // 生产环境禁止指向沙箱域名    if (process.env.PAY_API_HOST.includes('sandbox')) {      throw new Error('生产环境不能使用沙箱地址')    }  }}

logger.info({  event: 'pay.create',  orderNo,  userId,  amount,  provider: 'pay',  providerRequestId: res.requestId,   // 找对方排查的凭证  duration,  success: true,})