跳到主要内容

短信邮件通知

引用文件

本文引用的文件

目录​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与可靠性
  8. 故障排查指南
  9. 结论
  10. 附录：API 接口清单

简介​

本文件面向“短信邮件通知系统”的设计与实现，覆盖短信验证码、邮件发送、站内通知三大通信能力。文档从数据模型、消息发送机制、模板管理、状态监控与失败重试等方面进行系统性梳理，并提供关键流程的时序图与类图，帮助开发者快速理解与落地。

项目结构​

通知子系统主要分布在 system 模块的 biz 层，配合 infra 模块的消息队列生产者，以及多数据库方言下的表结构定义。核心目录与职责如下：

  • service 层：短信、邮件、站内通知的服务接口与实现
  • mq 生产者/消费者：基于 Spring Event 的异步解耦
  • controller vo：管理后台的增删改查与发送请求体
  • sql：各数据库方言下的通知相关表结构

Mermaid Diagram Code:

graph TB
subgraph "System 模块"
S_SMS["短信服务<br/>SmsSendService"]
S_MAIL["邮件服务<br/>MailSendService"]
S_NOTIFY["站内通知服务<br/>NotifySendService/NotifyTemplateService"]
C_SMS["短信渠道服务<br/>SmsChannelService"]
P_SMS["短信生产者<br/>SmsProducer"]
P_MAIL["邮件生产者<br/>MailProducer"]
CON_SMS["短信消费者<br/>SmsSendConsumer"]
end
subgraph "Infra 模块"
MQ["消息队列<br/>Spring Event"]
end
subgraph "数据库"
T_SMS["短信日志表<br/>system_sms_log"]
T_MAIL["邮件日志表<br/>system_mail_log"]
T_NOTIFY_TPL["站内通知模板表<br/>system_notify_template"]
T_NOTIFY_MSG["站内通知消息表<br/>system_notify_message"]
end
S_SMS --> P_SMS --> MQ
MQ --> CON_SMS
S_MAIL --> P_MAIL
S_NOTIFY --> T_NOTIFY_TPL
S_NOTIFY --> T_NOTIFY_MSG
S_SMS --> T_SMS
S_MAIL --> T_MAIL

图表来源

章节来源

核心组件​

  • 短信发送链路：服务层接口 → 生产者发布事件 → 消费者异步执行 → 短信通道客户端 → 第三方短信网关
  • 邮件发送链路：服务层接口 → 生产者发布事件 → 邮件账号配置 → 第三方 SMTP 服务器
  • 站内通知链路：模板校验与参数校验 → 内容格式化 → 写入站内通知消息表 → 前端拉取展示

章节来源

架构总览​

通知系统采用“服务层 + 消息队列 + 外部通道”的解耦架构，确保发送过程异步化、可扩展、可观测。

Mermaid Diagram Code:

sequenceDiagram
participant API as "业务接口"
participant Svc as "通知服务层"
participant Prod as "消息生产者"
participant MQ as "消息队列"
participant Cons as "消息消费者"
participant Chan as "短信/邮件通道"
API->>Svc : "调用发送接口"
Svc->>Prod : "发布发送事件"
Prod->>MQ : "publishEvent(...)"
MQ-->>Cons : "事件投递"
Cons->>Svc : "doSendXxx(message)"
Svc->>Chan : "调用第三方通道"
Chan-->>Svc : "返回发送结果"
Svc-->>API : "返回发送日志编号"

图表来源

详细组件分析​

短信验证码​

  • 场景枚举：定义了会员与后台用户的多种短信场景，便于按场景选择模板与风控策略
  • 发送接口：支持按用户类型与手机号发送，内部完成模板校验、参数校验与日志编号返回
  • 消息模型：封装发送所需的渠道、模板与参数
  • 生产者/消费者：通过 Spring Event 解耦，消费者异步执行真实发送
  • 通道服务：提供短信通道的增删改查与客户端获取

Mermaid Diagram Code:

classDiagram
class SmsSendService {
+sendSingleSms(...)
+sendSingleSmsToAdmin(...)
+sendSingleSmsToMember(...)
+doSendSms(message)
+receiveSmsStatus(channelCode, text)
}
class SmsProducer {
+sendSmsSendMessage(logId, mobile, channelId, apiTemplateId, params)
}
class SmsSendMessage {
+Long logId
+String mobile
+Long channelId
+String apiTemplateId
+KeyValue[]String,Object~~ templateParams
}
class SmsSendConsumer {
+onMessage(message)
}
class SmsChannelService {
+createSmsChannel(req)
+updateSmsChannel(req)
+deleteSmsChannel(id)
+getSmsClient(code)
}
SmsSendService <|.. SmsSendServiceImpl
SmsProducer --> SmsSendMessage
SmsSendConsumer --> SmsSendService
SmsChannelService --> SmsSendService : "获取通道客户端"

