消息与推送:订阅消息、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:
{
"name": "notify-send",
"main": "index.js",
"extensions": {
"uni-cloud-push": {}
}
}运行结果:云函数打包日志里出现 uni-cloud-push 依赖解析记录,函数体积增加若干 MB。少了这段 extensions,运行时 uniCloud.getPushManager 直接返回 undefined,报错位置在业务代码里,很容易误判成写法问题。
第二步:网关先抢幂等键,再发消息
网关只做三件事:取模板、抢幂等键、按通道发送。业务服务不判断平台,渠道列表来自模板配置。
// 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 会变,所以上报要放在启动路径上,并且覆盖旧值而不是追加。
// 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_token | uni-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、后台收通知栏、杀进程后冷启动点击,三种路径必须各测一遍。
小结
- 推送是《支付与交易:多端支付集成与对账》那条支付链路的下游:业务只产事件,网关负责取模板、抢幂等键、按通道发送。
- 三条链路的触达前提无法统一,能统一的只有服务端的事件模型、模板、幂等与日志。
- 订阅额度是账户不是开关,一次授权换一条,弹窗时机放在用户刚完成一个有后续动作的操作之后。
- 幂等落在数据库唯一索引上,落在内存里的标记活不过一次云函数调用。
- 排查按五段漏斗走,第三段的下发数据要靠厂商回执,不配就永远是零——这也是《性能优化:setData、长列表与首屏加载》讲性能时反复出现的那句话:没埋点就没有事实。
相关主题
推送解决了「通知送达」,但用户点开应用之后,还要面对另一类问题:地铁里、电梯里、会场里,网络时通时断。相关文章讲离线优先——缓存怎么失效、写操作怎么排队、多端同时改一条数据时听谁的。