Skip to content

消息与推送:订阅消息、uni-push 与厂商通道 ​

本篇要点:把一条业务事件分别投递到微信、App 在线通道和厂商通道,并能按漏斗定位「发了但没到」落在哪一段。 前置文章:《支付与交易:多端支付集成与对账》结束时,订单已经变成 paid;这一章解决的是怎么让用户知道这件事,以及为什么日志说成功、用户却没看见。

为什么需要它 ​

2026 年 3 月,一个社区团购项目,日常订单量八千上下。大促当天下午四点,客服群开始刷屏:用户说付完钱没收到自提提醒。

运维拉了发送日志,四千三百二十一条全部是 success。技术负责人在群里说了一句:「发都发出去了,是不是用户没开通知?」这句话听起来合理,但它把一个可以测的问题变成了不可测的猜测。

真实情况是:那批订单里 61% 的用户 App 正在前台,走的是 socket 下行,本来就不会出现通知栏;剩下的 39% 里,有一批客户端标识是三个月前上报的旧值。61% 是设计如此,39% 才是故障,而这两拨人在同一张日志里长得一模一样,都叫 success。

发送成功和用户看见之间,隔着两条通道、四次状态变更和一次设备标识的失效。能调用和能到达是两个不同的工程问题,前者查半小时文档就能过,后者通常要等一次大促之后才被认真对待。

一次业务事件到三种终端的完整链路如图 9-1。看清楚这张图会发现:业务服务只负责产出一份事件,剩下的全是渲染与投递,渠道在这里是数据,不是代码分支。

图 9-1 一次业务事件到三种终端的投递链路

核心概念 ​

通道:触达前提不同,就没有公共抽象 ​

通道(channel)指消息最终走的那条物理路径。本篇要处理三条:微信订阅消息、uni-push 的 socket 下行、手机厂商的推送通道。

能统一的是服务端的事:事件模型、模板与变量、幂等、重试、投递日志、统计口径。不能统一的是触达前提与载荷结构——微信要用户点一次授权换一条额度,App 要装包且没关通知,鸿蒙还要单独声明通知权限。把这三件事强行抽象成一个 send(),第二个渠道进来时就得重构。

额度:是账户,不是开关 ​

订阅消息(one-time subscribe)的额度是用户点一次授权换一条下发次数。很多需求方提「给用户推一条发货提醒」,听上去像打开某个阀门,实际是在一个余额可能为零的账户上做扣减。

反例是把额度当权限:以为用户勾了「总是保持以上选择」就等于永久授权。那句勾选只表示不再弹窗询问,额度仍然是零,发送时返回 43101(用户拒绝接受消息)。

客户端标识:cid 不是设备号 ​

cid(client id)是个推侧的客户端标识,通过 uni.getPushClientId 获取,对应 uni-id-device 表的 push_clientid 字段。重装、清数据、换 SDK 类型都会让它变化;官方文档写明 push_clientid 三个月未登录即失效。所以它不是设备指纹,只是一个需要不断续期的邮寄地址。

反例是把 cid 存在用户表里,注册时写一次就不管了。三个月后这批用户全部静默收不到消息,而接口照样返回 success。

幂等投递:唯一索引比 if 判断可靠 ​

幂等(idempotency)在推送里的落点是「同一次投递不产生两条记录」。做法是在 (event_id, channel, target) 上建唯一索引,插入失败即视为已投递过。

反例是在内存里写 if (sent) return。云函数是无状态的,每次冷启动都是一张白纸,这个标记活不过一次调用。

到达漏斗:把「没到」切成五段 ​

到达漏斗(delivery funnel)是把投递过程切成已提交、已受理、已下发、已展示、已点击五段,每段有各自的指标和病因。排查不靠猜,靠确定消息在哪一段消失。

反例是只看接口返回码。返回码只覆盖前两段,后面三段的数据来自厂商回执,不配回执地址的话,后台看起来永远全成功。