图表来源

章节来源

邮件发送​

  • 发送接口：支持按用户类型与邮箱发送，内部完成模板校验、参数校验与日志编号返回
  • 消息模型：封装发送所需的账号、标题、内容与模板参数
  • 生产者：发布邮件发送事件
  • 控制器 VO：定义邮件账号的创建/修改参数（主机、端口、SSL/TLS 开关）

Mermaid Diagram Code:

classDiagram
class MailSendService {
+sendSingleMail(...)
+sendSingleMailToAdmin(...)
+sendSingleMailToMember(...)
+doSendMail(message)
}
class MailProducer {
+sendMailSendMessage(logId, mail, accountId, nickname, title, content)
}
class MailSendMessage {
+Long logId
+String mail
+Long accountId
+String nickname
+String title
+String content
}
MailSendService <|.. MailSendServiceImpl
MailProducer --> MailSendMessage

图表来源

章节来源

站内通知​

  • 发送接口：支持管理员与会员两类用户，内部完成模板校验、参数校验与消息创建
  • 模板服务：负责模板的增删改查、分页、缓存与内容格式化
  • 消息服务：负责站内通知消息的分页、查询、未读统计、标记已读等

Mermaid Diagram Code:

classDiagram
class NotifySendService {
+sendSingleNotifyToAdmin(userId, code, params)
+sendSingleNotifyToMember(userId, code, params)
+sendSingleNotify(userId, userType, code, params)
}
class NotifyTemplateService {
+createNotifyTemplate(req)
+updateNotifyTemplate(req)
+deleteNotifyTemplate(id)
+getNotifyTemplate(code)
+getNotifyTemplatePage(page)
+formatNotifyTemplateContent(content, params)
}
class NotifyMessageService {
+getMyNotifyMessagePage(page, userId, userType)
+getNotifyMessage(id)
+getUnreadNotifyMessageList(userId, userType, size)
+getUnreadNotifyMessageCount(userId, userType)
+updateNotifyMessageRead(ids, userId, userType)
+updateAllNotifyMessageRead(userId, userType)
}
NotifySendService <|.. NotifySendServiceImpl
NotifySendServiceImpl --> NotifyTemplateService
NotifySendServiceImpl --> NotifyMessageService

图表来源

章节来源

短信发送流程（时序）​

Mermaid Diagram Code:

sequenceDiagram
participant Caller as "调用方"
participant Svc as "SmsSendService"
participant Prod as "SmsProducer"
participant MQ as "Spring Event"
participant Cons as "SmsSendConsumer"
participant Send as "doSendSms(...)"
Caller->>Svc : "sendSingleSms(...)"
Svc->>Prod : "sendSmsSendMessage(logId, mobile, channelId, apiTemplateId, params)"
Prod->>MQ : "publishEvent(SmsSendMessage)"
MQ-->>Cons : "onMessage(message)"
Cons->>Svc : "doSendSms(message)"
Svc->>Send : "执行真实发送"
Send-->>Svc : "返回发送结果"
Svc-->>Caller : "返回日志编号"

图表来源

站内通知流程（时序）​

Mermaid Diagram Code:

sequenceDiagram
participant Caller as "调用方"
participant Svc as "NotifySendService"
participant Tpl as "NotifyTemplateService"
participant Msg as "NotifyMessageService"
Caller->>Svc : "sendSingleNotify(userId, userType, code, params)"
Svc->>Tpl : "getNotifyTemplateByCodeFromCache(code)"
Tpl-->>Svc : "返回模板"
Svc->>Svc : "校验模板状态与参数"
Svc->>Tpl : "formatNotifyTemplateContent(content, params)"
Tpl-->>Svc : "返回格式化内容"
Svc->>Msg : "createNotifyMessage(...)"
Msg-->>Svc : "返回消息ID"
Svc-->>Caller : "返回消息ID"

图表来源

依赖关系分析​

  • 低耦合：服务层仅依赖消息模型与 VO，不直接依赖外部通道，通过生产者/消费者解耦
  • 可扩展：短信/邮件通道通过 SmsChannelService 提供客户端抽象，便于接入不同厂商
  • 可观测：邮件日志表与短信日志表均包含发送状态、异常、消息ID等字段，便于监控与重试

Mermaid Diagram Code:

graph LR
S_SMS["SmsSendService"] --> P_SMS["SmsProducer"]
S_MAIL["MailSendService"] --> P_MAIL["MailProducer"]
P_SMS --> M_SMS["SmsSendMessage"]
P_MAIL --> M_MAIL["MailSendMessage"]
C_SMS["SmsChannelService"] --> S_SMS
S_NOTIFY["NotifySendServiceImpl"] --> TPL["NotifyTemplateService"]
S_NOTIFY --> MSG["NotifyMessageService"]

