通知渠道抽象与统一模型设计：站内信、短信、邮件、Push 工程实践

做过后台系统的人大概都经历过这样一个阶段：最开始只有站内信，业务代码里直接调一个noticeService.send()就完事；后来运营说短信触达率高，加一个短信通道；再后来市场部要发邮件、App 要推 Push，于是每个业务场景里开始出现这样的代码——先判断用户有没有手机号，有就发短信，没有就走站内信，Push 失败再补一条站内信。半年之后，这段逻辑在十几个文件里各有一份变体，谁也不敢删。通知渠道抽象这件事，本质上不是写一个接口那么简单，而是要把站内信、短信、邮件、Push 这四种形态差异极大的通道，收敛到一套可扩展的统一模型里，让业务方只关心"通知谁、通知什么"，不再关心"怎么发出去"。这篇就按我自己落地过的几个版本，把统一模型怎么拆、接口怎么定、扩展点留在哪里、哪些地方容易设计错，一次讲清楚。

1. 通知渠道越加越乱的根源：发送逻辑和业务代码绑在一起

1.1 一个典型“哪里要发就写一段”的通知模块

先看一个特别常见的形态。订单状态变更要通知用户，代码大概长这样：先查用户信息，拿到手机号和邮箱，然后依次调短信客户端、邮件客户端，最后往站内信表里插一条记录。每个客户端都有自己的参数结构、自己的异常类型、自己的超时配置。表面上看是“通知模块”，实际上只是三段互不相关的调用被摆在了同一个方法里。

这种写法在渠道少、场景少的时候问题不大，甚至开发效率还挺高。但只要满足下面任意一个条件，它立刻开始反噬：渠道数量超过三个、通知场景超过十个、或者有人提出“Push 发不出去要降级到站内信”这种需求。因为降级逻辑意味着渠道之间产生了依赖关系，而现在的代码结构里，渠道之间只是并列的几行调用，没有任何地方可以承载“失败之后怎么办”的决策。

我在一个项目里见过更极端的版本：通知逻辑被复制到了七个服务里，每个服务自己维护一份短信模板 ID 的硬编码。运营改一次模板文案，需要发七个工单。这就是典型的把“通道实现”和“业务意图”焊死在一起，后面对任何一方的修改都会牵动另一方。

1.2 把四个渠道的差异摊开：变化点究竟在哪

要抽象，先得承认这四个渠道确实不一样，不能硬掰成一个样子。我把它们的差异列成一张表，这张表基本决定了后面模型怎么设计。

这张表里最容易被忽略的是结果语义这一行。很多人设计接口时把返回值统一定义成“成功/失败”，结果上线之后发现短信明明返回成功，用户根本没收到——因为通道侧返回的只是“已受理”。如果模型里不区分“提交结果”和“送达结果”，后面做重试、做补偿、做数据统计全部会失真。

提示：统一模型的第一步不是找共同点，而是把差异点完整列出来，再决定哪些差异应该被模型吸收，哪些应该留给具体渠道自己处理。

1.3 为什么“抽一个 send 方法”反而更糟

有一种很常见的“伪抽象”：定义一个NotificationService，里面有个send(userId, content, channelType)方法，用 switch 分发到不同渠道。看起来收敛了，实际上问题更多。

第一，参数不够用。邮件需要主题，Push 需要跳转参数，短信需要模板 ID，这些信息塞不进一个content字符串里，于是就开始加参数，加到第八个参数的时候，调用方已经不知道该传什么了。第二，渠道能力被抹平了。站内信可以发三千字，短信只能发七十个字，统一接口却要求所有渠道接受同样的内容，结果就是要么截断，要么在实现里偷偷做转换，行为不可预期。第三，扩展成本没降。加一个新渠道，还是要改那个 switch，还是要改接口定义，所有调用方都要重新编译。

问题的根子在于：这个抽象只统一了入口，没有统一数据模型和生命周期。真正的抽象应该是“业务方描述一条通知的意图，由框架决定用什么渠道、怎么渲染、怎么发、失败怎么办”。入口只是最外面那一层。

2. 统一模型拆三层：消息、渠道、编排策略

2.1 消息模型：四种渠道的共同骨架

我把通知拆成一个“消息对象”，它描述的是意图，不是某个具体渠道的报文。核心字段大致是这些：