动手实践 ​

第一步:给云函数装上扩展库 ​

扩展库不会自动带进来,这是新手第一处卡住的地方。改云函数目录下的 package.json:

json
{
  "name": "notify-send",
  "main": "index.js",
  "extensions": {
    "uni-cloud-push": {}
  }
}

运行结果:云函数打包日志里出现 uni-cloud-push 依赖解析记录,函数体积增加若干 MB。少了这段 extensions,运行时 uniCloud.getPushManager 直接返回 undefined,报错位置在业务代码里,很容易误判成写法问题。

第二步:网关先抢幂等键,再发消息 ​

网关只做三件事:取模板、抢幂等键、按通道发送。业务服务不判断平台,渠道列表来自模板配置。

js
// uniCloud-aliyun/cloudfunctions/notify-send/index.js
// 前提:package.json 已开启 uni-cloud-push 扩展库;HBuilderX 3.5.1+
'use strict'
const { appId } = require('./config.json') // 云函数私有配置,不下发前端
const db = uniCloud.database()
const push = uniCloud.getPushManager({ appId })

// 唯一索引建在 (event_id, channel, target) 上
async function claim(eventId, channel, target) {
  try {
    await db.collection('notify-log').add({
      event_id: eventId, channel, target,
      status: 'sending', create_time: Date.now()
    })
    return true
  } catch (e) {
    if (/duplicate key|E11000/i.test(String(e.message))) return false // 已投递过
    throw e
  }
}

exports.main = async (event) => {
  const { eventId, userId, templateCode } = event
  const { data: [tpl] } = await db.collection('notify-template')
    .where({ code: templateCode, enabled: true }).get()
  if (!tpl) return { code: 'TPL_NOT_FOUND', eventId }

  const { data: [device] } = await db.collection('uni-id-device')
    .where({ user_id: userId }).orderBy('last_active', 'desc').limit(1).get()

  for (const channel of tpl.channels) {
    if (!device || !(await claim(eventId, channel, device.push_clientid))) continue
    await push.sendMessage({
      push_clientid: device.push_clientid,
      title: tpl.title,          // 通知栏标题,官方限制 20 字以内
      content: tpl.content,      // 通知栏内容,限制 50 字以内
      payload: { route: tpl.route, eventId }, // 用 Object,离线厂商通道才取得到
      force_notification: tpl.forceNotification === true,
      category: { harmony: 'EXPRESS' } // 鸿蒙通道必填,HBuilderX 4.31+
    })
  }
  return { code: 0 }
}

运行结果:同一个 eventId 连调两次,第二次仍返回 { code: 0 },但 notify-log 不会多出记录——接口幂等、日志不重复。用不存在的 templateCode 调用,返回 { code: 'TPL_NOT_FOUND' } 且不产生任何发送。

第三步:客户端每次启动重新上报 cid ​

cid 会变,所以上报要放在启动路径上,并且覆盖旧值而不是追加。

uts
// uni_modules/push-bind/utssdk/app-harmony/push.uts
// 鸿蒙侧 uni-push 客户端 API 需要 HBuilderX 4.31 及以上
export function bindPush(userId : string) : void {
  uni.getPushClientId({
    success: (res) => {
      uniCloud.callFunction({
        name: 'notify-bind',
        data: { userId, cid: res.cid } // 服务端按 user_id 覆盖写入,同时更新 opendb-device
      })
    },
    fail: (e) => {
      console.log('bindPush fail: ' + e.errMsg)
    }
  })
}

export function listenPush() : void {
  uni.onPushMessage((res) => {
    // type 只有两个值:receive(收到消息)与 click(点击通知栏唤起)
    console.log('push event: ' + res.type)
  })
}