图表来源

性能与可靠性​

  • 异步解耦：通过消息队列异步发送短信/邮件，避免阻塞主线程，提升吞吐
  • 缓存模板：站内通知模板从缓存获取，减少数据库访问
  • 参数校验：发送前严格校验模板参数，降低下游失败率
  • 状态监控：邮件/短信日志表记录发送状态、异常与消息ID，便于重试与审计
  • 失败重试：建议在消费者侧对第三方通道异常进行幂等与重试控制（当前接口默认不支持批量发送，可按需扩展）

[本节为通用指导，无需列出具体文件来源]

故障排查指南​

  • 短信回调：提供回调接收入口，用于接收第三方通道的状态回传
  • 邮件异常：日志表包含 send_exception 字段，便于定位发送失败原因
  • 模板缺失：发送前会校验模板是否存在，缺失将抛出异常
  • 参数缺失：模板参数校验失败会抛出异常，需检查调用方传参

章节来源

结论​

通知系统以“模板 + 消息 + 通道”为核心，通过消息队列实现异步解耦，具备良好的扩展性与可观测性。短信、邮件、站内通知三类能力分别满足不同场景需求，建议结合业务对模板参数、通道配置与重试策略进行精细化治理。

[本节为总结性内容，无需列出具体文件来源]

附录：API 接口清单​

  • 短信发送

    • 发送单条短信给管理后台用户
      • 接口路径：POST /admin-api/system/sms/send-sms
      • 请求体：SmsTemplateSendReqVO
      • 返回：发送日志编号
    • 发送单条短信给会员用户
      • 接口路径：POST /admin-api/system/sms/send-sms-to-member
      • 请求体：SmsTemplateSendReqVO
      • 返回：发送日志编号
    • 发送单条短信给用户（通用）
      • 接口路径：POST /admin-api/system/sms/send-single-sms
      • 请求体：SmsTemplateSendReqVO
      • 返回：发送日志编号

  • 邮件发送

    • 发送单封邮件给管理后台用户
      • 接口路径：POST /admin-api/system/mail/send-mail-to-admin
      • 请求体：MailSendSingleToUserReqDTO
      • 返回：发送日志编号
    • 发送单封邮件给会员用户
      • 接口路径：POST /admin-api/system/mail/send-mail-to-member
      • 请求体：MailSendSingleToUserReqDTO
      • 返回：发送日志编号
    • 发送单封邮件给用户（通用）
      • 接口路径：POST /admin-api/system/mail/send-single-mail
      • 请求体：MailSendSingleToUserReqDTO
      • 返回：发送日志编号

  • 站内通知

    • 发送单条站内信给管理后台用户
      • 接口路径：POST /admin-api/system/notify/send-notify-to-admin
      • 请求体：NotifyTemplateSendReqVO
      • 返回：消息编号
    • 发送单条站内信给会员用户
      • 接口路径：POST /admin-api/system/notify/send-notify-to-member
      • 请求体：NotifyTemplateSendReqVO
      • 返回：消息编号
    • 发送单条站内信给用户（通用）
      • 接口路径：POST /admin-api/system/notify/send-single-notify
      • 请求体：NotifyTemplateSendReqVO
      • 返回：消息编号

  • 短信/邮件通道与账号

    • 短信渠道：创建/更新/删除/分页/详情
    • 邮件账号：创建/更新/删除/分页/详情

[本节为接口概览，具体字段与校验请参考对应 VO 类与控制器定义]

数据模型与表结构​

  • 短信日志表（system_sms_log）

    • 关键字段：模板编码、模板标题、模板内容、模板参数、发送状态、发送时间、发送异常、创建时间等
    • 用途：记录短信发送的全过程，便于监控与重试

  • 邮件日志表（system_mail_log）

    • 关键字段：接收邮箱、模板编码、模板昵称、模板标题、模板内容、模板参数、发送状态、发送时间、发送返回的消息ID、发送异常、创建时间等
    • 用途：记录邮件发送的全过程，便于监控与重试

  • 站内通知模板表（system_notify_template）

    • 关键字段：模板名称、模板编码、发送人名称、模板内容、类型、参数数组、状态、备注、创建/更新/删除时间等
    • 用途：统一管理站内通知模板，支持参数占位符与状态开关

  • 站内通知消息表（system_notify_message）

    • 关键字段：用户ID、用户类型、模板编号、模板编码、模板昵称、模板内容、模板类型、模板参数、已读状态、阅读时间、创建/更新/删除时间等
    • 用途：存储用户收到的站内通知消息，支持分页、未读统计与标记已读

章节来源

用户文档
AI 助手
Agent 列表
请选择一个 Agent 开始对话
AI 问答