做后端开发这些年我最大的感受是短信能搞定验证码但在 App 消息触达这件事上短信又贵又慢还容易被用户当成垃圾信息。真正让我下定决心把推送系统彻底搞清楚是一个订单超时赔付的告警场景——用户下单后收不到任何提醒客诉量直接翻倍。那个项目技术栈偏 Java客户端覆盖 Android 和 iOS团队最后选的是极光推送JPush。这篇文章就聊聊我在这套体系里的上手全过程Java 后端怎么最快接起来Android、iOS、鸿蒙这些端怎么配合以及全平台适配时最容易翻车的地方都在哪。适合谁看正在做 Java 后端、对消息推送还不熟或者正准备给项目做推送选型的开发者。我会尽量少聊没用的概念把能直接照抄的配置和代码摆出来。1. 为什么推送要交给 JPush整体设计思路与数据流向1.1 自己搭推送通道为什么划不来很多人第一次接到“做个推送”的需求第一反应是自己写一个长连接服务。除非你们公司有专门的 IM 团队否则我不建议这么干。移动端长连接的坑不是“难写”而是“写完还得长期养”。系统要维护心跳、处理断线重连、在进程被杀后靠系统通道拉起还要考虑不同厂商对后台进程的限制。这一套做下来比业务代码复杂得多而且线上出问题的时候特别难排查。另外还有离线消息。用户根本不打开 App 的那段时间消息得先存下来等用户下次上线再补发如果你有几十万甚至上千万活跃用户离线消息的存储和分发就变成了一个分布式问题。还要统计送达、展示、点击这些回执数据又得跟各个厂商通道打通。这些需求不是不能自己实现但投入产出比非常低开发周期可能比主业务还长。极光推送这类第三方服务本质上把“和移动端保持长连接、把消息分发到不同厂商通道、统计回执”这些脏活接了过去。后端只做一件事决定给谁发、发什么内容、何时发。这就是我选 JPush 的核心理由也更贴合 Java 后端团队“只关心业务逻辑”的定位。1.2 JPush 在后端生态中的定位如果说你的后端服务是消息的生产者客户端是消费者那 JPush 更像是那个投递员。你不需要关心用户当前是在 Android 还是 iOS也不需要关心他此刻是在 App 前台、后台还是系统重启后你只负责告诉投递员目标是谁消息是什么。从 API 结构也能看出这套设计。发送请求里包含platform、audience、notification三段platform决定发到哪些平台audience决定发给哪些人notification决定消息长什么样。后面写代码的时候你会频繁看到这三个概念理解了它们看官方文档会轻松很多。需要注意的是JPush 不是数据库不要把用户资料或业务状态存到推送服务里。它只理解registrationId、alias、tag这些面向推送的目标概念。业务后端应该维护好用户 ID 和这些推送目标之间的映射关系这层关系建好了推送代码才会干净。1.3 从客户端注册到服务端下发一次推送的完整链路先走一遍完整链路后面对代码会更有感觉。客户端安装 App 后JPush SDK 会自动向极光服务器注册得到一个唯一标识registrationId。客户端需要把这个 ID 交给业务后端保存同时大家约定一个alias比如userId1024绑定到这个客户端。这样后端推送时就不用每次去数据库翻registrationId。当后端要推送时构造一个PushPayload指定平台、目标、通知内容然后调用 HTTP 接口。极光服务收到请求后会先做合法性校验和频控再把消息下发到对应通道Android 端如果 App 在线走 JPush 自己维护的长连接如果 App 被杀走厂商通道小米、华为、OPPO、vivo、荣耀等。iOS 端走苹果 APNs。鸿蒙端走鸿蒙系统推送服务。客户端收到消息后会回调给 App 的业务层并按配置展示通知栏消息或交给 App 处理。后端能看到的回执包括送达数、展示数、点击数。设计系统时一定要把msg_id留好后面排查问题全靠它。2. Java 后端接入实操配置、初始化与发送消息2.1 创建应用与准备三件套在极光控制台创建应用后会分配一个 AppKey再生成一个 Master Secret。如果把 AppKey 看成公钥Master Secret 就是私钥。Master Secret 一旦泄露别人就能冒用你的身份给所有用户发消息所以务必放到 Nacos、KMS 这类配置中心不要硬编码进代码仓库。创建应用时有两项特别容易填错Android 包名和 iOS Bundle ID。这两项必须和客户端实际打包时保持一致尤其 Android 包名后续厂商通道审核会校验。如果开发中期改了包名整个推送链路都会断客户端 SDK 初始化就会失败。控制台里还有一些跟推送强相关的设置通知栏权限模板、厂商通道上传、iOS 证书/密钥。这些虽然属于客户端或运维的工作但后端最好心里有数否则线上报错时不知道去哪里看。2.2 Maven 依赖与 JPushClient 初始化Java 后端集成主要靠jpush-client这个库。在pom.xml里加依赖dependency groupIdcn.jpush.api/groupId artifactIdjpush-client/artifactId version3.6.0/version /dependency版本号以 Maven 中央仓库的最新版为准不同版本的 API 会有细微差异。初始化很简单我喜欢做成配置类这样整个应用只维护一个客户端实例Component public class JPushConfig { Value(${jpush.app-key}) private String appKey; Value(${jpush.master-secret}) private String masterSecret; Bean public JPushClient jPushClient() { return new JPushClient(masterSecret, appKey); } }对应的配置文件jpush: app-key: 你的AppKey master-secret: 你的MasterSecretJPushClient构造时可以指定连接超时、读取超时、最大重试次数。线上我建议把超时时间显式配小一点比如连接 3 秒、读取 10 秒不要让默认值拖住 HTTP 线程。另外JPushClient本身是线程安全的整个服务保持单例就够了千万不要每次发消息都 new 一个实例既浪费资源又容易触发连接数问题。2.3 用代码发出第一条推送来个最简单的需求给所有设备发一条通知。JPushClient client new JPushClient(masterSecret, appKey); PushPayload payload PushPayload.newBuilder() .setPlatform(Platform.all()) .setAudience(Audience.all()) .setNotification(Notification.alert(您的订单已发货)) .build(); try { PushResult result client.sendPush(payload); System.out.println(result); System.out.println(result.isResultOK()); } catch (APIRequestException e) { System.out.println(HTTP Status: e.getStatus()); System.out.println(Error Message: e.getMsg()); } catch (APIConnectionException e) { System.out.println(网络异常: e.getMessage()); }这里有个新手最容易误解的点sendPush返回成功只代表极光服务端收下了这条推送任务不代表用户手机一定收到了。真正的结果要看后续的送达回执。拿isResultOK()判断“推送是否成功”其实是在判断“请求是否被接受”。异常处理的重点在于区分两种错误。APIRequestException表示请求被极光服务接收但参数校验失败比如目标不存在、频率超限、无权限APIConnectionException表示 HTTP 层出了问题比如超时、DNS 解析失败。两类异常的处理方式完全不同前者要改代码或参数后者可以考虑重试。2.4 别名推送、批量推送与异步处理实际业务里很少给全体用户发消息更多是按用户、按群组发。如果客户端已经把 alias 设成用户 ID服务端可以这样构造PushPayload payload PushPayload.newBuilder() .setPlatform(Platform.android()) .setAudience(Audience.alias(user_1024)) .setNotification(Notification.newBuilder() .setAlert(订单状态已更新) .addPlatformNotification(AndroidNotification.newBuilder() .setTitle(订单提醒) .build()) .build()) .build();注意Audience.alias()支持传多个别名但单次请求的目标数量有上限具体限制看官方文档。如果要给大量用户推送建议分片提交比如每批 500 个别名分批循环发送。后端千万不要在业务线程里同步调用推送接口。推送 API 是远程 HTTP 调用遇到网络抖动可能卡住好几百毫秒线上一般用线程池提交或者更稳妥地把推送任务写到本地表由后台任务拉取发送。用 Spring 的Async时代码可以长这样Async(pushExecutor) public CompletableFuturePushResult sendByAliasAsync(String alias, Notification notification) { PushPayload payload PushPayload.newBuilder() .setPlatform(Platform.all()) .setAudience(Audience.alias(alias)) .setNotification(notification) .build(); try { PushResult result jPushClient.sendPush(payload); return CompletableFuture.completedFuture(result); } catch (APIRequestException | APIConnectionException e) { return CompletableFuture.failedFuture(e); } }如果有失败可以根据异常类型决定是否重试。APIConnectionException建议重试APIRequestException不要盲目重试先把参数和状态看清楚否则重试多少次都是白费。3. 全平台适配要点客户端 SDK 与前后端联调3.1 Android 接入与厂商通道Android 接入除了在 Module 的build.gradle加依赖还要在AndroidManifest.xml里配置 AppKey 元数据和相关权限。只做最小接入的话按官方 SDK 文档走一遍就能跑通。但必须提前认识到JPush 自己的长连接在 Android 上很容易被系统杀掉用户一旦手动杀进程或者系统省电策略介入消息就基本发不到。厂商通道就是借用小米、华为、OPPO、vivo、荣耀这些厂商的系统级推送服务。Android 原生推送的碎片化问题只有靠厂商通道才能缓解。接入方式一般是在各厂商开放平台创建应用拿到 AppID、AppKey、AppSecret再回填到极光控制台客户端引入对应厂商的推送 SDK 依赖并在极光控制台开启各厂商通道。每个厂商的配置入口和审批逻辑都不一样这里不逐一罗列。但后端同学必须理解一个关键点消息下发时JPush 会判断设备是否在线、厂商通道是否配置正确再决定走哪条路。如果你发现某类设备总是收不到消息先去查厂商通道配置文件而不是急着翻业务代码。3.2 iOS 的 APNs 配置与推送参数iOS 端相对简单但对证书的要求很严格。在极光控制台上传 APNs 证书或 .p8 密钥时要分清开发环境和生产环境。联调的时候用开发证书上架之后走生产。服务端发送 iOS 通知时要通过setApnsProduction(true/false)告诉极光走哪个 APNs 环境很多团队第一次联调都会栽在这一步。Java 后端构造 iOS 通知可以这样写Notification notification Notification.newBuilder() .setAlert(新消息来了) .addPlatformNotification(IosNotification.newBuilder() .setSound(default) .setBadge(1) .addExtra(from, order) .build()) .build();如果团队还在开发阶段忘了把setApnsProduction设为 false开发机将会收不到任何推送。这不是极光的问题是 APNs 开发环境和生产环境隔离导致的。还要提醒客户端同学必须在 AppDelegate 里先申请通知权限否则无论服务端怎么发通知栏都不会弹出来。3.3 鸿蒙、小程序、H5 与桌面端的取舍现在的“全平台”概念比几年前复杂多了。鸿蒙、小程序、H5、PC 桌面端每个端的能力边界完全不一样。极光推送本身支持 Android、iOS、鸿蒙以及部分厂商生态设备对原生平台适配得相当好。如果项目里有鸿蒙客户端极光也有对应的推送方案服务端 API 基本不用变JPush 会根据设备类型自动路由。但小程序和 H5 要冷静处理。微信小程序有独立的订阅消息体系官方并不建议在小程序里塞第三方推送 SDKH5 页面更适合用浏览器 Notification API 和 Web Push。硬把原生推送的思路套到这些端上反而会带来兼容性麻烦。所以做全平台适配时更合理的方式是业务后端提供一个统一的发送接口内部判断目标用户所属平台再决定调用 JPush 还是其他通道。换句话说全平台适配不等于一套 API 打天下而是让上层业务感知不到平台差异。3.4 前后端如何约定推送接口在前后端分离项目里前端如何让后端知道这台设备我习惯的约定是这样的App 启动后客户端拿到registrationId调用业务后端接口上报。用户登录成功后客户端调用 JPush 的setAlias(userId)后端同时保存一份用户 ID 和registrationId的关联。用户退出登录时客户端调用deleteAlias后端异步清理映射关系。接口伪代码示意// 客户端上报 POST /api/push/register { userId: 1024, platform: android, registrationId: 1900abc123 }后端收到后建立或更新映射表。推送时优先用 alias如果 alias 查不到再用registrationId。这里要注意多设备场景一个用户可能同时登录手机和平板数据库里应该保存多行registrationId。推送时要么发全量设备要么按设备类型筛选别把旧设备忽略掉否则用户换手机后还会收到旧设备的推送。4. 上线后最容易踩的坑与排查实战4.1 常见问题速查表先给一个速查表都是我实际遇到过或者帮同事排查过的问题。遇到推送异常时建议先对照表格定位方向再细查日志。问题现象大概率原因处理办法Android 在线收不到registrationId 没拿到或传错检查 SDK 初始化日志确认前台注册和回调Android 杀进程后收不到厂商通道未配置补齐厂商后台配置和 channel ID推送返回成功但送达为 0目标设备离线且无可用通道查厂商通道回执、用户在线状态iOS 收不到APNs 环境或证书不匹配区分生产/开发环境检查 apnsProduction点击通知没跳转前端路由或 action 不匹配用 extra 携带页面路径前端处理点击事件自定义消息收不到App 进程不在自定义消息不保证实时改用通知栏消息这个表看着简单但每行背后都是一整段排查故事。下面展开讲一个真实案例。4.2 “发送成功但用户收不到”排查实录一次促销活动后台显示推送成功但运营反馈很多用户没收到。第一步先拿到msg_id。如果代码里把PushResult的msg_id打进了日志直接去控制台搜没打的话日志里那段推送入参也可以当成线索。第二步在极光控制台找到这条消息详情看送达数、展示数、点击数的漏斗。那次问题很快暴露送达数远大于展示数说明消息已经到了设备但通知栏没有弹出来。再往下查发现客户端在华为手机上没配厂商通道进程在后台时JPush 的长连接被系统挂起消息只能走厂商通道而厂商通道没配所以只有在线设备能正常展示。第三步打开客户端 SDK 的 debug 日志确认onNotification回调有没有执行再检查系统通知权限是否被用户手动关闭。那次最后是在华为开发者平台补配了推送服务回填到极光控制台后杀进程场景才恢复正常。整个过程最花时间的反而不是查代码而是找到日志入口。所以从项目一开始就统一msg_id、userId、task_no的日志规范能省下大量排查时间。4.3 别名、标签与自定义消息的使用误区setAlias有一个很隐蔽的时序问题客户端调用后立即向服务端发消息服务端马上用 alias 推送极光那边可能还没完成绑定导致报“目标不存在”。SDK 的setAlias回调里有成功和失败结果一定要等回调成功后再把状态同步给后端。标签tag和别名alias的语义不同。别名是一对多适合定位具体用户标签更适合做用户分群比如把“VIP”用户或“灰度体验”用户打上一个标签。给用户打标签时如果要替换整组标签注意接口是全量覆盖还是增量更新文档里两种都有用错会造成标签数据紊乱。自定义消息和通知栏消息是两回事。通知栏消息一定能在通知栏展示自定义消息只是把内容透传给 AppApp 不处理就没有任何表现。进程被杀时自定义消息基本无法实时到达。所以像“订单支付成功”这种强提醒应该用通知栏消息不要为了省事把业务逻辑绑在自定义消息上否则用户永远感知不到。5. 迈向生产环境的工程化实践5.1 在 Spring Boot / 若依框架里接入推送如果项目是基于 Spring Boot 或若依RuoYi这类后台管理系统搭建的推送接入可以做得更整齐。常见做法是把推送封装成一个PushService暴露sendToUser、sendToUsers、sendToTag方法Controller 层只接收参数不直接面对PushPayload。若依这类前后端分离项目权限体系已经比较完善可以直接在/api/push下建一个发送接口前端 Vue 页面通过异步请求调用。这里要谨慎处理接口权限别让人拉个接口就能给全体用户发广告。代码结构大致分四层- PushService业务封装负责组装 PushPayload - PushController对外暴露 /api/push/send 接口 - PushTask负责定时任务和失败重发 - PushCallback接收客户端上报的 registrationId这样拆分之后Vue 前端只关心接口的入参和返回不用关心 JPush 的细节后端同学改推送实现时也不会影响前端联调。5.2 推送任务的幂等、限流与失败补偿把推送引入异步任务后就要考虑两个问题重复发送和失败重试。重复发送很好理解用户下单后消息没发成功或超时补偿任务又扫到原始订单再发一遍同一用户收到两条相同通知。解决办法是给推送任务建一张唯一键表比如订单号加事件类型加用户 ID发送前先查重或者用 Redis 的setnx做幂等控制。失败重试要区分异常类型。网络超时可以重试但参数错误、audience 非法这种重试也没用。重试要加指数退避别在高峰时段集中重扫。任务表建议至少记录这几个字段CREATE TABLE push_task ( id BIGINT PRIMARY KEY AUTO_INCREMENT, task_no VARCHAR(64) NOT NULL, user_id BIGINT NOT NULL, title VARCHAR(128), content VARCHAR(512), status TINYINT COMMENT 0待发送 1成功 2失败, msg_id VARCHAR(64), retry_count INT DEFAULT 0, next_execute_at DATETIME, create_time DATETIME, UNIQUE KEY uk_task_no (task_no) );每次发送前把task_no和msg_id打出来后台任务每几秒扫一次把“下次执行时间到期且重试次数未达上限”的任务捞出来重新发送。这样就算极光服务偶尔抖动推送任务也不会丢。5.3 推送数据的监控、统计与灰度策略推送不是发出去就结束了还要看收到率、点击率。极光控制台本身有送达、展示、点击统计但生产环境最好把关键指标对接到自己的监控系统。比如每天跑一个任务从数据库里捞当天推送任务和msg_id再通过极光查询接口获取送达、展示、点击数据汇总出各个模板的触达效果。上线新模板时我习惯先做小范围灰度选一批内测用户或指定标签观察展示数和点击率再放量。灰度不止是改代码更要确认 alert 文案、标题、跳转链接没有出问题。还有延时和频控监控。如果某次推送的送达耗时突然变高多半是厂商通道或极光侧出现异常需要及时告警。这部分的工程价值往往比发送本身更大毕竟用户感受到的是“消息到底来没来、快不快”。最后再分享一个小习惯我在项目里要求每条推送都必须在日志里打上msg_id、user_id、task_no三个字段。前期觉得啰嗦后期排查线上问题全靠这串关联。消息推送看着简单真正难的是让它在复杂链路里不出错。希望这篇教程能帮你把 Java 后端接入 JPush 这件事一次做对少踩几个我已经帮你踩过的坑。