运行结果:App 冷启动后云函数日志出现一条 notify-bind 记录,uni-id-device.push_clientid 与手机侧拿到的 cid 一致;卸载重装后 cid 变化,同一条记录被覆盖为最新值,旧 cid 不再收到消息。若未在 manifest.json 启用 uni-push 2.0,fail 会返回 getPushClientId:fail register fail,错误码为 1。

第四步:按漏斗配好观测 ​

三条链路的触达前提差异先摆在表里,联调时按这张表对号。

维度微信订阅消息App Push(uni-push 2.0)鸿蒙通知
触达前提用户点击授权,一次授权一条已安装 + 通知权限 + 厂商通道注册成功通知权限 + 应用权限声明
服务端入口subscribeMessage.send,需 access_tokenuni-cloud-push 的 sendMessage同 App,由 uni-push 路由
载荷结构模板字段,thing 类有字符上限title / content / payload同 App,另需 category
主要失败原因未订阅、额度耗尽、43101回执未配、ROM 杀后台、cid 失效权限未申请、基座不含模块

再按五段切分指标:

阶段观测指标典型病因定位手段
已提交网关调用成功率模板编码错、参数缺失云函数日志 + notify-log
已受理返回 taskId 非空cid 失效、厂商通道未配控制台「故障排查 - 状态查询」
已下发厂商回执到达数回执未配,数据恒为 0华为 / 荣耀 / vivo / 魅族后台
已展示通知栏曝光ROM 限制后台弹出、省电策略系统「后台弹出界面」权限
已点击点击率落地页 404、参数丢失客户端埋点 + 路由兜底

第三行最容易是空的。华为、荣耀、vivo、魅族四个渠道必须配回执地址才会产生到达数据,地址由个推提供(华为 https://thirdrcp-hz.getui.com/hw,荣耀 /ho,魅族 /mz,vivo 是另一套域名)。不配回执,后台看起来全成功,因为失败发生在厂商侧,不在你的代码里。

成本上不必紧张:官方给的量级约 0.0000058 元一次(一次云函数调用加最多三次数据库查询),日推十万条约 0.58 元。要防的是循环里误发,不是单价。

常见误解 ​

以为发送接口返回成功就是送达。 其实它只代表网关受理了请求。返回体里 $status 有三种取值:successed_online(在线下发)、successed_offline(离线下发,含厂商通道)、successed_ignore(九十天内不活跃设备不下发)。看到 successed_ignore 才发现「用户其实早就不用了」。

以为各处各自调 /cgi-bin/token 没问题。 其实多次刷新会互相顶掉,表现为随机 40001。正确做法是统一走 /cgi-bin/stable_token(grant_type=client_credential,可传 force_refresh=false),全站只留一个刷新者。

以为在线和离线对客户端是同一件事。 其实在线走 socket,不建通知栏,onPushMessage 能拿到 payload;离线走厂商通道,客户端监听不到内容,只有点击唤起才拿得到。前台收 socket、后台收通知栏、杀进程后冷启动点击,三种路径必须各测一遍。

小结 ​

  1. 推送是《支付与交易:多端支付集成与对账》那条支付链路的下游:业务只产事件,网关负责取模板、抢幂等键、按通道发送。
  2. 三条链路的触达前提无法统一,能统一的只有服务端的事件模型、模板、幂等与日志。
  3. 订阅额度是账户不是开关,一次授权换一条,弹窗时机放在用户刚完成一个有后续动作的操作之后。
  4. 幂等落在数据库唯一索引上,落在内存里的标记活不过一次云函数调用。
  5. 排查按五段漏斗走,第三段的下发数据要靠厂商回执,不配就永远是零——这也是《性能优化:setData、长列表与首屏加载》讲性能时反复出现的那句话:没埋点就没有事实。

相关主题 ​

推送解决了「通知送达」,但用户点开应用之后,还要面对另一类问题:地铁里、电梯里、会场里,网络时通时断。相关文章讲离线优先——缓存怎么失效、写操作怎么排队、多端同时改一条数据时听谁的。