public class NotifyMessage { private String messageId; // 全局唯一，用于幂等和追踪 private String bizType; // 业务类型，如 order、account private String sceneCode; // 场景码，如 ORDER_PAID private Long receiverId; // 接收人用户 ID private List<String> channels; // 期望渠道，可为空表示由策略决定 private String templateCode; // 模板编码，按渠道映射 private Map<String, Object> vars;// 模板变量 private Integer priority; // 优先级，影响降级和队列 private String dedupKey; // 去重键，同一键在窗口内只发一次 private Long scheduleAt; // 定时发送时间，空为立即 private Long expireAt; // 过期时间，超时不再发送 private Map<String, Object> ext; // 渠道私有扩展参数 }

这里面有几个字段值得单独说。sceneCode是我强烈建议加的，它把“这条通知是什么业务场景”固化下来，后面做渠道路由、模板映射、频控规则、数据统计全部以它为维度。没有它，你只能靠bizType粗粒度区分，运营想看“支付成功通知的到达率”就无从下手。

dedupKey是另一个高频踩坑点。业务方重试、消息队列重复投递、用户连点两次按钮，都会导致同一条通知发多遍。短信是有成本的，重复发就是真金白银。把去重键放到消息模型里，由框架统一做窗口期去重，比让每个业务方自己保证要可靠得多。窗口期一般按场景配置，验证码类 60 秒，营销类可以到 24 小时。

ext字段是留给渠道私有参数的出口。我一开始很抗拒这个设计，觉得它破坏了模型的纯粹性，但实际落地时发现绕不开——Push 要传厂商通道的角标数，邮件要传回复地址，这些参数没法抽象成通用字段。与其让每个渠道实现去强转一个Object，不如显式留一个扩展槽，并在文档里写清楚：通用能力走标准字段，渠道私有走 ext，且 ext 的 key 必须以渠道编码为前缀，避免不同渠道的 key 打架。

2.2 渠道模型：每个渠道只需回答两个问题

渠道层的设计我走过弯路。最早我定义了一个大而全的接口，里面有send、queryStatus、cancel、getLimit、render一堆方法，结果每个实现类里都有一半方法写着throw new UnsupportedOperationException()。这就是接口设计过肥的典型症状。

后来收敛成两个核心问题：这个渠道能发什么，和这条消息怎么发出去。对应两个方法：

public interface NotifyChannel { String code(); ChannelCapability capability(); SendResult send(ChannelContext context); }

ChannelCapability描述能力边界，包括支持的内容类型、最大长度、是否支持富文本、是否支持定时、是否有回执、单条消息的最大接收人数等。编排层在做路由和降级时，先看能力声明，不合规的直接跳过，而不是发出去再报错。比如用户只填了邮箱没填手机号，短信渠道的能力检查就会返回不可达，编排层自然降级到邮件，不需要在业务代码里写 if-else。

SendResult要区分三种状态：ACCEPTED（已受理）、DELIVERED（已送达，需要回执支持）、FAILED（失败）。再配一个retryable布尔值和错误码。这个设计直接决定了下游的重试逻辑能不能写对——只有FAILED && retryable才进重试队列，ACCEPTED一律不动，避免把“已受理”当成失败反复重投。

至于queryStatus、cancel这类方法，我没有放进主接口，而是拆成可选的扩展接口，实现类按需实现，编排层用instanceof判断是否支持。这样接口保持精简，能力又不会丢失。

2.3 编排层：路由、降级、限频、去重放哪里

这一层是最容易被低估的。很多人把渠道接口定义得很漂亮，然后把路由逻辑散落在业务代码里，等于白抽象。编排层的职责应该完整包含四件事。

路由负责决定一条消息最终走哪些渠道。输入是消息对象和用户画像，输出是渠道列表。策略可以是固定的（消息里指定），可以是按用户偏好（用户设置了只收站内信），也可以是按场景配置（营销类优先 Push，账号安全类短信+邮件双发）。我一般把策略做成配置项，存在配置中心，按sceneCode维度覆盖，避免每次调整都发版。

降级负责在主渠道失败时补发。这里的关键是降级链要有层级和上限，不能无限降。常见的配置是 Push → 站内信 → 短信，但短信必须加开关和日限额，否则一次 Push 服务抖动可能直接把短信费用打爆。我的做法是降级链上每一跳都配独立开关，且默认关闭，需要时手动打开。

限频分两个维度：用户维度和渠道维度。用户维度是“同一个人同一场景一天最多收几条”，渠道维度是“这个渠道每秒最多提交多少条”。前者防骚扰，后者防把第三方接口打挂。限频的计数我放在 Redis 里，用滑动窗口而不是固定窗口，避免临界点双倍放量。

去重就是前面说的dedupKey，在编排层统一做，命中就直接返回“已发送”，不进入渠道实现。

这四件事放在编排层，渠道实现就变得非常薄——只负责把标准消息翻译成通道报文并提交，职责单一，测试也好写。

3. 接口与落地的代码骨架：从定义到模板方法

3.1 渠道接口该暴露哪些字段

除了code()、capability()、send()，我在实际项目里还给渠道接口加了两个方法：render()和validate()。加它们的原因是，渲染和校验这两件事在不同渠道之间差异巨大，但调用时机又是统一的——必须在发送之前完成。

validate()做的是消息级别的合法性检查，比如短信渠道要检查模板变量是否齐全、变量值是否超长；邮件渠道要检查收件地址格式；Push 渠道要检查设备 token 是否还在有效期内。这些检查如果放到send()里做，失败就和网络错误混在一起，没法区分是“参数问题”还是“通道问题”。分开之后，参数问题可以在进入队列前就拦掉，不浪费一次调用。

render()负责把模板编码加变量渲染成渠道实际要发的内容。这里有个设计上的取舍：渲染结果要不要缓存？我的答案是按模板编码加变量哈希做短期缓存，因为很多通知的变量值其实高度重复（比如“您的订单已发货”这类固定文案），缓存能省掉大量模板引擎调用。但要注意变量里如果包含用户隐私信息，缓存 key 要做脱敏处理，不能把手机号直接拼进 key。

接口定完之后，渠道注册用 SPI 机制，每个渠道实现类在META-INF下声明，启动时自动扫描加载，新增渠道不需要改任何注册代码。这一点对后续扩展非常重要，下面第 4 节会详细说。

3.2 模板方法把公共动作收口

渠道接口定义好之后，如果让每个实现类自己去写“参数校验、渲染、频控、埋点、异常归一”，一定会写出七种不同的版本。所以我用一个抽象基类把公共流程收口：

public abstract class AbstractNotifyChannel implements NotifyChannel { @Override public SendResult send(ChannelContext context) { long start = System.currentTimeMillis(); try { validate(context); RenderedContent content = render(context); if (content == null || content.isEmpty()) { return SendResult.skipped("EMPTY_CONTENT"); } SendResult result = doSend(context, content); return result == null ? SendResult.failed("NULL_RESULT", false) : result; } catch (BizException e) { return SendResult.failed(e.getCode(), false); } catch (Exception e) { return SendResult.failed("CHANNEL_ERROR", true); } finally { metrics.record(code(), System.currentTimeMillis() - start); } } protected abstract void validate(ChannelContext context); protected abstract RenderedContent render(ChannelContext context); protected abstract SendResult doSend(ChannelContext context, RenderedContent content); }

这段代码的价值不在语法，而在异常边界的统一。业务异常标记为不可重试，系统异常标记为可重试，所有渠道实现都遵循同一套规则，编排层就不需要给每个渠道写特殊的错误处理。埋点也在这里统一记录耗时，后面做渠道健康度看板时数据直接可用。

render返回null或空内容的场景也要处理。我遇到过模板被运营误删，渲染结果为空，结果短信通道发了一条空短信出去，用户收到一脸懵。后来规定空内容一律标记为SKIPPED，不算失败也不算成功，单独统计。

3.3 四个渠道各自的实现差异

四个渠道的doSend写法差别很大，这也是为什么不能强行统一的原因。

站内信的doSend本质是一次数据库写入，要注意的是未读数的一致性。如果站内信表和用户未读数分开存，写入消息和更新未读数必须在同一个事务里，或者用消息表加计数的最终一致方案。我倾向后者，因为高并发下事务更新同一行用户记录会成为瓶颈，改成写消息后发一条事件，由消费方异步累加未读数，配合定时对账兜底。

短信的doSend要处理模板 ID 映射。业务方传的是templateCode，短信服务商要的是模板 ID，这两者的映射关系必须配置化，不能硬编码。而且模板是有审核状态的，模板被驳回或者下线时，发送要能快速失败并告警，而不是傻傻地重试。变量格式也要特别注意，不同服务商对变量占位符的写法不一样，有的用${code}，有的用#code#，这层转换应该在渠道实现内部完成，不污染消息模型。

邮件的doSend重点是 HTML 渲染和退信处理。HTML 里用户昵称这类变量必须转义，否则一个带尖括号的昵称就能把整个邮件排版搞乱。退信是邮件特有的问题，硬退信（地址不存在）应该把该地址标记为不可用，软退信（邮箱满）可以重试几次。这套逻辑不处理，邮件通道的信誉度会越来越差，最后全进垃圾箱。

Push 的doSend最复杂，因为要面对多设备、多厂商通道。核心是要把“用户”映射到“设备 token 列表”，然后逐设备发送并汇总结果。token 失效是常态，收到失效回执就要及时清理，否则每次发送都在做无用功。另外 Push 的“成功”只是受理成功，真正的展示率要看后续回执，所以这个渠道的SendResult里ACCEPTED状态会占绝大多数，统计口径要和短信区分开。

3.4 渲染层和发送层必须分开

这一条是我踩过坑之后才想明白的。早期我把模板渲染写在渠道实现里，结果出现了两个问题：一是同一个模板要在四个渠道里各写一遍渲染逻辑，文案改一次要改四处；二是想做一个“预览”功能，看看这条通知发出去长什么样，没法做，因为渲染和发送绑死了。

拆开之后，渲染层按sceneCode + channelCode找模板，模板统一管理，支持多语言和多版本。发送层只接收渲染好的内容。预览功能自然就有了——调渲染层拿结果，不调发送层。

模板管理还有个细节：模板变量要有 schema。每个模板声明自己需要哪些变量、什么类型、是否必填。发送前用 schema 校验一遍，缺变量直接失败在入口，而不是发出去一条“尊敬的 ${name}”。这个 schema 还能用来做运营侧的表单，让运营填变量的时候有提示，减少配错。

4. 新增一个渠道要动哪些地方：接入清单与验证方法

4.1 接入清单：从注册到上线

抽象设计得好不好，最直接的检验标准就是“加一个新渠道要改几个文件”。我现在这套结构下，接入一个新渠道（比如企业内部的即时通讯工具）大概是这样一张清单：

七步里没有一步需要改编排层或消息模型，这才是抽象到位的标志。如果接入过程中发现需要给消息模型加字段，那说明前面抽象时漏了共性；如果需要改编排层的 if-else，说明能力声明设计得不够用。

这里有个经验：第一个渠道实现往往会把接口设计的问题暴露出来，但不要急着改接口。等第二、第三个渠道接进来，共性才看得清楚。我第一版接口里有个getMaxLength()方法，后来发现不同渠道对不同内容类型的长度限制不一样，短信纯文本 70 字，但带签名和退订可能只剩 50 字。最后改成能力对象里放一个 map，按内容类型查限制，比单一方法灵活得多。

4.2 灰度、回滚与可观测性

新渠道上线最怕的是“静默错误”——发送没报错，但用户没收到，或者收到了乱码。所以接入清单里必须包含灰度方案。

我的做法是按sceneCode和用户 ID 哈希做灰度，先放 1% 的量，观察三个指标：提交成功率、回执成功率、用户投诉量。提交成功率看通道是否稳定，回执成功率看内容是否合规，投诉量看体验。三个指标都正常再逐步放量。灰度期间保留原渠道作为兜底，一旦指标异常，配置中心一键把流量切回去。

可观测性方面，每条通知从进入到结束要有完整的追踪链路。messageId贯穿始终，日志里带上sceneCode、channelCode、receiverId、result、cost。这些字段不是为了排查单条问题，而是为了做聚合分析——哪个场景的失败率高、哪个渠道的耗时在涨、哪类错误码集中出现。没有这些数据，渠道健康度就是拍脑袋。

告警要设两类：一类是失败率突增，按渠道和场景分别设阈值；另一类是耗时突增，往往是第三方接口变慢的前兆。这两类告警我都在凌晨被叫起来过，虽然难受，但比用户投诉到客服强。

4.3 幂等、重试与回执处理

重试这件事，写起来简单，写对很难。第一个坑是重试放大了重复发送。前面说的dedupKey只能防业务层重复，防不了框架层重试。所以在重试队列里，每个任务要带原始messageId，消费时先查发送记录，已成功的直接丢弃。

第二个坑是重试没有退避。固定间隔重试在通道抖动时会形成脉冲，把刚恢复的通道再打挂。我一般用指数退避加随机抖动，第一次 10 秒，第二次 30 秒，第三次 2 分钟，最多三次。超过三次进死信队列，人工处理。

第三个坑是不区分错误类型就重试。参数错误、模板不存在、用户已退订，这些重试一万次也不会成功，只会浪费资源。所以SendResult里的retryable字段必须由渠道实现准确判断，这需要和各通道的错误码做映射，是个细致活，但省不掉。

回执处理是异步的，要单独设计。短信和 Push 的回执通常通过回调或者主动轮询获取，拿到之后更新发送记录的状态。这里要注意回执的乱序问题——先发的后到、后发的先到都很常见，所以状态更新要用“只允许向前流转”的规则，DELIVERED不能被后来的ACCEPTED覆盖回去。

5. 几个容易设计错的地方与我的处理方式

5.1 渠道不等于消息类型

这是最常见的一个概念混淆。很多人把“验证码”“订单通知”“营销活动”当成渠道类型去设计，结果枚举里混着业务场景和发送通道，越加越乱。正确的切分是：渠道是发送通道（站内信、短信、邮件、Push），消息类型是业务场景（验证码、订单、营销），两者是多对多关系，通过模板映射和路由策略关联。

举个具体例子。“验证码”这个场景可能同时走短信和邮件，取决于用户注册时填了什么；“营销活动”可能走 Push 和站内信，不走短信因为成本高。如果把它们做成同一层级的枚举，这种组合关系就没法表达。分开之后，场景配置里写“优先短信，失败降级邮件”，渠道实现完全不感知业务语义，职责清晰。

这个区分还影响数据统计。按渠道统计能看出通道健康度，按场景统计能看出业务效果，两个维度交叉还能发现“某个场景在某个渠道的成功率异常低”这种问题。混在一起就什么都看不出来。

5.2 重试没做退避，短信被重复扣费

这个坑值得单独说，因为它是真金白银的损失。早期我们的重试是固定 5 秒一次，最多五次。有一次短信服务商那边响应变慢，大量请求超时，重试队列瞬间堆积。更糟的是，超时的请求实际上在服务商那边已经受理了，只是响应没回来。结果就是同一条短信发了三四遍，用户收到一堆重复验证码，费用也翻了几倍。

修复方案有三层。第一层是超时时间要合理，不能设得太短，短信接口的 P99 耗时是多少，超时就应该比它大一些，留出余量。第二层是重试前先查状态，如果通道提供了查询接口，先查再决定要不要重发。第三层是重试必须带退避和抖动，且总次数要少。上线之后同类问题再没出现过。

注意：所有会产生实际成本的渠道（短信、语音），重试策略必须单独配置，且要有日发送量上限兜底。这个上限不是防用户，是防程序 bug。

5.3 站内信和 Push 的“已读”语义不能统一

设计统一模型时，很容易想把“已读状态”做成通用字段，毕竟站内信有已读未读，Push 也有已读。但这两者的语义完全不同。

站内信的“已读”是应用内的状态，用户打开消息列表点开某条，状态就变了，这个状态由我们自己维护，可靠。Push 的“已读”是系统通知栏的状态，很多设备根本不回传，即使回传也延迟很大，而且用户可能直接在通知栏划掉，这算不算已读？语义模糊。

所以我的处理是：已读状态只放在站内信渠道自己的存储里，不进统一模型。统一模型只记录发送状态。如果业务方需要“用户是否看到通知”这个信息，通过站内信的已读状态加 Push 的点击回执综合判断，而不是指望一个通用字段。

类似的还有“撤回”。站内信可以撤回（把消息标记为已删除），短信发出去就收不回，Push 在部分通道可以撤回但有时间窗口。这类能力差异很大的操作，都不应该进统一模型的主干，而是作为渠道的可选扩展能力，用能力声明标记，业务方按需调用。

5.4 模板变量缺失导致整条链路崩溃

最后说一个看起来很小但影响很大的问题。模板渲染时如果变量缺失，不同的模板引擎行为不一样：有的抛异常，有的渲染成空字符串，有的原样输出占位符。如果异常没被捕获，整批消息的发送任务可能全部失败。

我遇到过的情况是，一个批量通知任务里有一条消息的变量缺失，渲染抛异常，异常一路往上冒，把整个批次的消费线程搞挂了，后面几千条消息全部卡住。修复其实很简单，在渲染层做兜底：变量缺失时记录一条告警日志，然后用默认值渲染或者直接跳过这条消息，绝不让单条消息的异常影响批次。

再往前一步，变量校验应该前置。模板配置的时候就声明必填变量，发送前用 schema 校验，缺了直接返回参数错误，连渲染都不进入。这样问题在入口就被拦住，不会传导到后面。

顺带说一个相关的经验：模板变量里不要放用户可控的原始内容直接拼接。邮件正文里的用户昵称要转义，短信变量里的内容要做长度截断，Push 的跳转参数要做编码。这些处理都应该在渲染层统一做，而不是指望每个调用方自己注意。渲染层是最后一道防线，它不做，就没人做了。

这套模型我在两个项目里落地过，第二个项目接入了六个渠道，新增渠道的平均耗时从最初的两三天降到了半天，主要时间花在通道联调和灰度观察上，代码改动量很小。真正花心思的地方其实不在接口定义，而在那些看起来琐碎的地方：重试策略、错误码映射、模板校验、回执乱序。这些细节决定了一套通知系统是“能跑”还是“敢让它跑”。